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 --localsigns 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 | 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 workspacemutates 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 workspaceruns 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 ascertify, 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.
- 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.
- Unless recording is disabled,
certify --repoandreviewwrite 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 branchcorral/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, andledger verifyreports 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 asLEDGER_PUBKEYand anchored in Rekor.certify --repo --attest --transparencylogs 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 verifyrefuses 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.
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.
- Model keys come from the environment or corral's keystore (
corral secret: OS keyring, then an age-encrypted file;setreads 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 asCORRALAI_AGENT_<NAME>), and that CLI inherits corral's whole environment, because it needsPATH,HOMEand 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. Acertifyagent seat starts in a fresh empty directory and the built-in definitions grant it no tools; areviewagent seat reads a worktree of the repository with read-only tools (Read,Grep,Glob;codexruns--sandbox read-only, which still lets it read the host). corral does not confine what the CLI itself does; seedocs/corral/agent-seats.md. - A run spends money.
--max-tokenscaps an audit's tokens across every audit seat;corral reviewhas 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 topull_request_targetto 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.
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.
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
bwrapsandbox: no network by default, filesystem confined to its workspace, host$HOMEand 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
detailvalues 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.
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.
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 ./... # everythingThe 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/localATTACH/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.
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 workspaceis not sandboxed, forcertify --repoandcorral reviewalike (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.
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.
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 installand 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:
govulncheckgates every merge (scripts/check-security.sh);gosecstatic analysis runs alongside it. CodeQL analyses the Go and the site's JavaScript/TypeScript on every push and pull request tomain, and weekly. - Dev process: mapped to NIST SSDF (SP 800-218); the local console is verified against OWASP ASVS.