---
title: "Review the Threat Model"
url: "https://docs.caracal.run/security/threat-model/"
markdown_url: "https://docs.caracal.run/markdown/security/threat-model.md"
description: "Assets, boundaries, threats, mitigations, and validation checks for Caracal."
page_type: "reference"
concepts: []
requires: []
---

# Review the Threat Model

Canonical URL: https://docs.caracal.run/security/threat-model/
Markdown URL: https://docs.caracal.run/markdown/security/threat-model.md
Description: Assets, boundaries, threats, mitigations, and validation checks for Caracal.
Page type: reference
Concepts: none
Requires: none

---

The repository threat model covers the current open-source Caracal runtime, services, packages, deployment assets, and release artifacts.

## Assurance Case

Caracal's security requirements are met under an explicit assurance case maintained in [`governance/THREAT_MODEL.md`](https://github.com/Garudex-Labs/caracal/blob/main/governance/THREAT_MODEL.md). It argues the claim from four pillars:

- **Threat model:** threats T1–T12 each carry an owner, a required mitigation, and a verification step.
- **Trust boundaries:** every boundary names what is untrusted and where mediation happens (see [Enforce Boundaries](/architecture/trust-boundaries/)).
- **Secure design principles:** deny-by-default, complete mediation, least privilege, defense in depth, and separation of privilege are enforced in STS, gateway, control, and the data layer.
- **Implementation weaknesses countered:** input validation, token-confusion prevention, SSRF blocking, secret redaction, audit/stream integrity, and a signed, provenance-attested release path, each backed by tests and scanners.

## In-Scope Areas

| Area | Scope |
| --- | --- |
| API | Control-plane routes, admin auth, product state, step-up APIs, admin audit. |
| Coordinator | Agent lifecycle, delegation, invocation, TTL, retention, outbox. |
| STS | OAuth token exchange, signing, JWKS, policy decisions, replay, revocation, step-up, audit emission. |
| Gateway | Proxy enforcement, upstream safety, STS exchange, bindings, replay, revocation checks. |
| Audit | Redis stream consumption, append-only ledger, HMAC chain, tamper sweeps, retention, export. |
| Control | Optional invoke endpoint, engine catalog enforcement, JTI replay, rate limits, audit. |
| Relay and streams | Coordinator lifecycle relay, Redis Streams signatures, dedupe, pending-entry handling. |
| Packages and infra | SDKs, transports, connectors, Docker, Helm, migrations, installers, release artifacts. |

Enterprise-only code and customer deployments outside the provided deployment model are out of scope for this open-source threat model.

## Assets

| Asset | Why it matters |
| --- | --- |
| Agent and application authority | Controls what autonomous agents can access and do. |
| Policies, grants, zones, resource bindings | Define authorization and proxy destinations. |
| Signing keys, KEKs, admin tokens, client secrets, database/Redis credentials | Compromise enables impersonation or service takeover. |
| Tokens, sessions, JTIs, revocations, step-up state | Enforce identity, replay prevention, expiry, and emergency denial. |
| Audit events and chain state | Provide evidence for incidents and tamper detection. |
| Redis Streams and outboxes | Carry lifecycle, invalidation, audit, and revocation events. |
| Images, installers, releases, lockfiles | Define what users execute. |

## Threats and Mitigations

| Threat | Required mitigation |
| --- | --- |
| Control-plane mutation bypass | Mandatory auth hooks, schemas, zone guards, and admin audit. |
| STS over-issues authority | Deny-by-default policy, grant/session validation, step-up, replay, revocation, and signing checks. |
| Gateway forwards unsafely | Per-request STS exchange, upstream bindings, SSRF guard, header stripping, timeouts, replay and revocation checks. |
| Agent/delegation state races | Transactions, locks, outbox events, dedupe, bounded relay retry. |
| Secrets leak | File-secret resolution, redaction, no plaintext key material in responses/logs/audit/examples. |
| Agent reads operator secrets | Operator secrets outside source workspaces, private operator directories, no secret mounts in agent containers, workload-only token injection, and separate users/containers for untrusted agents. |
| Audit evidence is missing or forgeable | Append-only audit role, HMAC signing, DLQ, replay, tamper checks. |
| Stream messages are forged or replayed | HMAC signatures, dedupe, pending-entry reclaim, ack only after durable handling. |
| Control becomes unsafe command execution | Gate file, JWT auth, scope checks, engine dispatch only, no shelling out, audit. |
| Release artifact compromise | Lockfile review, trusted workflows, image/archive validation, installer secret scans. |
| Product boundary drift | Update threat model and reject OSS changes that depend on enterprise-only code. |

## Validation

Use targeted suites for the changed boundary: API/Coordinator TypeScript tests, STS/Gateway/Audit Go tests, Control/Engine tests, stream consumer tests, release checks, and broader `pnpm run ci` when shared packages, crypto, config, release, or infra change.

## Next Step

Use [Harden Security Posture](/security/hardening/) to translate the threat model into deployment checks.

## Related Pages

- [Enforce Boundaries](/architecture/trust-boundaries/)
- [Respond to Incidents](/operations/incident-response/)
- [Validate Changes](/contributing/testing/)