Skip to content

Commit 241cae7

Browse files
committed
refactor(sandbox): clearer tool-network names + tri-state allow_network
Rename the jailed-command network values for clarity (pre-1.0, no shims): - sandbox.tool_network: blocked|carveouts|allowed -> block|only_explicit_states|allow - per-state allow_network: bool -> "auto" (default) | "allow" | "block" The tri-state fixes a real imprecision: a plain bool could not distinguish "this tool doesn't need network" (default) from "this tool must be isolated". Now a tool reaches the network iff it sets allow_network = "allow" (explicit-only, auditable: grep the one value to find every networked tool). "auto" is best-effort isolation (tolerated on hardened, which can't isolate per-tool); "block" REQUIRES isolation and is refused on hardened. This replaces the previous hardened+allowed warning with a precise refusal only when an explicit "block" (or the operator's tool_network = "block"/"only_explicit_states") can't be honored. The engine resolves the tri-state to a bool grant (allow_network == "allow"); the World/jail interface stays bool. Security review note: defaults unchanged and still safe (tool_network = "block", allow_network = "auto" — no jailed network). The config validator still pins tool_network = "allow" to agent_network = "open". Names only; no behavior change to the agent egress broker or the jail.
1 parent 3fdefdf commit 241cae7

16 files changed

