Skip to content

Security: pdbethke/corralai

SECURITY.md

Security Model

corral audits code it did not write, so it runs untrusted code by design: your test suite against deliberately broken copies of your code, tests a model wrote, and, in corral review, reproduction scripts a model wrote. A model can also be steered by text inside the code it reads (a prompt injection in a comment or a test). The posture starts from that:

Nothing a model says is trusted, and nothing a model wrote runs unconfined without you choosing that. A verdict is decided by execution. certify --local signs with its local key; repository and review ledger entries are signed when a certify key is configured and otherwise remain unsigned and hash-linked.

What runs where

What runs Where Network Your model keys in its environment
certify (default): your suite against each mutant, and the written tests a disposable copy of your tree in a bwrap sandbox (container or sandbox-exec elsewhere); project dependency dirs bound read-only none no
certify --repo --substrate workspace your checkout, in place (you, or the CI runner, are the isolation boundary) yes no (scrubbed)
corral review (default): the reviewer's and verifier's reproduction scripts the same sandbox as certify, seeded with the tree at the reviewed commit; dependency dirs bound read-only; a fresh workspace per script none no
corral review --substrate workspace (what the GitHub Action runs) a fresh detached git worktree at the reviewed commit for each script, on the host, not a sandbox (the runner is the isolation boundary) yes no (scrubbed)
an agent seat (Claude Code, Codex, …), in any verb that agent's own process: for review, started in a disposable copy of the repository; for certify, in an empty temporary directory the agent's own corral's environment, so an exported provider key reaches it (and may bill instead of the subscription)

Two of those rows are not sandboxed, and that is stated here because it is easy to miss:

  • --substrate workspace mutates your real checkout. Use it on a CI runner, a scratch clone, or a tree with no uncommitted work. Restores run on a failing command, a timeout, a panic and an interrupt (SIGINT/SIGTERM); a process killed outright (kill -9, out of memory) can leave a mutant behind, and nothing detects it.
  • corral review --substrate workspace runs model-written scripts with your user's permissions, on your filesystem and network (in a throwaway worktree, with model keys removed from their environment). It is opt-in, for where that is acceptable: a CI runner, a container. Without it, review runs the scripts in the same offline sandbox as certify, and refuses when there is none. The scripts are recorded in the ledger either way, so what ran is never hidden.

On macOS the sandbox-exec backend is a weaker boundary than Linux's bwrap: it runs as your user, and a jailed command can read the start-up environment of your other processes through the kernel (KERN_PROCARGS2, measured on macOS 27, 2026-10-13; no Seatbelt rule tried blocked it). Do not run an audit there with API keys exported in other shells, or use --jail container.

Why a hijacked model cannot change a verdict

  • The kill rate is your suite's exit code, run against each planted fault. No model reports it, so no injected instruction can raise it.
  • A proven gap is execution too: a written test counts only if it fails with the fault in and passes on your real code, both run.
  • The critic is advisory. Its opinion is recorded as unverified and never moves a status. Its answer is held to a fixed schema where the provider supports one, and parsed strictly either way, so it can say only sound, vacuous or dead check.
  • Review claims are demoted unless their script reproduces, and a second seat tries to refute what stands; both seats are graded by what held.

The record

  • Unless recording is disabled, certify --repo and review write hash-linked entries to a ledger directory, by default .corral/ledger. They carry an Ed25519 signature when a certify key is configured and are unsigned otherwise. In CI, the workflow must preserve the directory, for example on the orphan branch corral/ledger; the Action alone does not persist that branch.
  • corral verify --ledger <dir> --pub <key> checks hashes, links and signatures against a public key supplied by the verifier. A signature authenticates retained bytes under that key, not the truth of the audit. An unsigned chain has no signer authenticity: its owner can recompute hashes. Removing an interior entry breaks its successor's link, but tail truncation leaves the remaining chain valid. Detecting a missing tail requires an external record of the expected head. The owner can delete or rewrite local files; the ledger is tamper-evident under these trust assumptions, not immutable or automatically complete. Whoever holds the signing key can rewrite and re-sign the whole chain, and ledger verify reports an unsigned entry among signed ones as a note, not a failure; only an external anchor (a Rekor receipt or a published chain head) detects either. Corral's own signing key is published as LEDGER_PUBKEY and anchored in Rekor.
  • certify --repo --attest --transparency logs the signed statement to Rekor, a public, append-only log, so a record can be checked by someone who trusts neither you nor us. corral certify verify refuses an unanchored record unless you pass --allow-unanchored.
  • A record's own embedded key is never a trust anchor: verification takes the key from you.

Scope of an execution proof

A proven gap demonstrates that a test passes on the unmodified code and fails on a particular planted fault. It does not prove that the original code is correct, that the mutation is a realistic production defect, or that the test expresses the intended specification. Likewise, a reproduction script's exit status is evidence to inspect, not independent proof that its interpretation is correct.

