Threat model

What CTRLRun defends against, what it deliberately does not, and the fail-closed rules that follow from both.

CTRLRun sits in the execution path of consequential actions. This document states what it defends against, what it explicitly does not, and the fail-closed rules that follow. It covers every shipped version through v0.6, and grows with the roadmap.

Assets

• Correctness of consequential effects — an effect happens at most once per intent, and only as authorized.
• Integrity of human approval — what a human approved is what executes.
• Integrity of evidence — receipts reflect what happened.

Trust boundaries

 untrusted ─────────────┐        trusted ──────────────────┐
  agent reasoning       │         CTRLRun process           │
  LLM outputs           │         policy file               │
  tool outputs          │         StateStore (SQLite file)  │
  retry logic           │         approver's shell          │
  other agents          │                                   │

The agent is treated as a potentially compromised or hallucinating principal. Everything it proposes is verified; nothing it asserts is trusted.

In scope — CTRLRun v0.1 defends against

Threat	Control
Hallucinated or unlisted action	Unknown action → DENY
Prompt-injected agent proposing a forbidden action	Policy DENY; approval required for sensitive ones
Agent mutates action after human approval	Approval bound to action_hash; mismatch → DENY
Agent replays a consumed approval	Single-use, atomic consumption
Stale approval	Expiry checked at consumption
Duplicate execution on retry after timeout	Effect key + AMBIGUOUS + retry refused
Duplicate execution from concurrent agents	Atomic cross-process reservation
Silent loss of in-flight effect (worker crash)	Lease expiry → AMBIGUOUS, never released
Misclassifying unknown outcome as failure	Only NotExecuted → FAILED; else AMBIGUOUS
Malformed or missing policy	Load-time error; no Control without valid policy
Float-based hash collisions/mismatches	Floats rejected in arguments

In scope — CTRLRun v0.3 adds

The authority model answers a question v0.1 and v0.2 could not: who is acting, and what are they entitled to? Everything above still holds; these are the threats the second axis closes.

Threat	Control
A principal proposing an action nobody granted them	authority: present → no grant means DENY, including for actions the policy allows outright
An agent widening its own authority by delegating	Containment on every dimension, at creation and at every evaluation
A delegated grant that silently inherits what it does not name	Omission is rejected, never treated as unconstrained or inherited (§5.4)
A delegation handed to a wider population than its parent covered	A child subject may not carry a wildcard or drop its parent’s user
A compromised chain that has to be cut in a hurry	ctrlrun revoke is transitive by structure: one write cuts a chain of any depth
Authority outliving the credential that created it	delegable: true requires expires_at; Control.delegate refuses an expired by
A credential that has expired mid-action	Refused before authority and before policy; a lease extension is refused and the record becomes AMBIGUOUS by the ordinary path
A forged or tampered token	JWTIdentityProvider verifies the signature against a JWKS or a pinned key, with the algorithm taken from its own allow-list and never from the token (RFC 8725 §3.1)
An ID token presented as an access token	token_type is required and typ is checked — the cross-JWT confusion of RFC 8725 §2
A token for another audience or issuer	aud by exact membership on either wire shape, iss exact, exp required
Signing keys fetched from somewhere else	JWKS over HTTPS only, redirects refused outright, a duplicate kid refused rather than resolved, a failed fetch never emptying the cache
An unauthenticated principal reaching an authorization decision	--principal-from-client-info removed; AcsControlHook refuses an Authority without an identity provider
An environment chosen by the caller	The environment is set once on the Control and is never read off the wire

In scope — CTRLRun v0.9 adds

The authority model bounded one action and never an aggregate: a grant saying amount_lte: 5000 is silent about the thousand actions that each pass it. v0.9 answers how much, over which records, for which task? Everything above still holds.

