Threat model
What DefenseClaw on Agent Substrate defends against, what it trusts, and what it does not defend - trust boundaries, attackers, mitigations and out-of-scope threats.
The agent is untrusted. The whole design follows from that: the checks that matter run outside the sandbox, and nothing the agent says about itself is believed.
The last column of the attacker table says what covers each row. Parts marked Preview are the design and may change.
Assets
- Model and service credentials.
- The user's code and data, in the actor and in snapshots.
- The company policy and the audit trail.
- The identity of the person and of the agent.
- Other people's actors and data.
Trust boundaries
| Boundary | Trusted? | Notes |
|---|---|---|
| B1: actor to DefenseClaw | Untrusted | Only the token Substrate's egress gateway adds counts, and the gateway verifies it and checks the actor is alive with that UID. Bodies, session IDs, timestamps and paths are claims. No request header is ever echoed |
| B2: DefenseClaw to Substrate | DefenseClaw's own service account | It has the OpenFGA roles to read actors and templates, write egress policies, and create, fork, proxy and suspend actors in launcher atespaces, and nothing more |
| B3: administrators | Trusted for their scope | Chart values and signed policy, checked against trust anchors held in an admin-only Secret |
| B4: Agent Substrate | Trusted for the sandbox, the egress gateway and the identity CA | Not defended against: cluster administrators, node root, a sandbox escape |
Attackers and what stops them
| Attacker | Goal | What stops it | Notes |
|---|---|---|---|
| A compromised or prompt-injected agent | Exfiltrate data or secrets | Default-deny network; the callout checks every request; secrets are placeholders swapped only on bound hosts; exact-value matching on prompts and egress for any exposed value; tool chains remember a secret read when a later request leaves | Default deny, a listed feed host refused, secret-shaped tokens and an exposed value caught, no bearer value in the actor's files. Preview: the tool-chain check at egress on a chart install |
| The same agent | Bypass the guardrails | The model provider isn't in its allow list, so every model call passes the proxy; Substrate forwards only HTTP and TLS that match an allow rule, so WebSockets, tunnels and raw TCP carry nothing out (the connect itself completes, see Known limits) and non-DNS UDP is dropped; hook config is root-owned and the agent runs as an ordinary user | /llm serves only model paths; a WebSocket upgrade is refused (403); raw TCP to a public address on ports 22, 443 and 9999 connects but carries nothing (no SSH banner from github.com:22, TLS to the bare address is reset); hook tamper checks cover Claude Code, Codex, OpenCode, Copilot CLI, Hermes, Kiro, Antigravity and Devin. Amp can't be protected and is refused in managed |
| The same agent | Pretend to be another actor or person | Identity comes from a Substrate-signed token and a live-UID check, not from anything the agent sends. A worker token, a stale UID or no token is refused. The actor listener serves only actor routes and the admin listener is unreachable | No token, a forged x-defenseclaw-actor, a worker-for-actor token and a wrong audience are refused; a recreated same-name actor's old token is refused; admin paths answer 404 on the actor listener |
| The same agent | Use another actor's session or ask approval | Approvals are keyed to the actor UID. A fork inherits findings but not approvals. The relay session token is per person and per actor and is verified for the calling actor only | The relay refuses a request with no session token and accepts one bound to its own actor; a queued ask is visible to its owner only. Preview: the fork rule and a token for another actor against a live relay |
| A user | Loosen their own policy | Policy lives in the cluster. The profile can only tighten the company floor. Users see only their own policy | A user naming a profile they aren't mapped to is refused. Preview: tightening against a live floor |
| A user | See another user's data | Usage, policy and secret names are own-data only. The fleet view is admin-only on its own listener. Administrators see the inventory (list, status, delete, policy reset, each audited as them) but never another person's session: connect, exec and session certificates are the agent's own person's only | Another person's agent gives the same answer as one that doesn't exist; asks are own-only. Preview: secret names (usage isn't available yet) |
| Someone with Kubernetes access | Edit an agent's allow list | The controller reverts the change and records who made it. After three reverts in ten minutes it raises a policy_conflict alert and keeps the agent on deny-only (the DefenseClaw rule alone): a later change is replaced with deny-only again, so it never adds access | The revert, the conflict rule and an admin policy reset apply |
| Someone with Kubernetes access | Start agents outside DefenseClaw | Only DefenseClaw can create actors in launcher atespaces. Unattested templates get no network. Foreign actors are reported | A second identity is refused in a bootstrapped atespace; an unattested or wrong-signer template gets no network; a hand-written policy on a foreign actor is reported |
Someone with kubectl ate proxy rights | Take over an actor | Substrate's router allow list names who can reach actors; the chart adds DefenseClaw's identity and verify warns about any other listed client. Other access is audited as the person who did it: a refused attempt on another person's agent writes a row with the caller, the route and the target (one row a minute per caller, route and target, with a count), and the relay's session check refuses a token that doesn't name the actor's own person | A proxy by a user without the Kubernetes RBAC is refused. Note that the egress gateway's own client is on the router allow list, which doctor --cluster flags. A principal with the proxy rights (a global owner, for example) also reaches the actor's other ports, such as a dev server the agent started; the relay port still asks for a person-bound session, and secrets never sit in the actor |
| A supply-chain attacker | Replace the agent image or the kit | Templates carry a signed attestation of the image digest, kit version and scan result; the controller admits only attested digests that a profile allows; images are pinned by digest | A malicious skill or MCP server in an image stops the build; the stored attestation verifies with cosign; revoking a signing key removes the template's policy within one controller interval (about 74 s, mostly the Kubernetes Secret sync) |
| A flood of requests or hooks | Starve other actors | Fair-share rate limits per actor and per atespace answer 429 on the DefenseClaw gateway's routes (hooks, model calls, telemetry). Requests to a host in the actor's allow list go through Substrate's egress gateway and the egress callout, which checks each one but limits no actor's rate in 1.0.10 | One actor at about 390 requests a second does not slow ten others. One actor sending about 370 requests a second to an allowed host gets no 429, and the other actors' requests and egress checks stay fast |
Known limits
- Cluster administrators, node root and sandbox escapes are out of scope. They can read memory, snapshots and traffic.
- Proxy rights reach every port of an actor. Substrate's proxy forwards to any port the actor listens on, not only the relay. Anyone the router allow list and the Kubernetes RBAC let run
kubectl ate proxy(a global owner, the egress gateway's client) can open a dev server, a debug port or a preview the agent runs (for example on port 3000), with no DefenseClaw check and no DefenseClaw session. Only the relay port needs a session certificate bound to the agent's own person: it refuses everyone else (401), so the terminal, the files the relay serves and the agent's session stay protected, and secrets are never in the actor. Keep the proxy RBAC to the people who already administer the cluster, and don't serve anything from an actor port that they should not reach. - The hop from Substrate's egress gateway to the DefenseClaw actor listener is plain HTTP inside the cluster in Substrate v1.0.0, because that version verifies an
httpsupstream only against public certificate authorities. The token travels in the clear on the cluster network for up to its lifetime (5 minutes). A NetworkPolicy admits only the egress gateway to that port. Use a CNI that encrypts pod traffic where this matters. - Sign-in tokens are not revoked on the gateway. The admin listener verifies a person's access or ID token by its signature, issuer, audience and expiry, with no revocation list and no session check at the sign-in server.
defenseclaw substrate logoutends the refresh token at the issuer and forgets the stored tokens, but a copy of the access token (or the ID token) made before it keeps working until it expires: the issuer's access-token lifespan (often 5 to 15 minutes; the gateway accepts at most 24 hours).logoutprints that time. Keep the access-token lifespan short (5 to 15 minutes), and if a token may have been copied, end the person's session at the sign-in server and wait out the lifespan. - Hosts that echo requests get the real secret. A secret is swapped in on the hosts it is bound to, and some services return the request they get, headers included, or publish it:
httpbin.org(and*.httpbin.org),httpbingo.org,httpbin.io,postman-echo.com,echo.hoppscotch.io,webhook.site,*.pipedream.net,*.requestcatcher.comand*.beeceptor.comare well-known ones, and any API with a debug or echo endpoint can do the same. On such a host the real value comes back to the agent and its model in the response. The callout never reads the answer, in body mode too, so nothing masks the response. The gateway warns at start about every secret bound to a host on that list. Bind a secret only to the API that needs it, never to a test or echo service. - The terminal relay has no end-to-end TLS past Substrate's router. The session token and the terminal and file traffic are plain inside the proxied connection, on the cluster network between the router and the actor. Someone who can read pod traffic there can see what you type and the files you push or pull. The session token they could also see opens one attachment only, is bound to you and that actor, and is checked by the relay of that actor only. Where this matters, use a CNI that encrypts pod-to-pod traffic (for example WireGuard in Cilium or Calico).
- The relay runs as root and the agent as its own user. In a template built by DefenseClaw 1.0.10 or later the image runs the relay as root, and the relay starts the agent, its tasks, the commands a launcher runs and every file copy as the image's non-root user (
relay.agent_userin the kit configuration), with no capabilities and no set-user-ID escalation (no_new_privs). The agent can then neither signal, trace nor replace the relay. Being PID 1 is not enough on its own: gVisor, the default sandbox class, delivers SIGKILL and SIGSTOP from inside an actor to its PID 1, which a Linux kernel does not. The relay also catches and drops the terminating signals a process can catch: TERM, INT, HUP, QUIT, USR1, USR2, PIPE, ALRM, TSTP, TTIN, TTOU, ABRT, ILL, TRAP, SYS, STKFLT, XCPU, XFSZ, VTALRM, PROF, IO, PWR, and SEGV, BUS and FPE when they are sent withkill(a real fault still ends it). Known limits: a template built by an older DefenseClaw runs the relay and the agent as one user, so on gVisor the agent can stop its own relay (and with it its own actor); the relay logs a warning at start, andtemplate buildfixes it. A relay that runs as root but may not change user (a template that drops CAP_SETUID or CAP_SETGID) refuses to start the agent rather than run it as root. The relay has exactlySETUIDandSETGID(to start everything as the agent, and to open the agent's terminal and look into its home as the agent's file-system identity) andKILL(to stop the agent's processes): the template asks Substrate for them (security_context.capabilities, set bytemplate publish) and drops its other defaults (admission refuses a template left with any other capability), and the relay drops anything else it is given, on every thread. Every template built before 1.0.10 is named in an audit warning (sandbox.relay_unseparated) and indoctor(substrate.relay_separation). - A TCP connect from an actor always completes. Substrate's egress takes every TCP connection the actor opens and decides on the client's first bytes: an HTTP request or a TLS ClientHello that matches an allow rule goes on, anything else is closed. So the connect succeeds to any address and port, and a port scan from an actor sees every port open, but no data reaches the target: a protocol where the server speaks first, such as SSH, gets an empty banner, and TLS to a bare IP address (no name to match) is reset (
SSL_ERROR_SYSCALL). DefenseClaw writes only name-based HTTPS, TLS pass-through and HTTP rules, on fixed ports; it can't make the connect itself fail. - WebSocket hosts aren't inspected. Substrate 1.0.0 refuses WebSocket upgrades on inspected (
https) andhttprules. An agent that needs a WebSocket host works only if that host is inallow_passthrough_for: its traffic is then not inspected, the callout never sees it, and no secret is injected there, so the agent's own credential for it sits in the actor. Amp is the agent this stops. Substrate's egress gateway answers the refused upgrade (403,WebSocket egress is not supported) itself, before it calls the DefenseClaw callout, so the refusal is not in DefenseClaw's audit orlog.egress.blockedrecords; it shows only in the egress gateway's own access log (kubectl -n ate-system logsof the egress gateway pods). - Headers only on stock Substrate 1.0.0. The callout cannot read request bodies on the stock egress filter. It still checks hosts, methods, paths and headers, and the hook path covers MCP tool calls. Reading MCP bodies needs a Substrate build that lets the callout ask for them.
- The callout sees credentials as placeholders. On Substrate 1.0.0 the callout sees service credentials before injection (placeholders), and the actor token after. It identifies the actor from Substrate's own identity and a live-UID check.
- URL rules match the path as sent. The callout refuses spellings it can read in more than one way (an encoded slash or semicolon, a
..segment) withpath_ambiguousrather than guessing. Every matchingurl_rulesrule counts, whatever its order, and the strictest wins: deny, then ask. An approval never lifts a deny, and it covers the rule and the methods it was asked for (a request counts as every method a server framework could run it as, and an ask names them all). - Replies of OpenAI-style models on Bedrock are not inspected for tool calls yet. For Codex, OpenCode, Copilot CLI and Hermes, the proxy inspects prompts and enforces the model allowlist. A tool call in the model's reply is stopped by the hook when it runs, not by the proxy before.
- A new allow list takes about ten seconds to apply to new connections, and a freshly created or resumed actor outside the launcher has no network until its policy is written.
- A private repository is Preview.
run --cloneof a public repository works on a chart install. A private repository relies on the egress gateway adding the credential on the git host. - Snapshots hold everything the actor held. Encrypt and restrict the bucket, and use
delete. Subscription sign-ins put tokens in snapshots, so managed profiles refuse them. - Skills and MCP servers are not scanned in the cluster. skill-scanner does not run there. A skill in an attested template is trusted by its digest, because
template buildscanned it and signed the result. A skill added mid-session is not scanned, so it follows the fail mode: managed installs and the strict tier refuse it with an alert; open source allows it with an alert. The agent may read the skill's name and description before the refusal; every model call also goes through the prompt guardrails, which see that text. An MCP server the agent adds or calls mid-session (a repository.mcp.json, a written MCP config,mcp add) is checked by its config only: a server that downloads and runs code, or starts through a shell, is refused in every tier. Its tools are not scanned, because mcp-scanner does not run in the cluster either, so a server that may run code of the folder follows the same fail mode as an unscanned skill. That is every server except an installed program, a registry package the folder cannot redirect (no projectbin,node_modulesprogram,.npmrc,pip.conforuv.toml, no local package option, no code-loading environment variable), and a container image run with no mount. Tool-call hooks and the egress policy still apply to what it does. - Agents whose hook file the agent can reach. Antigravity has no managed hooks tier: its hook file and
~/.geminiare root-owned, but the agent owns its home, so it can rename~/.geminiaway and make its own. The relay watches that folder and acts on the file-system event itself: when the folder is moved (also when it is swapped away and back), replaced or removed, or when the watch's event queue overflows or the watch ends, the relay stops every process the agent started (also tools in a session of their own), says why on every attached terminal and closes it, writes a HIGH audit row (relay_guard_tamper), and refuses every new attachment and task with the reason, so the agent has to be deleted and started again. A watch that cannot be set at start refuses the agent (fail closed), with the same audit row. A tool call in the moment between the rename and the stop (milliseconds) can run without DefenseClaw's hooks, and anagythe agent starts itself with anotherHOMEis not watched (the shell call that starts it is still checked by the hook). Hook-silence detection and the egress policy still apply. Amp cannot keep its hook registration root-owned at all, so a managed install refuses it. - The actor's environment and entrypoint are allowlisted. Admission checks the template's container spec against what was attested, not only the image signature: every env variable of the image and of the template must be one of the kit's own (with the kit's exact value where the kit fixes one) or an ordinary base-image setting (locale, terminal, user identity, version pins such as
NODE_VERSION, toolchain homes), and the process must be the image's attested entrypoint and arguments. A list of the variables that load code is never complete, so anything else is refused (env_not_permitted, or "is not the attested entrypoint"), naming the variable or field.template publish --envapplies the same rule. In 1.0.10 a template built before the upgrade that fails the allowlist refuses new actors, while its running actors keep running and keep their network, with a warning row; refusing running actors comes in the next release. Fields the vendored Substrate API does not know, and any capability a template adds, are refused too.template buildrefuses git and npm settings in the image's home that run a program. Known limit: shell start files (~/.bashrc) are code by nature and are trusted like the base image's programs. - Facts from the kit are claims. Path facts for link-resolving rules come from inside the actor, so a compromised kit can lie. The rule that blocks the action doesn't depend on it, but link-resolving detections can be evaded by a compromised kit.
- Random state in a snapshot. Actors made from one golden snapshot share the memory it captured, including the state of a random number generator in a program that started before it. The relay is in the snapshot (it answers the wake-up probe), so every actor of a template shows the same relay start time; it creates its session IDs and keys only after the first resume, from the kernel's random source, and reports when it began serving the actor (
serving_sinceinstatus). Identifiers generated after the actor starts are unique per actor (checked on 20 actors of each class). - Telemetry volume. Sampling for
--taskruns never drops blocks or lifecycle records. - Chain state is kept for at most 4,096 actors per atespace. A new actor past that evicts another, idle actor's chain state: one whose window holds no secret read if there is one; within each group, an actor suspended for more than 24 hours goes first, then the one used least recently. Only when every idle actor in the atespace holds a secret read in its window does the eviction lose one: the evicted actor's next request out of the cluster is checked against an empty window and allowed. An actor can't cause this, because actors can't create actors; it takes someone who can launch 4,096 actors in one atespace, each of which has read a secret in its last 30 minutes of running time. Each atespace has its own cap, so other atespaces are not affected.
- Cross-actor findings are correlation, not proof. They appear in telemetry and detections, and never block on their own.
- Idle suspend can't see CPU use without a usage feed. The chart runs the controller without one (
--usage-listen). Without a CPU feed, a detached actor running a silent job can be suspended afteridle_suspend_after; attach, or run it with--task, to keep it running. An actor with a terminal attached is never suspended for idleness unlesssubstrate.idle_suspend_without_cpuis on. - Not in this release: Secure Client, a hosted control plane, process lineage and the kernel feed.
Agent Substrate on Amazon EKS
What differs from kind and GKE when you run Agent Substrate v1.0.0 on EKS for DefenseClaw - private nodes, S3 snapshots, microVM nodes, ECR images, credential injection and a unique token issuer.
ACP guard
Put DefenseClaw between an ACP editor client and coding agent to inspect prompts, streaming output, permissions, filesystem, terminal, and extension methods.