Generated tests still need human review and execution in the project's full suite. On unreleased main, per-survivor runs with multiple proven tests also check the merged file once on the unmodified code (authored_together). A failure is a warning, not a change to the individual proofs, counts or certification status. An absent result means not checked; even a pass is not a flakiness guarantee.

Keys and cost

  • Model keys come from the environment or corral's keystore (corral secret: OS keyring, then an age-encrypted file; set reads stdin, never argv). They are removed from the environment of the code corral runs: your suite in the jail or on the workspace substrate, and review's reproduction scripts.
  • An agent seat is the exception. Any seat can be a coding-agent CLI (claude-code, codex, or one you define as CORRALAI_AGENT_<NAME>), and that CLI inherits corral's whole environment, because it needs PATH, HOME and its own login variables. So a vendor API key you exported for corral's API seats reaches it too, and a CLI that prefers an API key over its subscription login will bill it. A certify agent seat starts in a fresh empty directory and the built-in definitions grant it no tools; a review agent seat reads a worktree of the repository with read-only tools (Read, Grep, Glob; codex runs --sandbox read-only, which still lets it read the host). corral does not confine what the CLI itself does; see docs/corral/agent-seats.md.
  • A run spends money. --max-tokens caps an audit's tokens across every audit seat; corral review has no token cap. In the GitHub Action, a pull request from a fork gets none of your secrets, so it cannot spend your key — it fails for want of one unless the job is guarded. Never switch to pull_request_target to make fork PRs run: it hands your secrets to a workflow that checks out the contributor's code. The Action docs say how to guard it.

The optional daemon (corral-wrangler, frozen)

No audit needs or reads the daemon. For those who run it, its model is the one below: it coordinates a herd of agents and assumes any agent can be hijacked, so it relies on containment and on every action being attributable.

Prevention (containment)

The blast radius of a compromised agent is bounded by construction, not by trust.

  • Agents are jailed. An agent's shell commands run in a bwrap sandbox: no network by default, filesystem confined to its workspace, host $HOME and secrets stripped from the environment. The agent process is confined at the point it executes anything.
  • The credential boundary. The git/forge token lives only in the brain. It is scrubbed from the process environment right after load, injected into a clone/push URL for exactly one network call, and never written to .git/config (which an agent could read) or any log. Agents hold no credentials — they ask the brain to perform git operations.
  • Per-forge credential isolation. With multiple forges configured (GitHub / GitLab / Gitea), a token is only ever used against its own host — one forge's token is never injected into another forge's URL.
  • The fleet oracle is sandboxed. The free-form "ask the fleet" feature has an LLM generate a read-only SQL query, but it runs inside a locked DuckDB connection (disabled_filesystems, extension-autoload off, lock_configuration) so a generated query cannot read local files, attach other databases, hit URLs, or reach environment secrets — it can only read the curated fleet metadata. Verification is fail-closed.
  • The fleet is metadata-only. What a brain syncs to the shared fleet (and thus what the oracle can reach) is a curated, per-table column allowlist of mission/task/finding metadata — counts, roles, models, severities, outcomes, timestamps. Agent-authored content, reference/RAG bodies, memory text, and free-form JSON detail values are not synced: JSON columns that cross are value-sanitized to a fixed key whitelist at the sync boundary (a regression test seeds a canary and asserts it never appears in the synced table). The one deliberate exception is the mission directive — synced as mission identity so a mission is recognizable across the fleet. Treat the directive as identity, not as a secret; if that matters, redact it before it leaves the brain.
  • Knowledge is trust-tiered. Agent-written "lessons" and ingested reference material are unvetted — searchable as clearly-fenced data, but never auto-injected as an authoritative instruction into a future mission. Only human-vetted knowledge is authoritative. This kills the "poisoned document propagates through the herd" worm.
  • Coordination between daemons is signed and fail-closed. Brains have Ed25519 identities; coordination intents are signed and verified against a trust registry, replay-protected, and advisory-only — a brain publishes its own signed intents and reads verified peers'; it can never call, command, or coerce another brain.
  • Least privilege elsewhere: an SSRF guard on the MCP gateway, bounded agent-spawn governance, per-IP and per-principal rate limits, a scoped read-only observer token, and OIDC + a per-principal authorization allowlist.

Detection (forensics)

Because all agent traffic funnels through the brain (the single trusted egress), the brain is the forensic authority.

  • Every consequential agent action is recorded — the audit trail, telemetry, mission/task/finding history, and memory authorship — and is attributable to a verified principal.
  • Agents cannot forge or erase their own trail. They act through the brain, which records the action as a side effect. The subject of the record does not control the ledger.
  • The record is queryable in natural language (the fleet oracle) — "what did agent X do across every mission? who ingested that document?" — so an incident can be reconstructed.

Prevention bounds what a hijacked agent can do; forensics ensures you can always see what it did.


Verify the claims yourself

The security properties above are backed by adversarial tests. Don't take them on faith — run them. (Sandbox/bwrap tests require go test, not a direct shell, because they nest user namespaces.)