Threat	Control
An agent draining an account one permitted action at a time	A consequence budget on the grant: a metric, a limit, a rolling window. The sum is consumed when the effect is reserved, in the same transaction, so two processes cannot both pass a check and then both spend
A budget check racing its own consumption across hosts	The charge is written inside the reservation’s transaction, under a per-grant lock taken in a fixed order on Postgres. Verified multi-process against Postgres, not argued
An agent buying authority by manufacturing ambiguity	An AMBIGUOUS effect holds its charge until a human or a reconcile hook resolves it. Ambiguity is not a refund
A delegation spending its parent’s budget over again	Every grant in the chain is charged on every reserve, so a child’s spend is its parent’s spend
A child grant taking a higher rate than its parent	Containment on both axes: no higher limit, and no shorter window, because a shorter window over the same limit is a higher rate
A negative amount refilling a budget	A metric value that is negative, missing, or not an integer is refused, with an event and a receipt. Absence is never counted as zero
An agent reaching for a record that is not its principal’s	Where a deployment configures a scope provider, the kernel asks it before reserving anything, and refuses out_of_scope. This is the bite on an identifier an attacker chose
A scope source that is down failing open	scope_unavailable, a distinct refusal from out_of_scope, fail-closed. Observe mode reports which
A grant or delegation issued for one unit of work being spent on another	tasks: on a grant, attenuated by the same child ⊆ parent rule as every other dimension

What a budget does not do

Stated here because a limit reads like more of a defence than it is.

• A budget cannot recall an action already in flight. The window rolls forward, and a reservation taken a second before it rolls commits regardless. A budget bounds what may start, never what has started.
• A budget is fail-closed against its own principal. An agent that can manufacture ambiguity can pin a budget it is not entitled to spend, because R2 holds the charge until a human resolves it. That is a denial of service against the operator’s own agents, and it is the deliberate side of the trade: the alternative is an agent that manufactures authority.
• A budget counts a metric an operator named, an argument on the action. It is not a consequence model: nothing ranks, scores or classifies what an action means, and a budget on amount says nothing about an action whose damage is not in that field.
• A budget is per store. Two deployments sharing a provider account and not a store each enforce their own, and the provider sees the sum.
• A budget is not a rate limit on the remote. It bounds authority, not traffic.

What a scope provider does not do

• It is worth what its source is worth. It is the operator’s own code answering from the operator’s own system of record. A poisoned source answers wrongly and the kernel cannot tell.
• The residual gap SPEC-v0.7.md states for preconditions applies unchanged: the check cannot run inside the atomic reservation write, so a record that changes hands in the window between the answer and the reservation is not caught.
• Only the hash of the answer reaches the receipt. An auditor can prove the scope was the one the kernel matched against, and cannot read what it contained.

What task binding does not do

• It limits blast radius; it does not detect a hijack. The task id is supplied by the caller, and an agent talked into a different goal is usually still inside the task it was legitimately given. ASI01 stays partial for this reason.
• It does not propagate across agent hops. A grant is evaluated where the action is proposed; docs/ROADMAP.md puts propagation in v0.10.

Out of scope — CTRLRun does not defend against

