Enterprise Security Readiness

This page is the single source of truth for evaluating Caracal’s security posture and supply-chain trust. It is written for enterprise security, procurement, and platform teams who need to verify that the project follows security and operational best practices before adopting it.

Each control carries a status:

Implemented — enforced in code, CI, or the release pipeline today.
Documented — a stated policy or expectation the project operates under.
Planned — intended, not yet in place.
Not claimed — deliberately not asserted, because it is not independently verified.

Nothing here asserts a compliance status that cannot be proven. Where a control depends on organization settings that are not visible in the repository, it is marked Documented, not Implemented.

What Caracal Is

Caracal is a pre-execution authority layer for agents and workloads. Its Security Token Service (STS) issues scoped, signed mandates; the Gateway enforces protected-resource access; the Coordinator tracks agent and delegation state; and the Audit service preserves tamper-evident evidence. The Community Edition is licensed under Apache 2.0 and is designed to be self-hosted.

The data Caracal handles, where encryption occurs, how keys and tokens are isolated, and how trust boundaries work are covered in Review the Threat Model. Start there before a deeper review.

Security Control Summary

Area	Control	Status
Static analysis	CodeQL (security-extended) for Go, Python, TypeScript	Implemented
Dependency vulnerabilities	OSV-Scanner sweep across npm, Go, Python	Implemented
Dependency vulnerabilities	Per-pull-request dependency review before merge	Implemented
License compliance	Copyleft license deny-list on introduced dependencies	Implemented
Dependency updates	Dependabot for actions, npm, Go, pip, Docker	Implemented
Container CVEs	Trivy scan of published images (Critical/High)	Implemented
Container hardening	Distroless, non-root, pinned base digests	Implemented
Release signing	Sigstore keyless build provenance attestations	Implemented
SBOM	SBOM and provenance attached to every image	Implemented
Reproducible builds	Archives rebuilt and byte-compared in CI	Implemented
Release verification	Post-release attestation and provenance checks	Implemented
Supply-chain posture	OpenSSF Scorecard, results in code scanning	Implemented
Vulnerability disclosure	Private reporting policy and process	Implemented
Threat model	Assets, boundaries, encryption, key isolation	Documented
Incident response	Defined response process	Documented
Branch protection	Protected `main`, required review	Documented
Maintainer MFA	MFA required for maintainers and committers	Documented
FIPS validation	FIPS-validated cryptographic modules	Not claimed

How Releases Are Signed

Releases are signed with GitHub Artifact Attestations, built on the Sigstore keyless model. Signatures are produced in the release workflow using short-lived keys issued to the workflow’s OpenID Connect identity, so no long-lived signing key is stored on any distribution server. The trust root is Sigstore’s transparency log: verification confirms that an artifact was built by the Garudex-Labs/caracal release workflow.

CLI and Console archives are checksummed in SHA256SUMS and carry build-provenance attestations.
npm packages publish with provenance.
Container images carry both provenance and SBOM attestations.

Verification steps for archives, images, and packages are in Verify a Release. The bundled installers run gh attestation verify automatically.

How SBOMs Are Generated

Every container image is built with SBOM and provenance generation enabled in the release pipeline. The SBOM is attached to the image as an attestation in the registry and can be inspected with the registry tooling:

docker buildx imagetools inspect ghcr.io/garudex-labs/caracal-<service>:<tag> \
  --format '{{ json .SBOM }}'

For a source-level dependency inventory across all ecosystems, the weekly OSV-Scanner workflow enumerates and checks the npm, Go, and Python dependency graphs from their lockfiles.

How Vulnerabilities Are Handled

Reporting. Vulnerabilities are reported privately through GitHub Security Advisories or email, never as public issues. The full policy, required report format, and response timeline are in Report a Vulnerability.
Detection. CodeQL (security-extended) runs on pull requests and on a schedule. OSV-Scanner runs weekly across every dependency ecosystem and reports into GitHub code scanning. Trivy scans published container images weekly for Critical and High CVEs.
Triage. Findings surface in the repository’s code scanning view as a single consolidated feed, so maintainers and evaluators review one source instead of disparate scan logs.
Response. Confirmed incidents follow the documented incident response process, and fixes ship through the standard signed release pipeline.

How Dependencies Are Reviewed

