Security model

What AgentBox protects, how, and — just as important — what it doesn't.

Protected assets

• GitHub App private key and installation tokens
• Repository write authority delegated to an agent
• Runtime identity and policy configuration
• Approval decisions and audit history

The delegation bound

The security claim is that an agent's authority is at most the developer's, and usually less, and that the agent is always distinguishable from the developer.

How it holds today

• Entitlements are keyed to the human, not the agent: the directory export by human email, GitHub teams by ghLogin, Jira elevation only when the ticket is assigned to human.
• Default deny narrows from there: allow rules with requires need every requirement satisfied; an outage makes them unknown, which can't satisfy an allow but still lets deny and approval apply.
• Separation is structural: the assertion's jti and runtime ID are in every decision and approval; the issuing human can't approve that runtime's requests; revocation never touches a human credential.

Where it's weaker than the claim

• The bound is emergent, not checked. A wrong team claim merely fails requires; it isn't rejected or audited as a mismatch. An allow rule written without requires opts out of the bound.
• Whoever holds the issuer key defines the developer. --human is an argument; nothing authenticates the developer to the issuer yet.
• Static exports and the 5-minute entitlement cache mean offboarding can take effect late. Revoke the runtime explicitly when a developer's access changes.
• The egress proxy and model gateway see only a source address, so the bound covers the broker's decisions, not theirs.

Both gaps are tracked on the roadmap under Milestone 2.

Implemented controls

1. Credential isolation. The key and tokens live in agentd. Authentication is added only to fixed GitHub HTTPS endpoints; redirects are rejected; client authorization headers aren't forwarded.
2. Least-privilege tokens. Minted for one numeric repository ID with only the permission the operation needs.
3. Default deny. Unknown resources and unmatched actions are denied; deny overrides approval and allow.
4. Parse before forwarding. All pushed refs are checked before any receive-pack body is sent. Malformed packets fail closed.
5. Bound approvals. Grants bind repository, refs, object IDs, runtime, and config digest; expire in 15 minutes; are consumed once, durably.
6. Separate admin channel. Approvals use an owner-only Unix socket, not the workspace listener. oidc: reviews require an HMAC signature.
7. Audit-or-nothing. Audit append failure prevents forwarding. State files are owner-only; one daemon per state directory.
8. Bounded resources. Request sizes, concurrency, headers, and upstream waits are limited. Rate limiting runs before authentication, and rejection floods are summarized rather than written per request.
9. Network isolation. The Compose workspace is internal-only with closed DNS, dropped capabilities, and no broker state.
10. Projected APIs. PR/CI access is an allowlist of methods and paths; response fields are projected explicitly and upstream error bodies aren't relayed.

Known limits

• A compromised host, broker, Docker daemon, or same-UID process can bypass controls.
• Allowed writes can exfiltrate data. A permitted push or PR can carry workspace data. Scanning is regex-based and misses encoded or split secrets.
• Reads are repository-level. There's no branch-level read filtering.
• Reviewers approve a SHA, not a diff. They must inspect the commit on GitHub.
• The approval web UI is in the trust boundary. Its admin secret can approve as any oidc: reviewer.
• The issuer key is trusted. Whoever holds it can mint any runtime identity.
• Protected-branch drift only warns. Rules are enforced at startup; the hourly recheck logs a warning.
• Allowlisted upload hosts and TLS content to allowlisted hosts are remaining egress channels.
• Unicode homoglyphs across scripts aren't detected when allowUnicodeRefs is on; reviewers see escaped code points.

Supply chain

• Zero npm runtime dependencies.
• Release images carry an SPDX SBOM, SLSA provenance, and keyless cosign signatures.
• Each image digest is Trivy-scanned (failing on fixable HIGH/CRITICAL) before it's tagged.
• CI runs checks, tests, a protocol fuzzer, and the demo on Node 22 and 24.

Reporting

The full threat model lives in THREAT_MODEL.md in the repository. Please report vulnerabilities privately through GitHub security advisories rather than public issues.