• A compromised CTRLRun process, host, or Python environment.
• A root attacker or a malicious administrator with write access to the policy file or SQLite database.
• A compromised external service (Stripe lying about outcomes).
• A compromised approver, or social engineering of the approver. CTRLRun proves what was approved, not that the human was right.
• Executors that raise NotExecuted incorrectly (asserting no side effect when one occurred). This is an integration bug, and it is the most dangerous one available: NotExecuted is the one exception that makes an effect retryable, so an executor that raises it after the remote acted turns the one guarantee CTRLRun is built around into a licence to act twice. ctrlrun verify does not and cannot check for it. Verify reads the operator’s configuration and supplies its own executors; it never calls the one behind @protect and never imports the module it lives in (SPEC-v0.4 §1.2). An earlier version of this line said v0.4 verify would include such a check. It does not, and the sentence was wrong when it was written.
• Data exfiltration through read actions the policy allows. CTRLRun is not DLP.
• Denial of service by flooding approval requests.
• Bypassing the decorator entirely (calling the raw function). v0.2 gateway mode narrows this; process-level enforcement is out of scope.
• A compromised identity provider. CTRLRun consumes identities: it verifies a token somebody else issued and maps the verified claims onto a Principal. It issues nothing, and an issuer that signs a token for the wrong subject has told CTRLRun the truth as far as CTRLRun can tell. Everything downstream — grants, delegation, receipts — is then wrong, correctly and consistently.
• A HeaderIdentityProvider behind a proxy that does not overwrite the header. It is worth exactly what the thing setting it is worth, and RFC 7239 §8.1 says the same of the header it standardizes. If the agent can set the header, the agent chooses its own authority. It warns at construction and it is still the operator’s call.
• A revoked token before its exp, where no feed is configured. Without one, a verified token is valid until it expires, which is why one with no exp is refused, and short lifetimes are the whole of the story. Since v0.8 a deployment may pass JWTIdentityProvider(revocations=...) a feed of Security Event Tokens, and a credential the issuer revoked is then refused at resolution. Two things that closes less than they sound: a revoked credential leaves a log line and no receipt, because resolution happens before an action exists, where an expired one leaves a receipt; and a feed is worth what its source is worth. Somebody who can write the file, or stand in front of the poll endpoint, can refuse the operator’s own agents at will, which is a denial of service against them and is fail-closed. They cannot admit a principal the issuer revoked: the feed is only ever consulted to refuse, and there is no path on which its answer makes an otherwise-invalid credential valid.
• A tenant-templated issuer. issuer is matched as an exact string, so a multi-tenant endpoint cannot be configured correctly here. Pointing it at one without pinning the tenant makes every tenant on that platform a valid issuer — stated because the fail-open is inviting.
• Authority across an agent-to-agent hop. A grant covers the principal CTRLRun resolved for this call. Propagating attenuated authority across hops is v0.10.
• Approving an authority change. ctrlrun delegate --as is an assertion typed at a shell, not an authentication; the record keeps created_via so a reader can tell an act from an assertion. Authenticating the approver remains out of scope, as in v0.1.

Known v0.4 limitations — what ctrlrun verify does not see

ctrlrun verify runs the kernel’s own failure scenarios against an operator’s configuration and reports what passed, what failed, and what could not be tested at all. The list of what it cannot see matters more than the feature does, so it is here as well as in docs/verify.md — verify sees the configuration, not the code.

• Not the operator’s executors. The function behind @protect is never called. The NotExecuted integration bug above is invisible here, because verify supplies its own executors and never imports the operator’s module.
• Not the operator’s reconcile hooks, for the same reason: a hook is a Python callable passed to @protect, and it does not appear in any file verify reads.
• Not where the decorator was placed. Code that calls the raw function bypasses CTRLRun entirely — the “bypassing the decorator” line above — and no amount of configuration-reading finds that.
• Not the deployment. Whether the proxy in front of HeaderIdentityProvider overwrites the header, whether $CTRLRUN_STATE points where the operator thinks, whether two gateways share a state file: none of it is in the document.
• Not whether the policy is the right policy. Verify has no opinion on whether stripe.refund should be autonomous to €500 or to €5. It is not a linter, it does not score, and it never says a configuration is too permissive. A configuration that permits everything and constrains nobody can pass every guarantee in the catalogue, because the guarantees are about the kernel doing what it says under that configuration.

And the corollary, stated because a badge invites the opposite reading: the badge means “declared guarantees pass” and nothing else. Not secure, not safe, not compliant, not certified, not audited.

Fail-closed rules (v0.1, not configurable)

Condition	Result
action not in policy	DENY
policy missing / malformed	cannot start
approval missing / expired / mismatched / consumed	DENY
effect key template unresolvable	DENY
effect COMMITTED / AMBIGUOUS / in-progress	reservation refused
lease expired mid-execution	AMBIGUOUS
executor raised non-NotExecuted	AMBIGUOUS
StateStore unavailable	exception; no execution

Known v0.1 limitations