go test ./...            # everything

The load-bearing suites, by claim:

The oracle cannot exfiltrate (internal/oracle)

  • TestSandboxExfilBlocked — an 11-vector matrix (read_text/read_csv/read_blob/glob/ read_json/local ATTACH/COPY/URL fetch/second-statement/obfuscated/pragma_*) — every one is blocked, and a seeded canary file's contents never surface.
  • TestLockdownBlocksFilesWithoutValidator — proves the DuckDB config lockdown (not just the string validator) blocks file reads, and that the lockdown is irreversible.
  • TestGetenvCannotReadScrubbedSecret — getenv() in a generated query cannot read a scrubbed secret.

Knowledge-poisoning worm is contained (internal/memory, internal/fence, internal/mission)

  • TestRecallLessonsSharedOnly — agent-written (private) lessons are never auto-recalled into instructions; only vetted (shared) lessons are.
  • TestUntrustedNeutralizesEmbeddedSentinel — untrusted content can't forge or escape the data fence.

A daemon's identity is unforgeable (internal/attest, internal/fleet)

  • TestVerifyRejectsTamper / TestVerifyWrongKeyFails — tampered or impersonated intents fail verification.
  • TestRegisterTOFUPinAndConflict — a brain cannot overwrite another brain's pinned identity.
  • TestActiveClaims_ForgedSigDropped / TestActiveClaims_ImpersonationDropped / TestActiveClaims_ReplayResurrectionRejected — forged, impersonated, and replayed claims are all dropped before they can influence a decision.

The credential boundary holds (internal/repo, cmd/corral, internal/sandbox)

  • TestPushCredRegistryStrict — a token is never injected into a foreign forge's URL.
  • TestTokenNeverPersistedInConfig — the token never lands in .git/config.
  • TestMinimalEnvHasNoGitToken / TestRunEnvIsSecretFree — a jailed subprocess's environment is secret-free.

The jail confines (internal/sandbox)

  • TestBwrapConfinesWritesAndReads — writes outside the workspace and reads of sensitive paths fail.
  • TestBwrapWrapNetOffByDefault — no network unless explicitly enabled.

What this does not claim

Honesty is part of the model.

  • It does not make an LLM immune to instructions in content it reads. Fencing untrusted data is hardening, not a guarantee; the control is that unvetted content can't reach an authoritative position and that a fooled agent is contained. If an agent chooses to follow injected text in fenced reference data, containment (jail, no credentials, human PR review) is what limits the damage.
  • It does not defend against a malicious insider holding a valid key. Attestation between daemons stops identity forgery, not an authorized brain publishing false claims; that is mitigated by advisory-only semantics, TTLs, and revocation, not prevented.
  • It assumes a single trust domain. Coordination between daemons assumes every participating daemon belongs to one owner; it is not multi-tenant isolation.
  • --substrate workspace is not sandboxed, for certify --repo and corral review alike (see "What runs where"); both verbs' default substrate is.
  • It has not been battle-tested at scale. The properties are proven by design review and the adversarial tests above; they have not (yet) survived a hostile production adversary.

Reporting a vulnerability (coordinated disclosure)

Please report suspected vulnerabilities privately — do not open a public issue. Use the repository's GitHub Security Advisories ("Report a vulnerability") so a fix can be prepared before disclosure: https://github.com/pdbethke/corralai/security/advisories/new. Include reproduction steps and, ideally, a failing test in the style above.

We follow coordinated disclosure (aligned with ISO/IEC 29147 disclosure and 30111 handling):

  • Acknowledgement: within 3 business days.
  • Triage + initial assessment: within 10 business days.
  • Fix & disclosure: coordinated with the reporter; a public advisory + credit (unless you prefer anonymity) once a fix is available, targeting 90 days or sooner for severe issues.
  • Safe harbor: we will not pursue or support legal action against researchers who act in good faith, avoid privacy violations and service disruption, and give us reasonable time to remediate before public disclosure.

Corralai is source-available under the Elastic License 2.0; see LICENSE.

Supply-chain security posture (our own methods)

We hold corralai's own build and distribution to the standards it helps others meet, and publish the evidence:

  • Provenance: a release is a source tag, installed with go install and checked against the Go checksum database; no SLSA build provenance is produced yet. The console UI bundle's manifest is signed with an Ed25519 release key, and the release workflow refuses to publish a version whose committed signature does not cover it.
  • Scoring: an OpenSSF Scorecard runs on every push to main (see the badge in the README).
  • SBOM: an SPDX Software Bill of Materials is generated in CI.
  • Vulnerabilities: govulncheck gates every merge (scripts/check-security.sh); gosec static analysis runs alongside it. CodeQL analyses the Go and the site's JavaScript/TypeScript on every push and pull request to main, and weekly.
  • Dev process: mapped to NIST SSDF (SP 800-218); the local console is verified against OWASP ASVS.

There aren't any published security advisories