---
url: 'https://adk.nht.io/developer-tools/eslint-rules/sandbox.md'
description: >-
  The adk-sandbox plugin at @nhtio/adk/batteries/sandbox/lint — three rules that
  turn the sandbox policy's silent fail-opens and gate-free constructions into
  lint findings.
---

# Sandbox battery rules

## LLM summary — Sandbox battery rules

* `import adkSandbox from '@nhtio/adk/batteries/sandbox/lint'`, namespace `adk-sandbox`, three rules, `configs.recommended` sets them at the stated severities.
* `adk-sandbox/no-network-disabled` (`warn`) — `network: { disabled: true }` inside a `SandboxPolicy` means the network restriction is OMITTED, i.e. UNRESTRICTED network.
  Deny-all is `network: {}`.
  Also fires, BY DESIGN, on the same shape nested inside a skills config — e.g. `unsafe.scriptsPermissivePolicy: { network: { disabled: true } }` gets a second finding from `adk-skills/no-unsafe-opt-in` AND one from this rule: the nested section is a real `SandboxPolicy` the battery would derive, so leaving it unflagged would let the same fail-open ride one level down.
* `adk-sandbox/filesystem-read-default-allow` (`warn`) — an `allowRead` list with no broad `denyRead: ['/']` before it. Reads are deny-then-allow, so the allow list re-permits nothing and the whole host stays readable. A `denyRead`-only policy is NOT reported.
* `adk-sandbox/require-gate` (`error`) — `createRunShellCommandTool({…})` / `createEvaluateJavascriptTool({…})` with an object literal containing no `gate`. Both throw `E_SANDBOX_GATE_REQUIRED` at construction. The callee is matched by its resolved export name, so an aliased (`createRunShellCommandTool as mkShell`) or namespace (`tools.createRunShellCommandTool`) spelling is checked identically; a same-named factory from another module is not.
* Conservative by design: spreads, non-literal arguments, dynamic values and unimported-name ambiguity are all left alone rather than guessed at. Each rule's own section lists exactly what it does NOT catch.
* TypeScript wrappers are transparent: `as X`, `satisfies X`, `<X>{…}`, `x!` and parentheses around an argument or property value are looked through, so `{ network: { disabled: true } as const }` and `createRunShellCommandTool({…} as any)` are flagged exactly like the bare literals. An assertion is not an escape hatch here.
* Rules are report-only. Carve out an exception with `// eslint-disable-next-line adk-sandbox/<rule> -- <reason>`.

The sandbox battery's failure modes share a shape: the policy *looks* like it
confines something and does not, and nothing at runtime says so. A `disabled:
true` that reads as "off" and means "unrestricted". An `allowRead` list that
reads as "only these paths" and permits the whole host. A gated tool that throws
on its first production construction because nobody passed a gate.

All three are decidable from the source text, so they belong in lint rather than
in a stack trace.

## Install and register

```ts
import adkSandbox from "@nhtio/adk/batteries/sandbox/lint";

export default [
  {
    plugins: { "adk-sandbox": adkSandbox.plugin },
    rules: adkSandbox.configs.recommended.rules,
  },
];
```

`eslint` and `@typescript-eslint/utils` are optional peer dependencies of
`@nhtio/adk`; the sandbox battery never imports this module at runtime. Every
rule here is report-only — no autofix, because each finding is a policy decision
and the linter is not the one who gets to make it.

## `adk-sandbox/no-network-disabled` — warn

`network: { disabled: true }` does not turn the network off. The field name says
it does; the implementation omits the SRT network configuration key entirely,
and an absent network rule is not a restrictive rule — it is no rule at all. The
sandbox gets **unrestricted** network access, which is the exact opposite of what
the field reads as, and there is no runtime error, no warning, and no visible
difference in the code.

Deny-all is `network: {}` — an empty allow-list. An allow-list is
`network: { allowedDomains: [...] }`.

```ts
// flagged
const policy: SandboxPolicy = {
  filesystem: { denyRead: ["/"], allowRead: ["/workspace"] },
  network: { disabled: true }, // UNRESTRICTED network
};

// correct
const policy: SandboxPolicy = {
  filesystem: { denyRead: ["/"], allowRead: ["/workspace"] },
  network: {},
};
```