Automated gate. A scheduled dependency review runs every two days over the changes merged to main in that window and fails on newly introduced High-or-higher vulnerabilities and on a copyleft license deny-list. It is skipped automatically when no commits landed in the window.
Updates. Dependabot opens grouped weekly update pull requests for GitHub Actions, npm, Go modules, pip, and Docker base images. Updates pass the same CI, dependency review, and code review as any other change.
Pinning. GitHub Actions are pinned to commit SHAs, container base images are pinned to digests, and language dependencies are resolved from committed lockfiles (pnpm-lock.yaml, go.sum, Python *.lock). Reviewer guidance for dependency changes is in the repository contributing guide.

How Maintainers Enforce Controls

The following are Documented expectations for the project’s maintainer organization. They depend on GitHub organization and repository settings rather than repository files, so they are stated as policy rather than asserted as independently verifiable from the source tree:

Multi-factor authentication is required for every maintainer and anyone with commit access.
The default branch main is protected: direct pushes are disallowed and changes land through reviewed pull requests.
Contributor pull requests require at least one approving maintainer review and passing CI; authors do not approve or merge their own changes.
Release and publish workflows run from protected CI environments with minimal, scoped permissions.

OpenSSF Scorecard runs weekly and publishes its results, giving an external, repeatable signal for branch protection, token permissions, pinned dependencies, and other repository health checks.

How Container Images Are Hardened

All service images are built to run safely with least privilege:

Minimal base. Final stages use Google distroless images pinned by digest, with no shell or package manager in the runtime layer.
Non-root. Images run as an unprivileged user.
Read-only root filesystem. Images are designed to run with a read-only root filesystem; only declared state directories under /var/lib/caracal need to be writable.
Dropped capabilities. Images require no added Linux capabilities; deployments should drop all capabilities and set no-new-privileges.
Reproducible, multi-stage builds. Build and runtime stages are separated so build tooling never ships in the runtime image.

Recommended Kubernetes securityContext and runtime hardening settings are in Harden Security Posture.

When a base image carries a CVE that upstream has not yet rebuilt to fix, and no newer pinned digest is available, the finding is tracked in a time-boxed .trivyignore.yaml entry with a justification and an expiry date. The suppression expires automatically so the finding resurfaces for re-evaluation once a fixed base image is published, keeping the weekly container scan free of un-actionable noise without losing the audit trail.

How the Project Approaches Supply-Chain Trust

Caracal aligns with the SLSA build-provenance model and OpenSSF best practices:

One clean source of truth per signal: code scanning for vulnerabilities and static analysis, Scorecard for repository health, attestations for build provenance. Scans are scheduled rather than duplicated per push to avoid noise.
Build provenance is generated and verifiable for every released artifact.
Releases are reproducible: the pipeline rebuilds archives and byte-compares them against the published artifacts before signing.
Dependencies are pinned, updated on a fixed cadence, and gated on review.

Regulated-Enterprise and FIPS Readiness

This section states clearly what is and is not supported for regulated customers.

Cryptography in use. Caracal signs mandates and audit evidence and uses HMAC for stream and audit integrity. Cryptographic operations rely on the standard libraries of the Go, Node.js, and Python runtimes used to build and run the services.
FIPS status — Not claimed. The project does not claim FIPS 140-2/140-3 validation. The default release artifacts are not built against FIPS-validated cryptographic modules, and no FIPS self-test or certificate is asserted.
What regulated customers can do today. Because services are distributed as container images, an operator who requires FIPS-mode cryptography can run them on a FIPS-validated host or base platform and supply a FIPS-validated runtime where their compliance program requires it. This is the operator’s responsibility and is not verified by the project.
Encryption boundaries. Transport security (TLS) is terminated and configured by the operator; see Harden Production. Key and secret isolation is described in Rotate Keys and Secrets and the threat model.
Planned. A documented, tested FIPS-mode build path is a candidate for a future release and is currently marked Planned, not available.

What an Enterprise Team Should Review

Review the Threat Model — assets, trust boundaries, encryption, and key and token isolation.
Report a Vulnerability — the vulnerability disclosure policy and response timeline.
The repository’s OpenSSF Scorecard result and code scanning alerts for current, independent security signals.
Verify a Release — confirm you can validate signatures, provenance, and SBOMs for the artifacts you intend to run.
Harden Security Posture — the production hardening checklist, including container securityContext.
The Regulated-Enterprise and FIPS Readiness section if you operate under FIPS or similar mandates.