Skip to main content

Security

Caracal is designed to deny uncertain authority rather than guess.

Audience: Both

Context: This page explains the public security behavior that operators and reviewers need to understand when deploying or evaluating the open-source runtime.

Core Explanation​

Explicit authority model​

Caracal protects execution behind explicit authority artifacts:

  • policies constrain what may be issued
  • mandates grant signed, time-bound authority
  • delegation edges define allowed handoff paths
  • validation runs before protected execution

The design goal is to prevent silent authority expansion.

Fail-closed validation​

The authority evaluator in caracal/core/authority.py denies execution when it cannot prove authority. Denials include cases such as:

  • missing mandate
  • revoked mandate
  • expired or not-yet-valid mandate
  • invalid signature
  • out-of-scope action
  • out-of-scope resource
  • invalid delegation path

This is one of the most important security properties in the runtime.

Secret and key handling​

The runtime uses several layers of local secret material:

  • workspace secrets stored through the configuration manager
  • config-encryption support for encrypted config values
  • principal signing material managed through principal key storage helpers
  • Merkle signing keys under the workspace key path
  • local keystore material under the Caracal storage layout

Runtime Boundary​

The open-source runtime uses container separation plus a restricted in-container shell:

  • host caracal commands orchestrate Docker resources
  • caracal cli enters a restricted Caracal-only session
  • Flow uses workspace-local logs to avoid leaking runtime noise into the UI

This is an operational boundary, not a full sandbox guarantee for arbitrary hostile code. The project still assumes you control the runtime environment.

Internal Behavior​

Security-relevant implementation choices visible in the codebase include:

  • PostgreSQL is required and must fail loudly when unavailable
  • Redis and Merkle are treated as mandatory runtime capabilities
  • workspace-local operational paths are enforced even if config points elsewhere
  • Merkle keys are auto-provisioned when missing so integrity workflows stay available
  • purge and workspace deletion paths explicitly clean up runtime state and, when possible, workspace schemas

Practical Usage​

Useful operational commands:

caracal config-encrypt status
caracal config-encrypt encrypt <value>
caracal merkle verify-range ...
caracal audit export

Use these when you need to review encrypted config handling, integrity state, or audit evidence.

Vulnerability Reporting​

Public security reports should go to support@garudexlabs.com.

Do not disclose a vulnerability publicly before a fix or mitigation has been published.

Edge Cases And Constraints​

  • The public docs describe security behavior that is visible in the open-source code. They do not document enterprise-only internals.
  • Some secret storage flows degrade gracefully when a system keyring is unavailable by deriving fallback encryption material. That keeps the runtime operable, but the behavior should still be understood by operators.
  • Validation failures are not all identical. An execution can fail for scope mismatch, cryptographic failure, revocation, timing, or graph-path reasons, and the authority ledger preserves that distinction.
AI tools
On this page