Skip to content
5 min read · 919 words

Sandbox battery rules ​

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.

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.