• Effect key templates do not escape placeholder values. A template is literal text with values substituted in, so refund:{tenant}:{payment_id} resolves tenant="acme:evil", payment_id="p1" and tenant="acme", payment_id="evil:p1" to the same key. Arguments come from the agent, which this model treats as untrusted, so a crafted argument can make two distinct logical effects share one identity. The consequence is a refusal, not a double execution — the second attempt is blocked as a duplicate — so this costs availability, not correctness, and it fails in the safe direction. Until values are escaped, put the untrusted placeholder last, or use a delimiter the value cannot contain.
• Single-host reservation only (SQLite). Multi-host needs Postgres (v0.6).
• Approver identity is free text; no authentication of the approver (v0.3).
• Receipts are not signed, and they are not signed after v0.6 either. v0.6 adds a hash chain (SPEC-v0.6.md §6): each receipt carries the hash of the one before it, with seq inside the hashed content, so a partial tamper is detected and named — an UPDATE on one row, a DELETE from the middle, a reordering. What that closes is alteration that keeps the receipts after it: changing what receipt n says while leaving the rest in place costs a rewrite of all of them plus the head, rather than one statement. Not a truncation at the end, and not an append. Two earlier versions of this line claimed the first; a review measured both at two statements, undetected — delete the rows and rewind the head, or insert a well-formed row and advance it. The head is a row in the same database as the receipts, so it raises the cost of forgetting and not the cost of erasing; an anchor outside the database is what would close that, and v0.6 has none. What it does not close is authorship, and it does not close a database admin who can rewrite every row including the chain head: such an adversary recomputes the chain and it verifies. The malicious-administrator line above is unchanged; v0.6 narrows it rather than removing it. Nor does the chain prove that every action wrote a receipt — a receipt whose write failed leaves no gap in seq and is invisible to the chain by construction; the events log is where that is reconciled.
• No reconciliation; AMBIGUOUS always needs a human (v0.2 adds the executor reconcile hook).
• The decorator can be bypassed by code that doesn’t use it.

Known v0.2 limitations

These follow from SPEC-v0.2.md. They were written here before the code landed, which is the point — a limitation recorded only after somebody hits it is a postmortem, not a threat model. They shipped in 0.2.0 and every one of them describes behaviour you can run today.

• A lazily-validating upstream can win a retry it should not have. The gateway maps the JSON-RPC errors that the specification defines as emitted before dispatch — -32700, -32600, -32601, -32602, and MCP’s -32020 / -32021 / -32022, plus HTTP 401 and a scope-challenge 403 — to FAILED, permitting an automatic retry. They are the closest thing MCP offers to an executor raising NotExecuted (SPEC-v0.1 §5.5): the peer is stating in band that it rejected the request rather than running the method. An upstream that does work and then returns -32602 violates JSON-RPC 2.0, and CTRLRun will retry against a side effect that already landed. The alternative — mapping every error to AMBIGUOUS — makes a routine token expiry or a typo’d tool name cost a human ctrlrun resolve, which is how a guarantee becomes something people switch off. The asymmetry stays where v0.1 put it: -32603 Internal error and every unrecognized code are AMBIGUOUS.
• not_executed_on_error: true is an operator’s assertion, and is not checked. It maps a tool result carrying isError: true to FAILED for one tool. It is NotExecuted expressed in YAML by the person who knows their upstream, and it is wrong in exactly the same way if they are wrong.
• An approval does not cover input elicited mid-call. A tool call held open across an MCP multi round-trip exchange executes with inputResponses the approver never saw. Two of the three mutation paths are closed — the continuation must present the exact requestState the gateway relayed, and its arguments must canonicalize identically to the approved ones — so the approved call cannot be altered. What remains is the content of the elicited answer itself, which a compromised upstream chooses the question for. It is recorded (EXECUTION_RESUMED carries the keys and a digest) but not approved. Deny the tool if that is unacceptable. Binding an approval across an elicitation round trip was asked of v0.3 and deliberately not answered there (SPEC-v0.3.md §13); it stands.
• The gateway’s principal is not authenticated — and clientInfo is one of its sources. Closed in part by 0.3.0. --principal-from-client-info is removed: it read a field the MCP specification says implementations “SHOULD NOT rely on … for security decisions”, and it was survivable only while a policy could not address the principal at all. The authority model ended that, so the flag exits non-zero naming --principal-header. What remains is the original sentence: --principal-header is worth whatever the proxy that sets it is worth. A deployment that wants the principal verified rather than asserted uses --identity-jwt (0.3.0), which is the only option here that checks a credential.
• Reservation is still single-host. Two gateways in front of one upstream share no reservations unless they share a state file on one machine.

