feat(docker): sandbox egress control (on/off/allowlist) with filtered proxy

[suzu784]

What does this PR do?

Adds a third egress mode for Docker sandboxes: terminal.container_network: "allowlist", alongside the existing on/off (network: bool). In allowlist mode, sandboxes attach to a per-allowlist --internal network and reach the internet only through a shared, dual-homed, stdlib-only forward proxy — default-deny, TLS pass-through via CONNECT (no certificate interception). Raw / non-proxied egress has no route out.

The threat model is the one already described in docs/security/network-egress-isolation.md (prompt-injected data exfiltration via curl/wget from inside a sandbox). That doc covers an ops-level pattern (compose + external squid/envoy); this PR provides the same control in-app, per-sandbox, auto-provisioned, with no external infrastructure. The two are complementary — happy to add a cross-reference to that doc if desired.

Related Issue

No linked issue — feature proposal. Closest prior art is the deployment pattern in docs/security/network-egress-isolation.md.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• tools/environments/egress_proxy.py (new): network/proxy provisioning — one --internal network + one shared proxy container per allowlist hash, labeled hermes.egress, pruned from cleanup_all_environments()
• tools/environments/egress_proxy_server.py (new): self-contained stdlib proxy, mounted read-only into python:3.13-slim (CONNECT tunnel, absolute-URI plain HTTP forward, 403 deny, 502 upstream-failure)
• tools/environments/docker.py: DockerEnvironment(network_mode=, network_allowlist=), mode resolution + allowlist normalization; legacy docker_network: false remains a hard deny even when new defaults are present
• Wiring (the env-driven bridges without which the environment layer is inert): cli.py env_mappings, gateway/run.py _terminal_env_map, tools/terminal_tool.py _get_env_config()/_create_environment(), hermes_cli/config.py TERMINAL_CONFIG_ENV_MAP + defaults + hermes config display
• cli-config.yaml.example: documented container_network / container_network_allowlist incl. fail-closed and prune semantics, plus the explicit scope boundary that Codex app-server commands use Codex's separate sandbox
• scripts/release.py: AUTHOR_MAP entry for this contributor (contributor-check)

Design points:

• Fail closed everywhere: unknown mode → "off"; proxy provisioning or outbound-connect failure → --network=none; legacy docker_network: false cannot be weakened by container_network: "on" (never silently open)
• IP-literal allowlist entries require an exact match (no subdomain/wildcard logic on IPs)
• Warns when user docker_env overrides the injected proxy env vars

How to Test

1. bash scripts/run_tests.sh tests/tools/test_egress_proxy.py tests/tools/test_docker_environment.py — 110 tests (provisioning/restart/race/fail-closed orchestration, real proxy-server integration over loopback, prune keep/remove, config-wiring regression guards)
2. Live E2E (requires Docker): set terminal.container_network: "allowlist" and container_network_allowlist: ["pypi.org"] → inside the sandbox, https://pypi.org returns 200 via the proxy, https://example.com fails with Tunnel connection failed: 403 Forbidden, raw-socket egress is unreachable
3. Verified E2E against a live Docker daemon on macOS (Apple Silicon) — allowlisted 200 / unlisted 403 / no raw route / prune leaves no leftovers

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (plus the AUTHOR_MAP entry required by contributor-check)
• Affected suites pass via the canonical runner (scripts/run_tests.sh, 110 tests); relying on CI for the full matrix — my host lacks some optional deps (whisper/fastapi/mautrix) so a full local run has known env-caused failures unrelated to this change
• I've added tests for my changes
• I've tested on my platform: macOS 26 (Apple Silicon), Docker via Colima

Documentation & Housekeeping

• I've updated relevant documentation (cli-config.yaml.example, docstrings)
• I've updated cli-config.yaml.example for the new config keys
• CONTRIBUTING.md / AGENTS.md — N/A (no architecture/workflow change)
• Cross-platform: docker-backend-only feature; the proxy is stdlib-only and runs inside a Linux container, so host OS differences don't apply
• Tool descriptions/schemas — N/A (no tool schema change)

🤖 Generated with Claude Code

https://claude.ai/code/session_013n8YAnnTrwfzD5oECy6zdi

[teknium1]

Thanks for the substantial, fail-closed design and proxy coverage. It needs a few security-boundary fixes before salvage.

Problems

• tools/code_execution_tool.py:680-688 and tools/file_tools.py:1141-1151 independently construct Docker configs but do not receive either new egress key. Unlike the terminal path, those Docker sandboxes fall back to DockerEnvironment's default network mode.
• Current reuse protection only inspects a reused container when legacy network is false (tools/environments/docker.py:913-917). The new allowlist mode leaves that boolean true, so a labeled bridge container can be reused after an operator changes to allowlist mode.
• tests/tools/test_egress_proxy.py:436-442 reads source text instead of executing configuration behavior.

