Secure Caracal
This section covers OSS code and assets in this repository, not enterprise code, customer infrastructure, external identity providers/upstreams, or model behavior.
The Security Model in Brief
Section titled “The Security Model in Brief”Caracal’s core security idea is that programs hold authority, not credentials: instead of standing API keys, a program receives a short-lived signed pass for exactly one approved action, and every link in that chain fails closed. Four properties carry the model:
| Property | What it means | Mechanics |
|---|---|---|
| Deny by default | Nothing is callable until a resource is registered, a grant path exists, and the active policy allows the request. | Authority and Enforcement |
| Fail closed | A policy, key, replay, revocation, Session, or Approval failure stops issuance; a verification failure stops the request before the upstream. | Mandates |
| Central revocation | Ending a Session, Delegation, or Authority record invalidates dependent authority without key rotation or redeploys. | Sessions and Revocation |
| Tamper-evident evidence | Decisions and results are recorded append-only with integrity checks, replay, and dead-letter paths. | Audit and Request Traces |
What Is Enforced, Recommended, and Yours
Section titled “What Is Enforced, Recommended, and Yours”An honest evaluation separates three categories. Repository code enforces the first; documentation recommends the second; only you can provide the third.
Enforced by the code (verifiable in source and tests):
- STS fails closed on Policy, key, replay, revocation, Session, Approval, and signing failures.
- Gateway authorizes before dispatch and applies binding, egress, redirect, replay, and revocation controls.
- Published modes require integrity keys and authenticated metrics.
- Audit is append-only/tamper-evident with replay and DLQ paths.
- Runtime secrets remain outside untrusted application/agent workspaces.
- OSS behavior does not depend on enterprise code.
Recommended practices (documented, not forced): pin and verify releases, keep mandate TTLs short, use shared revocation stores in production, route provider credentials through Gateway brokering, and walk the hardening checklist before real traffic.
Your responsibilities (outside the repository’s reach): host and network isolation, TLS termination, identity-provider governance, key custody and rotation cadence, backup and restore testing, monitoring ownership, and any compliance program. Repository controls contribute evidence to those programs; they never satisfy them alone.
Choose a Review
Section titled “Choose a Review”| Goal | Page |
|---|---|
| Assets, boundaries, threats, residual risk | Review the Threat Model |
| Deployed environment review | Harden Security Posture |
| Artifact verification | Verify a Release |
| Repository evidence | Generate an Evidence Pack |
| Private reporting | Report a Vulnerability |
| Adoption controls and non-claims | Review OSS Adoption Readiness |
Review Completion
Section titled “Review Completion”Tie every claim to version, config, source/test evidence, and observed result. Repository controls do not replace host hardening, identity governance, recovery testing, or compliance programs.
Next Step
Section titled “Next Step”Start with Review the Threat Model.