Threat model

Rendered from docs/threat-model.md in the repository.

Living document. Reconcile after every feature that changes a trust boundary, a credential path, or the network surface. The maintenance table at the foot is the contract: a feature that lands without updating it has not landed.

Read docs/layout.md for where things live, docs/credentials.md for how secrets are delivered, and docs/egress.md for the network boundary.

1. What this system is, in security terms#

An always-on container running untrusted code that holds real credentials and can reach the network. Constitution II states it plainly: "A container runs untrusted agent code."

Every control below follows from taking that literally. The agent is not an occasional bug to defend against — it is a hostile actor by assumption, because a prompt-injected agent is indistinguishable from a malicious one, and this container exists precisely to bound what either can do.

2. Actors and trust#

3. Assets#

4. Trust boundaries#

1. Operator machine → container host — SSH / docker context. Build contexts and injected material cross it, possibly over the network to a remote daemon.
2. Host → container — compose configs, volumes, environment. The credential-injection boundary. Feature 016 made it two-way. Every other flow across 1 and 2 runs outward from the operator: material is injected, and what the container produces goes to a git remote (boundary 4) or to logs nobody stores. A run record runs the other way — the container authors a file, and the tool ingests it into a durable store on the operator's machine. So the container is now an input to something the operator keeps, and everything ingestion accepts is data the untrusted side wrote (T16).
3. Container → network — the egress boundary (Feature 012). Phase B moved this boundary out of the agent container. The agent joins the egress sidecar's network namespace holding an empty capability set; the rules that govern it are installed by a container it does not share a filesystem or a process table with. The boundary is no longer a setting the confined party owns. Two further consequences of that shape: - The inside is a set of containers, not one. Every operator sidecar is inside by default (FR-023); egress.sidecars_outside is the only exit, by declaration, and each name is disclosed in the enforcement statement (FR-023b). - Traffic between containers inside the boundary is loopback and is not filtered. That is not a gap — it is what "inside" means. Placing a sidecar inside is a decision to let the agent drive it (T5, T14).
4. Container → git remote — the sanctioned exfiltration path, by design (Hard Constraint #1).
5. Agent → its own governing spec — Feature 006 FR-020.
6. Control plane → the fleet — Feature 017, and the widest boundary in this document. A container that manages containers: it holds a keypair whose public half the operator authorises on permitted hosts, so what crosses this boundary is not material but AUTHORITY. Three things about its shape matter more than its existence: - It inverts boundary 1. Boundaries 1 and 2 run outward from the operator's machine; this one puts the operator's machine-level reach inside a container, on the far side of a boundary built to confine one. The confining direction is unchanged — the control plane cannot escape its container — but what it can reach from inside is no longer a subset of what a container had. - The boundary is the AUTHORISATION, not the declaration. control_plane_hosts is intent an operator can see before deploying; actual reach is wherever the public key is authorised, which lives outside the container on purpose. Treating the declared scope as the boundary would be a control that does not control, and revoke — withdrawing the key — is therefore the only concrete narrowing. - It is recursive, and not gated. A control plane can deploy another (T17), so standing keys can be minted from inside the system. Scope is where the key is authorised, so a parent cannot constrain a child even in principle; the answer is visibility — provenance on every inventory entry — rather than an enforcement point that could not enforce.

Boundary 3 governs its egress like any other container's, including the telemetry export this feature added (T19). That is not a courtesy: an enforced declaration that omits the collector blocks export, and export is fail-open precisely so the work is not blocked by its own observability.

Which mechanism governs a destination is selected by the declaration, not by a mode switch: an entry without a port is enforced by the proxy allowlist, an entry with a port by an explicit netfilter rule (FR-018a). Both mechanisms are deployed together; Phase A was not superseded and removed.

5. Threats and current posture#

T1 — Credential theft from the image or generated artifacts#

Mitigated. Secrets are never baked into the image, never passed on argv, never printed. Tool- injected material lands under /run/agent-container/… — never on a volume — and vanishes with the container. The repository holds a locator, never a value (Feature 008); a source: file credential that is git-tracked inside the project is refused with remediation. A sentinel test asserts no credential value reaches any generated artifact (compose model, proxy config, --json).

Residual, accepted: an on-volume auth.json written by operator-interactive login is exempt by design — it is the operator's own session, and the agent can read it.

Residual, accepted, and new with 019: the agent's SSH private key lives on the per-container ssh volume. It is not injected — the container generates it, and no channel carries it — but it does outlive its container, which is what the rest of this asset class does not do. That is load-bearing rather than an oversight: a key regenerated on each boot would silently invalidate whatever the operator registered on the forge, and the symptom would arrive days later as a push that stopped working. down --purge and ssh-key rotate are the revocation boundary, and both say so in their output — nothing else would tell the operator the registration is now dead.

Residual, and the sentinel does not reach it: a run record is a generated artifact the sentinel deliberately does not cover, because one of its fields is operator free text and FR-002 requires it. That exemption is bounded by a closed field set rather than by a filter — see T15.

T2 — Secrets leaking through the build context#

Mitigated by construction. The build context is image/, not the checkout, so narrowness is structural rather than an allowlist maintained in step with the Dockerfile. Measured during Feature 009: an unprotected context shipped 2234 files / 23.4 MB — including a planted .env and an API key — to a daemon that may be remote.

T3 — The agent rewrites the spec that governs it#

Mitigated. The tool reads the declarative spec only host-side; the in-container copy is delivered read-only via compose configs. The host-side-only read is load-bearing; the read-only delivery is defence-in-depth. A configuration that would expose the spec writable (a bind workspace over the project config directory) is refused.

T4 — The agent reaches a model provider nobody chose#

Mitigated — Feature 012 Phase B — with one residue, T13, that is named rather than absorbed. Enforcement is packet-level and no longer depends on the agent's cooperation. The sidecar installs -P OUTPUT DROP before exec'ing either daemon, redirects 80/443 to squid, and exempts squid's and unbound's own traffic by uid. squid peeks the ClientHello SNI and splices — never bumps — so the client verifies the real server certificate and no Authorization header is ever readable by the proxy (Constitution III, R2). Resolution is allowlist-only (unbound, local-zone "." refuse plus a forward-zone per declared name).

Phase A's four open bullets, each re-measured under Phase B:

• unsetting HTTPS_PROXY — changes nothing. Undeclared host, every proxy variable unset: still curl exit 35. Under Phase A that same probe returned 0. That difference is the phase.
• ~/.agent-env/env — still the agent's own file, and now inert: proxy variables are no longer what routes the traffic.
• non-HTTP protocols and non-standard ports — default-denied. Ports 8080 and 1337, and ssh to an undeclared host on 22, are dropped. A port is reachable only because the declaration names it.
• DNS — closed by refusing to ask, which is the only thing that closes a channel whose payload rides in the question. An undeclared or tunnelling-shaped name gets REFUSED, not NXDOMAIN: "policy forbids asking" must be distinguishable from "no such host", and NXDOMAIN is a cacheable negative that would outlive the declaration error that caused it.

The resolver hole this uncovered is worth recording, together with the fact that the first fix for it was itself runtime-specific. Compose always creates a user-defined network, where the daemon runs an embedded resolver the agent reaches over loopback and which forwards the query outside the namespace — past every rule of ours. Pointing /etc/resolv.conf at unbound would have been advisory (and is not even writable as dev), so the packet is rewritten instead.

The original rewrite matched -d 127.0.0.11 — Docker's embedded resolver and nothing else's. Podman puts aardvark-dns on the network gateway, so under podman the rule never matched, every lookup fell through to default-deny, and nothing resolved at all, declared or not. It failed closed, so it was never a hole — but it made egress-enabled environments unusable on the runtime ADR 0001 makes the default, and "the control was inert under our own default runtime" is the kind of finding that only surfaces by running it.

The rule is now by PORT, not by destination address: all port-53 traffic, UDP and TCP, REDIRECTed to unbound, with the resolver exempted by UID (! --uid-owner) so its own upstream forwarding does not loop back into the rewrite. A POSTROUTING SNAT to 127.0.0.1 makes the query arrive looking local, without which unbound refuses it and the allowlist appears to deny everything — including declared names, which is the tell. The filter DROP for the ephemeral high port the daemon's resolver also answers on is retained: the redirect matches port 53 only, and asking that port directly walked straight past the rewrite (measured — it answered). This satisfies FR-020a, which required all port-53 traffic to be forced to the resolver and which the narrow rule never actually met.

Residual: the name check does not constrain the destination address — see T13.

T5 — Laundering egress through an operator sidecar#

Mitigated by default placement; the exception is declared, never silent. Any sidecar the agent can reach that has unrestricted egress is a bypass: redis REPLICAOF <host> <port>, postgres COPY … FROM PROGRAM, any service that fetches a URL on request. The agent need not escape anything — it need only ask something that already has the access. So every operator sidecar joins the boundary by default (FR-023) and meets the same default-deny the agent does, and there is no automatic allowance for the project network to reach sidecars — that would be the hidden baseline FR-001e forbids, arriving by a different route (FR-023c).

Residual, and declared: egress.sidecars_outside deliberately places a named sidecar outside, for the cases that genuinely need their own egress. Anything it can reach is reachable through it. The tool names each one in its enforcement statement (FR-023b) instead of letting enforced: true quietly cover it.

T6 — Exfiltration through the sanctioned git push#

Not mitigated, and largely unmitigable. Hard Constraint #1 requires every agent to commit and push, because the container is ephemeral. An agent that can push can push content of its choosing. Narrowing this without breaking the constraint is an open problem; the current answer is that the remote is operator-declared and the history is reviewable.

T7 — Privilege escalation inside the container#

Mitigated by design. Rootless by decision: no sudo, no root at runtime, sshd runs as dev on 2222, the runtime is immutable, and every system dependency is baked at build (agents never apt install). Phase B put a real CAP_NET_ADMIN into the deployment, and it lands on the egress sidecar, which runs no untrusted code. The agent container's capability set is measured as [] and SC-011 asserts it; the two containers share a network namespace only, not a filesystem, a process table, or a capability set. This is the Istio/Linkerd sidecar pattern: the privilege exists precisely where the untrusted code is not. The sidecar's own exposure is T14.

T8 — Container escape / host compromise#

Out of scope. This project's controls do not defend the kernel or the container runtime. Rootless operation reduces blast radius; runtime and kernel patching are the host operator's responsibility.

T9 — Supply chain of the agent CLIs#

Not mitigated. The agent CLIs are npm globals installed at build time. A compromised release executes with the agent's full access — credentials, workspace, network. Version pinning and provenance verification are unaddressed.

T10 — Loss of work#

Mitigated by construction. Constitution I: containers are disposable, durable state lives in git, and every agent commits and pushes. Feature 012 had to add a deploy-time check (FR-003c) because an enforced egress declaration silently broke HTTPS git push — a control that would have failed only at push time, exactly when the work would otherwise have been preserved.

T11 — Collision between parallel containers#

Mitigated. Constitution IV: names, ports and volumes derive deterministically from one identifier, and the computed values are a stable contract guarded by an identity-lock test. Changing one is a migration, not an edit.

T12 — Silent failure of a control#

Partially mitigated — and this is the recurring defect class in this codebase. Observed and fixed instances:

• a YAML guard that returned nothing for flow style and quoted keys, so a sidecar override could set agent.environment.NO_PROXY and defeat the egress control past a guard reporting no problem;
• unanchored proxy filter patterns, making api.anthropic.com.attacker.net reachable from a declaration naming anthropic;
• a hostname length that split one filter line into two unanchored patterns;
• an allowlist delivered by a mechanism (configs: file:) that is a bind mount and therefore cannot reach a remote daemon — documented backwards in two places that corroborated each other;
• teardown that stranded the proxy container and exited 0;
• the allowlist enforced by the one component that cannot see the hostname: on the intercept port, http_access deny all closed the connection before ssl_bump could peek the SNI, so every declared host broke while every refusal test still passed — broken-closed, which looks exactly like working;
• the ACL scoping that fix written as localport 3129, which never matches because an intercepted connection reports the original port 443; the scoping silently became a no-op, indistinguishable from a working rule when observed from outside the container (myportname matches);
• local-zone "." refuse shadowing every forward-zone, producing an allowlist-only resolver that resolved nothing — and passing every refusal check while doing so;
• a pytest -k selection spelled nonstandard for a test named non_standard, matching no test and reported as "all egress tests pass". A filter that matches nothing and a filter whose tests all pass look identical;
• a port-owner migration detector that answered False whenever enforcement was off, so redeploy — the one command that moves the port binding — was the one command that could not survive it. "No migration needed" is also the correct answer in the common case, which is what hid it.

Standing countermeasures: structural guards get proof-that-they-can-fail tests; honesty statements are tested for absence of overclaim; and claims about mechanism are established by running them, not by reading documentation.

T13 — A declared name does not constrain the destination address#

Not mitigated. Inherent to splicing, measured, and stated in the tool's own output. squid connects the spliced session to the address the client chose — its access log records ORIGINAL_DST, the destination the netfilter REDIRECT captured, not an address squid resolved for itself from the SNI. Name and destination are therefore decoupled: a process that opens a connection to an arbitrary address while presenting a declared name in its ClientHello satisfies the allowlist and is spliced to whatever it dialled.

What it does and does not grant. It does not grant discovery — the agent cannot resolve a name the declaration does not permit, so it must already hold a literal address. It does grant delivery: bytes to an attacker-controlled IP, under the cover of a declared name.

Why it is open rather than closed by wording. Closing it means pinning each connection's destination to the addresses the allowlist-only resolver actually handed out for that name — real shared state between unbound and squid, and a control that would break on every short-TTL, multi-address or CDN-fronted provider. An enforcement that fails on a declared provider's own address rotation gets switched off, not tightened. The mechanism is named here so the next attempt starts from the real obstacle.

Not silent. The transparent-mode strength statement says it in the tool's output — "the connection is spliced to the address the CLIENT chose, so a process that opens a connection to an arbitrary address while presenting a declared name is not stopped by the name check" — and a test asserts that clause is present, on the same absence-of-overclaim principle as the rest of FR-022.

T14 — The enforcement sidecar is new surface and a new dependency#

Newly introduced by Phase B. Accepted, with the failure direction checked rather than assumed. The environment now contains a container holding CAP_NET_ADMIN and running two network daemons, and every name lookup in the environment depends on it.

• It fails closed, and that was measured, not argued. The rules are installed before either daemon is exec'd, so no window exists in which the agent is unconstrained. The observable cost is the mirror image: for ~3 s after up returns, a declared destination is refused because squid and unbound are not yet serving, and that refusal is indistinguishable from a policy refusal from inside the container. The boundary holds; the diagnosis is what suffers — which is why the sidecar carries a healthcheck probing both daemons and the agent (and every sidecar inside the boundary) waits on service_healthy rather than on "started".
• A compromised sidecar is a compromised boundary. Nothing here defends squid or unbound against their own vulnerabilities; they are distribution packages and share T9's supply-chain posture.
• What the agent gains from the arrangement: reachability of the sidecar's listening ports over loopback. Nothing more — the namespace is shared for networking only.

T15 — The task text is recorded verbatim, and it is the one field a credential can arrive in#

Newly introduced by Feature 016. Accepted as a NAMED, BOUNDED exposure — stated, not filtered. A run record keeps the task the operator gave (FR-002), and a task is free text an operator types, so it can contain a credential. No other field is a place the tool would put one: repository is SHAs and paths read out of git, usage is refused unless it is numbers under identifier-shaped keys, and every remaining field is composed by the tool or the entrypoint from what it already knew.

The bound is a table, not a filter. RECORD_FIELD_PROVENANCE in bin/agent-container maps every field to tool · git · agent · operator and has exactly one operator row. That closure is the whole of the no-credentials claim, which is why a test asserts the table itself: add a second free-text field and the claim becomes false while every other test still passes.

What that closure is, exactly. It is a statement about which fields exist and where the tool puts values in them. Ingestion checks the field set of a record the container wrote and warns about anything undeclared; it does not re-derive the values, which are the container's word — so the claim is "the tool writes a credential into no field but task", not "no byte of a stored record can be a credential regardless of what ran inside" (T16).

Pattern redaction was rejected, for the reason this document catalogues under T12. A redactor that misses one value converts an operator's caution into misplaced confidence — a check that passes while the thing it names is broken — and its existence licenses exactly the habit the warning exists to discourage. Saying the task is recorded verbatim; do not put a credential in one is weaker protection and strictly better information. The rule is stated in docs/observability.md and where a task is given.

Where a task text ends up. Durably in $XDG_DATA_HOME/agent-container/runs/ on the operator's machine, written 0600; in transit on the -runs volume, where the host operator and the agent itself can both read it — the same exposure as anything on a volume, and the reason the durable store is not one. Ingestion warns when a stored record carries a field the build does not declare, because the claim above covers only the fields it does.

T16 — A run record is an account of a run, not evidence against the agent#

Newly introduced by Feature 016. Accepted, and the limit is stated rather than implied. The pending record lives at /var/lib/agent-container/runs on a volume owned dev:dev (0700) — and the agent runs as dev. It is out of /home/dev, so no ordinary shell or agent-config write touches it by accident, but that is separation from accident, not from intent: a process running as the agent can rewrite or delete its own pending record before the tool ever sees it.

What that does and does not undermine. Against a crash, a SIGKILL, a failed agent or an operator's own hand, the record is exactly what it claims — which is every case the feature was built for. Against a hostile agent, the values inside a well-formed record are the container's word, so a record must never be read as proof that a run did or did not push, change a file, or touch a repository.

Ingestion distrusts the boundary even where it must trust the content. The drain is the only door records enter the store by that the tool did not compose itself, so member names from the tarball are refused rather than repaired (a directory component, a .., or a name that is not a run id), oversized members are skipped, a record whose schema is not this build's is left on the volume rather than misread, and nothing the parser distrusted is ever handed to the clear step that removes files. host and environment are stamped by the tool, keyed off the volume it drained — so a forged record cannot claim to belong to another environment or another host.

Not closed by permissions. Making the directory unwritable by the agent means a second uid inside the container writing the record, which is a setuid helper or a privileged process in the one place this project has none (Constitution II, T7). That trade — real privilege inside the untrusted container, to harden a summary against an adversary who by then already holds the credentials and the push — is not worth making, so the limit is documented instead.

6. Risk summary#

7. Accepted residual risks#

• The operator is trusted absolutely. There is no multi-tenant model and no defence against the operator's own machine being compromised.
• A sanctioned channel can carry anything. A declared provider and a declared git remote are both full-bandwidth egress to a hostile agent.
• The boundary governs where, never what. TLS is never terminated (Constitution III), so no content inspection is possible — deliberately, because a decrypting proxy would see every Authorization header and create a new plaintext credential location inside the component meant to reduce exposure. Whatever a declared destination will carry, it carries.
• And where is a name, not an address (T13). Splicing preserves the client's chosen destination; the allowlist checks the name it presented.
• Everything inside the boundary can reach everything else. The shared network namespace makes agent↔sidecar traffic loopback, unfiltered by construction. Putting a sidecar inside is a decision to let untrusted code drive it.
• auth.json from interactive login is readable by the agent.
• A headless task runs Claude Code with --permission-mode bypassPermissions, so the agent's tools are unrestricted inside the container. This is accepted rather than overlooked: headless has no tty, so the default asks for an approval that can never arrive — Claude declined the work and exited 0, reporting success for a run that did nothing. The container is the boundary (rootless, declared egress, disposable home), and an agent that can already open a shell gains nothing from confirming a file write. The consequence to hold onto is that the egress declaration, not the agent's consent dialog, is what constrains a headless run.
• A host bind is mounted read-only (--mount, --workspace bind), which removes an exposure: the container cannot write the operator's filesystem, and everything it writes goes to a volume that can be revoked by name. Read-write was requested until it was measured to be unavailable anyway on the common Lima setup — docker failed at first write, podman refused at create.
• A task is recorded exactly as it was typed (T15). The tool does not redact it, because a redactor that misses one value is worse than none. Do not put a credential in a task.
• A run record is the container's account of itself (T16). It is trustworthy against crashes and kills — the cases it exists for — and it is not evidence against an agent that chose to edit it before the tool drained the volume.

8. Maintenance#

Update the row, and the affected threat, in the same change that ships the feature.