Suggested changes

• Propagate both settings through file and code-execution paths, with behavioral coverage for all three creation paths.
• Make reuse validate the expected allowlist network and replace stale bridge/different-allowlist containers.
• Replace the source-shape test with CLI/gateway propagation tests; update website/docs/user-guide/configuration.md alongside the example config.

Automated hermes-sweeper review.

[teknium1]

Allowlist mode also needs to update the cross-process reuse guard. On current main that guard only checks not network, so a previously bridge-networked container with the same task/profile labels will be reused after this setting changes to allowlist, bypassing the intended boundary. Validate the expected internal network and replace mismatches.

[teknium1]

Please replace this source-text assertion with a behavioral propagation test. Repository policy forbids tests that read source files: this can pass while runtime wiring is broken and blocks harmless refactors.

[suzu784]

Thanks for the review — all three findings were valid. Addressed in cb26d8698 + 98ca78afe:

1. Egress keys not propagated to the code-execution / file-tools Docker paths → fixed in 98ca78afe. Both container_config dicts now carry container_network / container_network_allowlist, mirroring the terminal path. Behavioral coverage added for all three creation paths: the new tests drive the real _get_env_config() → container_config → _create_environment chain with a capturing _DockerEnvironment fake and assert the settings reach DockerEnvironment (network_mode="allowlist", allowlist intact). Before the fix, the execute_code and file-tools tests fail with network_mode=None — reproducing exactly the gap you flagged.

2. Reuse guard skipped for allowlist mode → fixed in cb26d8698. The if not network: gate is gone; _reuse_network_mismatch() now validates the reused container's HostConfig.NetworkMode against the effective expectation in every mode:

• off / allowlist: exact match required — none, or the current allowlist's hermes-egress-<hash> network (a changed allowlist hashes to a different name, so stale-bridge and different-allowlist containers are both replaced). Inspect failure counts as mismatch (fail closed).
• on: replaces only containers stranded on a hermes-egress-* internal network (no route out under an open config); deliberate --network=none containers from docker_extra_args are kept, preserving the documented no-churn behavior, and legacy docker_network: false resolves to off so its guard is unchanged.

expected_network_name() (new, pure) exposes the provisioning name derivation to the guard. 10 new reuse-guard tests cover bridge/none/other-allowlist/matching/proxy-failure/inspect-failure across all three modes.

3. Source-text test → replaced in 98ca78afe with behavioral bridge tests: one executes the real cli.load_cli_config() against a temp HERMES_HOME and asserts TERMINAL_CONTAINER_NETWORK* land in os.environ (JSON-encoded list included); two more extend the gateway's subprocess import harness (tests/gateway/test_config_env_bridge_authority.py) to assert the import-time bridge exports both vars and that config.yaml wins over a stale .env. website/docs/user-guide/configuration.md now documents both keys (modes, allowlist entry format, fail-closed semantics, container-replacement-on-mode-change, proxy lifecycle) alongside the example config.

[teknium1]

Heads-up on an interaction with a feature that just landed on main (PR #70848, re-land of #30179): the iron-proxy credential-injection egress firewall for Docker sandboxes.

Both features claim the same container-side surface:

1. HTTPS_PROXY / HTTP_PROXY env vars — iron-proxy sets these to http://host.docker.internal:9090 / :9091 when proxy.enabled is on. If allowlist mode also sets them to its own filtered proxy, one feature silently disables the other.
2. Network reachability — this PR's --internal network removes the container's route to host.docker.internal (host-gateway), which is how sandboxes reach the iron-proxy daemon on the host. With both enabled, credential injection breaks: SDK calls carry proxy tokens that nothing swaps for real keys, so every provider call 401s.
3. Container reuse — feat(egress): re-land iron-proxy credential-injection firewall (revert of #58489) #70848 added an egress-posture label/fingerprint to the reuse path (_find_reusable_container, hermes-egress label) because proxy env/CA mounts are immutable post-creation. A third network mode should participate in that fingerprint (or the network-mode guard added in 3167dba) so mode switches don't silently reuse a container with the wrong posture.

None of this is a rejection signal — default-deny reachability control and credential injection are complementary layers. But the PR needs an explicit answer for proxy.enabled && container_network: allowlist: either compose them (chain the filtered proxy upstream of iron-proxy, or attach the iron-proxy bind to the internal network) or refuse the combination loudly at startup. Silent breakage of the credential firewall would be the worst outcome.