Lines changed: 172 additions & 146 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ All five must pass. 691 tests currently green.
104104
`reset --hard`, and `branch -D` unconditionally. Do not add overrides.
105105
- Config is **secure by default**: every field has a default, and
106106
security-sensitive fields default to the *safe* value (`sandbox.agent_network
107-
= "providers"`, `sandbox.tool_network = "blocked"`, `run_commands = "ask"`,
107+
= "providers"`, `sandbox.tool_network = "block"`, `run_commands = "ask"`,
108108
`protect_* = true`,
109109
`git.allow_* = false`). Config is layered (built-in defaults < global
110110
`$XDG_CONFIG_HOME/agent6/config.toml` < per-repo `.agent6/config.toml`

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ Enforcement is layered:
242242
agent's Python code can read or write outside the jail.
243243

244244
If you set `sandbox.run_commands = "yes"`, `sandbox.agent_network = "open"`,
245-
and `sandbox.tool_network = "allowed"` the worker can talk to anywhere on the
245+
and `sandbox.tool_network = "allow"` the worker can talk to anywhere on the
246246
public internet from inside the sandbox. The defaults exist for a reason.
247247

248248
See [SECURITY.md](SECURITY.md) for the per-layer breakdown.
@@ -251,7 +251,7 @@ See [SECURITY.md](SECURITY.md) for the per-layer breakdown.
251251

252252
agent6 is **secure by default**: every field has a default, and
253253
security-sensitive ones default to the safe value (`allow_push = false`,
254-
`agent_network = "providers"`, `tool_network = "blocked"`,
254+
`agent_network = "providers"`, `tool_network = "block"`,
255255
`run_commands = "ask"`, `protect_* = true`).
256256
Start from [agent6.example.toml](agent6.example.toml), or just run
257257
`agent6 connect` + `agent6 model` (global) and `agent6 init` (per-repo).
@@ -267,7 +267,7 @@ exactly where it came from; `agent6 check` validates without running.
267267
[sandbox]
268268
profile = "auto" # auto | strict | hardened
269269
agent_network = "providers" # providers | local | open (agent's LLM egress)
270-
tool_network = "blocked" # blocked | carveouts | allowed (jailed commands)
270+
tool_network = "block" # block | only_explicit_states | allow (jailed cmds)
271271
allow_urls = [] # extra agent egress hosts under "providers"
272272
run_commands = "ask" # yes | no | ask
273273
protect_git = true

‎SECURITY.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Under that adversary, agent6 aims to make the following true:
4646
"providers"` (the default; see Defense Layer 1b); `"local"` narrows it to
4747
loopback providers, `"open"` lifts it. Jailed commands (`run_command`,
4848
machine `tool` states) are governed separately by `sandbox.tool_network`
49-
(default `"blocked"`); see Defense Layer 1b and §8.
49+
(default `"block"`); see Defense Layer 1b and §8.
5050
4. No `git push`, no `--force`, no history rewrite, no `reset --hard`.
5151
5. No persistence after the run terminates (no daemon, no cron, no
5252
`.bashrc` mutation — the jail's mount namespace is the
@@ -284,30 +284,34 @@ deterministic** tool reach the network — a `tool` command is fixed/operator-
284284
reviewed (unlike `run_command`, whose argv the LLM chooses), so a networked
285285
audited tool is not a free exfiltration channel.
286286

287-
`sandbox.tool_network` governs jailed-command egress: `"blocked"` (default —
288-
none), `"carveouts"` (only `tool` states with `allow_network = true`;
289-
`run_command` stays offline), `"allowed"` (`run_command` too — requires
287+
`sandbox.tool_network` governs jailed-command egress: `"block"` (default —
288+
none), `"only_explicit_states"` (only `tool` states with `allow_network =
289+
"allow"`; `run_command` stays offline), `"allow"` (`run_command` too — requires
290290
`agent_network = "open"`, since `run_command` runs inside the agent process and
291-
cannot out-reach a confined agent). The enforceable combinations:
291+
cannot out-reach a confined agent). A tool reaches the network only if it sets
292+
`allow_network = "allow"`; `"auto"` (default) and `"block"` mean no network.
293+
The enforceable combinations:
292294

293-
| `agent_network` | `tool_network` | agent process | `run_command` | `tool allow_network=true` |
295+
| `agent_network` | `tool_network` | agent process | `run_command` | `tool allow_network="allow"` |
294296
|---|---|---|---|---|
295-
| `providers` *(def)* | `blocked` *(def)* | providers + `allow_urls` | none | none |
296-
| `providers` | `carveouts` | providers + `allow_urls` | none | host network |
297-
| `local` | `carveouts` | loopback providers only | none | host network |
298-
| `open` | `allowed` | unconfined | host network | host network |
297+
| `providers` *(def)* | `block` *(def)* | providers + `allow_urls` | none | none |
298+
| `providers` | `only_explicit_states` | providers + `allow_urls` | none | host network |
299+
| `local` | `only_explicit_states` | loopback providers only | none | host network |
300+
| `open` | `allow` | unconfined | host network | host network |
299301

300-
`carveouts` and `agent_network = "local"` require the `strict` profile (they
301-
need a per-child / per-process network namespace); on `hardened` they are
302-
refused rather than silently under-confined. Every surface fails closed:
302+
`only_explicit_states` and `agent_network = "local"` require the `strict`
303+
profile (they need a per-child / per-process network namespace); on `hardened`
304+
they are refused rather than silently under-confined. Every surface fails closed:
303305

304306
- **Operator-gated, machine-declared.** `agent_network`/`tool_network` are read
305307
only from the operator's global/repo config — a machine's `[config]` overlay
306308
(possibly LLM-drafted or shared) is rejected at load if it declares
307309
`[providers.*]` or `[sandbox.*]`. A `tool` merely *declares* `allow_network`;
308-
it only reaches the network if the operator set `tool_network = "carveouts"`
309-
(or `"allowed"`). A networked tool under `tool_network = "blocked"` is
310-
refused, naming the offending state.
310+
it only reaches the network if the operator set `tool_network =
311+
"only_explicit_states"` (or `"allow"`). A networked tool under `tool_network =
312+
"block"` is refused, naming the offending state; an explicit `allow_network =
313+
"block"` (network must be denied) is refused on `hardened`, which can't
314+
isolate a single tool's network.
311315
- **Bundle confinement.** Helper scripts live in an operator-reviewed
312316
`scripts/` directory beside the `.asm.toml`. `machine check` validates
313317
that every entry under `scripts/` resolves *inside* the bundle (symlinks

‎STATE_MACHINES.md‎

Lines changed: 22 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -314,29 +314,31 @@ A `list`-typed variable spliced as a bare argv element
314314
`scan-inbox` here is an illustrative stand-in — a `tool` state runs
315315
whatever audited command the operator names.
316316

317-
**Network (opt-in, default off).** A `tool` runs fully network-isolated
318-
(empty netns) unless it sets `allow_network = true`. Because the machine
319-
engine is a host-netns *supervisor* (each `agent` state confines itself in its
320-
own subprocess; see §9), an opt-in `tool` can reach the host network even while
321-
the agents stay confined to the provider API — a `tool` command is fixed and
322-
operator-reviewed, so it is not a free exfiltration channel the way a networked
323-
`run_command` would be. Whether opt-in is honored is the operator's call via
324-
`sandbox.tool_network` (read from the global/repo config, never the machine
325-
overlay):
326-
327-
| `sandbox.agent_network` | `sandbox.tool_network` | agent egress | `tool` w/ `allow_network=true` |
317+
**Network (opt-in, default off).** A `tool`'s `allow_network` is one of
318+
`"auto"` (default — no network), `"allow"` (wants the host network), or
319+
`"block"` (no network, *required*: refuse on `hardened`, which can't isolate a
320+
single tool). A tool reaches the network only when it sets `allow_network =
321+
"allow"`. Because the machine engine is a host-netns *supervisor* (each `agent`
322+
state confines itself in its own subprocess; see §9), an opt-in `tool` can reach
323+
the host network even while the agents stay confined to the provider API — a
324+
`tool` command is fixed and operator-reviewed, so it is not a free exfiltration
325+
channel the way a networked `run_command` would be. Whether the opt-in is
326+
honored is the operator's call via `sandbox.tool_network` (read from the
327+
global/repo config, never the machine overlay):
328+
329+
| `sandbox.agent_network` | `sandbox.tool_network` | agent egress | `tool` w/ `allow_network="allow"` |
328330
|---|---|---|---|
329-
| `providers` *(def)* | `blocked` *(def)* | providers + `allow_urls` | none |
330-
| `providers` | `carveouts` | providers + `allow_urls` | **host network** |
331-
| `local` | `carveouts` | loopback providers only | **host network** |
332-
| `open` | `allowed` | unconfined | host network (and `run_command`) |
331+
| `providers` *(def)* | `block` *(def)* | providers + `allow_urls` | none |
332+
| `providers` | `only_explicit_states` | providers + `allow_urls` | **host network** |
333+
| `local` | `only_explicit_states` | loopback providers only | **host network** |
334+
| `open` | `allow` | unconfined | host network (and `run_command`) |
333335

334336
So the headline setup — confined agents + one audited networked tool — is
335-
`sandbox.agent_network = "providers"`, `sandbox.tool_network = "carveouts"`,
336-
and `allow_network = true` on that one state. `carveouts` (and `local`) need
337-
the `strict` profile; a networked tool under `tool_network = "blocked"`, or a
338-
tool-network config the profile can't honor, is refused at startup naming the
339-
state.
337+
`sandbox.agent_network = "providers"`, `sandbox.tool_network =
338+
"only_explicit_states"`, and `allow_network = "allow"` on that one state.
339+
`only_explicit_states` (and `local`) need the `strict` profile; a networked tool
340+
under `tool_network = "block"`, or a tool-network config the profile can't
341+
honor, is refused at startup naming the state.
340342

341343
**Script bundles.** A machine is a *bundle*: the `.asm.toml` file plus an
342344
optional sibling `scripts/` directory holding operator-reviewed helper

‎agent6.example.toml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -135,11 +135,11 @@ profile = "auto"
135135
# providers only (local models; strict-only). "open" = unconfined.
136136
agent_network = "providers"
137137
# Whether JAILED commands (run_command, verify, machine tool states) may reach
138-
# the network: "blocked" | "carveouts" | "allowed"
139-
# "blocked" = none. "carveouts" = only machine tool states that set
140-
# allow_network = true (audited, deterministic), run_command stays offline
141-
# (strict-only). "allowed" = run_command too (requires agent_network = "open").
142-
tool_network = "blocked"
138+
# the network: "block" | "only_explicit_states" | "allow"
139+
# "block" = none. "only_explicit_states" = only machine tool states that set
140+
# allow_network = "allow" (audited, deterministic); run_command stays offline
141+
# (strict-only). "allow" = run_command too (requires agent_network = "open").
142+
tool_network = "block"
143143
# Extra egress destinations the AGENT process may reach under
144144
# agent_network = "providers", on top of the provider endpoints. Each entry is a
145145
# host, host:port, or full URL (a missing scheme implies https / port 443); only

‎src/agent6/cli/completers.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ def _complete_models(
4141
_CONFIG_ENUM_CHOICES: dict[str, tuple[str, ...]] = {
4242
"sandbox.profile": ("auto", "strict", "hardened"),
4343
"sandbox.agent_network": ("providers", "local", "open"),
44-
"sandbox.tool_network": ("blocked", "carveouts", "allowed"),
44+
"sandbox.tool_network": ("block", "only_explicit_states", "allow"),
4545
"sandbox.run_commands": ("yes", "no", "ask"),
4646
"git.commit_strategy": ("per_step", "squash", "stage", "none"),
4747
"workflow.critic": ("off", "on_verify_fail", "before_finish", "periodic"),

‎src/agent6/cli/egress.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -89,11 +89,11 @@ def _check_network_profile(cfg: Config, selected_profile: SandboxProfile) -> str
8989
"""A refusal message if the network config can't be enforced on this profile.
9090
9191
``agent_network = "local"`` (loopback-pinning) and ``tool_network =
92-
"carveouts"`` (singling one tool out) both need a network namespace, which
93-
only the ``strict`` profile provides. On ``hardened`` (a real sandbox that
94-
can't provide them) we refuse rather than silently under-confine; on
95-
``none`` (no sandbox at all) the unsandboxed warning already covers it and
96-
we run. Returns None when fine.
92+
"only_explicit_states"`` (singling one tool out) both need a network
93+
namespace, which only the ``strict`` profile provides. On ``hardened`` (a
94+
real sandbox that can't provide them) we refuse rather than silently
95+
under-confine; on ``none`` (no sandbox at all) the unsandboxed warning
96+
already covers it and we run. Returns None when fine.
9797
"""
9898
if selected_profile != "hardened":
9999
return None
@@ -104,11 +104,11 @@ def _check_network_profile(cfg: Config, selected_profile: SandboxProfile) -> str
104104
" pinning needs the egress broker), but this host supports only"
105105
" 'hardened'. Use 'providers' or 'open'."
106106
)
107-
if sb.tool_network == "carveouts":
107+
if sb.tool_network == "only_explicit_states":
108108
return (
109-
"sandbox.tool_network = 'carveouts' requires the strict profile (a"
110-
" per-tool network namespace singles one tool out), but this host"
111-
" supports only 'hardened'. Use 'blocked' or 'allowed'."
109+
"sandbox.tool_network = 'only_explicit_states' requires the strict"
110+
" profile (a per-tool network namespace singles one tool out), but"
111+
" this host supports only 'hardened'. Use 'block' or 'allow'."
112112
)
113113
return None
114114

‎src/agent6/cli/machine_cmds.py‎

Lines changed: 23 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -322,38 +322,47 @@ def _machine_protect_paths(machine_path: Path, cwd: Path) -> tuple[Path, ...]:
322322

323323

324324
def _machine_network_refusal(
325-
cfg: Config, profile: SandboxProfile, tool_states: list[ToolState], has_network_tool: bool
325+
cfg: Config, profile: SandboxProfile, tool_states: list[ToolState]
326326
) -> str | None:
327327
"""A refusal message if this machine's tool-network needs can't be honored.
328328
329329
Layers machine-specific rules on top of `_check_network_profile` (which
330-
handles agent_network=local / tool_network=carveouts on `hardened`):
331-
a tool opting into the network needs `tool_network != "blocked"`; and on
332-
`hardened` per-tool isolation is impossible, so a machine with tool states
333-
under `tool_network = "blocked"` is refused rather than silently handed the
334-
host network. Returns None when fine.
330+
handles agent_network=local / tool_network=only_explicit_states on
331+
`hardened`). On `hardened` per-tool isolation is impossible, so we refuse —
332+
rather than silently mis-confine — whenever isolation is *required*: by the
333+
operator (`tool_network = "block"`) or by a state (`allow_network = "block"`).
334+
A networked state under `tool_network = "block"` is a config conflict and is
335+
refused on any profile. Returns None when fine.
335336
"""
336337
net_err = _check_network_profile(cfg, profile)
337338
if net_err is not None:
338339
return net_err
339340
tn = cfg.sandbox.tool_network
340-
if has_network_tool and tn == "blocked":
341+
has_allow = any(s.allow_network == "allow" for s in tool_states)
342+
has_block = any(s.allow_network == "block" for s in tool_states)
343+
if has_allow and tn == "block":
341344
return (
342-
"a tool state sets allow_network = true but sandbox.tool_network ="
343-
" 'blocked'. Set sandbox.tool_network = 'carveouts' for audited"
344-
" per-tool egress."
345+
'a tool state sets allow_network = "allow" but sandbox.tool_network ='
346+
" 'block'. Set sandbox.tool_network = 'only_explicit_states' for"
347+
" audited per-tool egress."
345348
)
346-
if tool_states and tn == "blocked" and profile == "hardened":
349+
if tool_states and tn == "block" and profile == "hardened":
347350
return (
348351
"isolating a machine's tool-state network requires the strict profile"
349352
" (a per-tool network namespace); this host supports only 'hardened'."
350-
" Run on strict, or set sandbox.tool_network = 'allowed' (tools share"
353+
" Run on strict, or set sandbox.tool_network = 'allow' (tools share"
351354
" the host network)."
352355
)
356+
if has_block and profile == "hardened":
357+
return (
358+
'a tool state sets allow_network = "block" (network must be denied),'
359+
" but the hardened profile can't isolate one tool's network. Run on"
360+
' strict, or use allow_network = "auto" to tolerate the host network.'
361+
)
353362
return None
354363

355364

356-
def _cmd_machine_run(path: Path, *, exit_on_wait: bool = False) -> int: # noqa: PLR0911, PLR0912
365+
def _cmd_machine_run(path: Path, *, exit_on_wait: bool = False) -> int: # noqa: PLR0911
357366
try:
358367
spec = load_machine(path)
359368
except MachineError as exc:
@@ -365,7 +374,6 @@ def _cmd_machine_run(path: Path, *, exit_on_wait: bool = False) -> int: # noqa:
365374
states = list(spec.states.values())
366375
has_agent_state = any(getattr(s, "kind", None) == "agent" for s in states)
367376
tool_states = [s for s in states if isinstance(s, ToolState)]
368-
has_network_tool = any(s.allow_network for s in tool_states)
369377
agent_runner: Callable[[AgentRequest], AgentExecResult] | None = None
370378
# Default profile for confinement-free machines: resolve from the host.
371379
profile: SandboxProfile = detect().detected_profile
@@ -387,20 +395,10 @@ def _cmd_machine_run(path: Path, *, exit_on_wait: bool = False) -> int: # noqa:
387395
except RuntimeError as exc:
388396
print(f"REFUSING: {exc}", file=sys.stderr)
389397
return 2
390-
refusal = _machine_network_refusal(cfg, profile, tool_states, has_network_tool)
398+
refusal = _machine_network_refusal(cfg, profile, tool_states)
391399
if refusal is not None:
392400
print(f"REFUSING: {refusal}", file=sys.stderr)
393401
return 2
394-
if tool_states and profile == "hardened" and cfg.sandbox.tool_network == "allowed":
395-
# hardened has no per-child netns, so a tool's allow_network = false
396-
# cannot be honored — every tool command shares the host network.
397-
# The operator opted into "allowed" (broad), so we warn, not refuse.
398-
print(
399-
"[agent6] note: on the hardened profile tool states are not"
400-
" network-isolated per-tool — every tool command shares the host"
401-
" network (per-tool allow_network needs the strict profile).",
402-
file=sys.stderr,
403-
)
404402
if has_agent_state:
405403
missing = _check_provider_keys(cfg)
406404
if missing is not None:

0 commit comments

Comments
 (0)