**What it does not catch.** The rule needs to recognise the object as a sandbox
policy, so it only inspects an object literal that carries the sibling
`filesystem` key or is annotated `SandboxPolicy`. An unrelated
`{ network: { disabled: true } }` in some other API is never flagged. It also
ignores `disabled: false`, dynamic values (`disabled: isDisabled`) and any
policy assembled through a spread. A TypeScript wrapper (`as const`,
`satisfies SandboxPolicy`, `<SandboxPolicy>{…}`) is looked through, not treated
as a bypass.

One intentional overlap with the skills battery: a `SandboxPolicy`-shaped literal
nested inside a skills config — the policy a deployment supplies through
`unsafe.scriptsPermissivePolicy` — carries `filesystem`/`network` sections just
the same, and this rule fires on it there. That is not noise bleeding across
plugins; the nested section is a real sandbox policy at runtime, and leaving it
unflagged would let the same "disabled means unrestricted" misread hide one level
down, inside an object that is already being flagged as unsafe. The same literal
may therefore collect a finding from this rule and one from
`adk-skills/no-unsafe-opt-in` — both name their own boundary.

## `adk-sandbox/filesystem-read-default-allow` — warn

Reads are **deny-then-allow**. The read axis starts by allowing everything, then
applies `denyRead` rules, then applies `allowRead` rules on top. `allowRead` is
therefore only meaningful *inside* a broad deny: it re-permits subtrees you
previously refused.

Write the allow list without a broad deny and it re-permits nothing. The policy
reads as if it confined reads to `/workspace`, and in fact the whole host stays
readable — the only paths refused are the mandatory sensitive-file set and
whatever you named in `denyRead`.

The canonical broad deny is `'/'`, the filesystem root; the battery's own
matcher treats a `'/'` rule as covering every absolute path. It is not `'~'` —
nothing in the battery expands a tilde (the model-path layer classifies a
leading `~` as a host-escape *rejection*, and policy rules are passed to SRT
verbatim).

```ts
// flagged: allowRead with no broad deny — /etc, /home, / are all still readable
const policy: SandboxPolicy = {
  filesystem: { allowRead: ["/workspace"] },
  network: {},
};

// correct: deny broadly, then re-permit
const policy: SandboxPolicy = {
  filesystem: { denyRead: ["/"], allowRead: ["/workspace"] },
  network: {},
};
```

**A `denyRead`-only policy is not flagged, on purpose.** Hiding specific paths —
a credentials file, a hooks directory — from a host you have decided is
otherwise readable is the battery's documented way to narrow exposure, and it
makes no confinement claim that could be false. The rule reports the `allowRead`
claim specifically, because that is the property that lies when it stands alone.

**What it does not catch.** `filesystem: { disabled: true }` is respected (rules
off, nothing to reason about); a spread inside the section may carry the broad
deny, so any spread silences the rule; a `denyRead` that is not an array literal
(`denyRead: myRules`) is likewise unreadable and left alone.

## `adk-sandbox/require-gate` — error

Every sandbox tool is gated. `createRunShellCommandTool` and
`createEvaluateJavascriptTool` have no reference gate and refuse to construct
without one, throwing `E_SANDBOX_GATE_REQUIRED` — because a gate-free shell, or
a gate-free read of `.env`, is an unbounded capability that no default should be
allowed to hand out.

The throw is at construction time, which in an agent means the failure lands
wherever the assembly happens to run first — usually a production start-up, long
after the code review that could have caught it.

```ts
// flagged
const shell = createRunShellCommandTool({
  sandbox: enforcer,
  policy,
  translator,
});

// correct
const shell = createRunShellCommandTool({
  sandbox: enforcer,
  policy,
  translator,
  gate,
});
```

**What it does not catch.** A spread argument (`{ ...options }`) is not inspected
— the gate may come from there, and the rule stays silent rather than guess. A
non-literal argument is not inspected at all. The callee is matched by its
resolved EXPORT name through the file's import bindings — an aliased
`createRunShellCommandTool as mkShell` and a namespace
`tools.createRunShellCommandTool` name the same battery export and are checked —
but a same-named function imported from somewhere other than the sandbox battery
is out of scope, and a *shadowed* local binding is not traced. A TypeScript
wrapper (`as any`, `satisfies ShellConfig`, `<ShellConfig>{…}`, `x!`) is looked
through, so it does not hide a missing gate.

::: tip Gate-free is sometimes deliberate
An `adk-sandbox/require-gate` finding is not always a bug — a read-only workspace
tool in a trusted-tier deployment may legitimately be gate-free, if that is the
decision. Make the decision visible instead of implicit:
`// eslint-disable-next-line adk-sandbox/require-gate -- trusted tier, read-only workspace mount`.
:::