Known v0.3 limitations

• Authority is built at load time and is not hot-reloaded. Revocation and expiry are live — read from the store and the clock on every evaluation — but an edit to the file is not. Narrowing a ceiling, bringing an expiry forward, removing delegable or deleting a grant takes effect when the process next loads the document, which for ctrlrun gateway means a restart. The runtime lever is ctrlrun revoke, one delegation at a time, by id.
• There is no way to list delegations, so there is no way to sweep a subtree. The ids are in the events file. Cutting a chain of unknown width means setting delegable: false on the root grant and restarting, after which §5.6 rule 6 denies every descendant.
• Observe mode executes. It is the rollout path, not a sandbox: effects land at remotes and the records of them are real. What it suspends is CTRLRun’s refusals, wholesale — every ⚠ row of SPEC-v0.3.md §9 at once. It is not a per-action opt-out and cannot be made one.
• A mode: observe writer and a ≤ 0.2 reader do not mix. ReceiptResult gains observed, and Receipt.from_dict parses result into a closed enum — so an older process reading the same store raises. Upgrade every reader before switching any writer.
• Claims are receipt data, not action identity. They are deliberately outside the action hash, so an approval survives a token rotation — and equally, a claim that changed between proposal and execution does not invalidate one. Matching a grant on a claim is out of scope (§13): it needs an answer to “what does a missing claim mean” that v0.3 does not have.

Known v0.7 limitations

• A precondition fingerprint narrows the window between a human’s approval and the action’s execution, and does not close it. The recheck is a network call to the operator’s provider, so it runs strictly before consume_approval_and_reserve and cannot run inside it. A change to the resource that lands after the comparison and before the reservation is not refused. What the mechanism buys is the difference between minutes of human deliberation and milliseconds of kernel work, which is worth having and is attribution rather than prevention. ctrlrun verify’s G16 grades a change made before the comparison, because that is the half a correct kernel refuses; the residual half is pinned by a test (SPEC-v0.7.md §6.7) and is not graded, because there is nothing there for a correct kernel to do.
• The NotExecuted classifier speaks only for the requests it sent. ctrlrun.transport claims NotExecuted only where a connection it opened was handed no request byte and no send went out anywhere in the executor run. It can only see this library’s own sends. An executor that sends part of the effect through requests, through httpx directly, or on a raw socket, and then uses the classifier, can be handed a claim that is true of these connections and false of the effect. So can one that raises a claim while a sibling thread’s request is still in flight. The claim holds where every request of the effect goes through the classifier on the executor’s context, and the module says so where a reader would look. The error is in the same direction as the integration bug above, and for the same reason it is the most dangerous one available.
• A classifier that cannot observe does not claim, and that costs true refusals. Outside an executor run nothing is claimed at all, and a send on a thread that did not copy the executor’s context marks every open run, so an unrelated concurrent run can lose a claim it was entitled to. Both are deliberate: the cost is AMBIGUOUS where FAILED was true, never the other way round.
• A reused action_id leaves late writes attributable to the wrong attempt. Attempt numbers never repeat since v0.7, on every backend, but a transition still names its holder by action_id alone. A caller that rebuilds the same Action after a retry reuses the id, so a write from a lapsed attempt can land on a newer one. SPEC-v0.7.md §12.3a states the consequences, including the one where a late FAILED permits a renewal beside a dispatch that is still running, and records why the fix is a schema change deferred rather than an unavailable one.

Disclosure

Report vulnerabilities privately to [e-mail]. Do not open public issues for security reports. SECURITY.md has the process and what counts as a vulnerability.