Security Model

Security Model

This page states what is protected, where trust changes hands, which controls exist, and which risks are accepted. It follows the shipped docs/security.md, which carries a test reference for every control and is the authoritative version. Every control there has a status: Required means planned, Implemented means code exists, Verified means a named test exercises it. Nothing is described above its status.

Assets, in priority order

1. The operator's credentials and host: the GitHub token, SSH keys, the shell environment, the container engine socket.
2. The destination repository: its branches and the truthfulness of what a pull request claims.
3. The operator's source checkout, which is never written.
4. Validation evidence: the module cache, snapshots, proposal records.
5. Model spend.

Trust boundaries

Boundary	What crosses
Operator to the tool	flags, configuration, approvals; fully trusted
Host process to repository content	every file is untrusted; manifests are parsed, files are delivered to the model as data
Host to execute containers	a read-only snapshot and cache go in; an exit code and capped output come out
Host to acquire and mutate containers	manifests go in; cache and staging files come out; the network is reachable by configuration
Host to the tool container	nothing from the repository goes in; the built scanner binary comes out, copied by the host. The network is reachable by configuration (proxy.golang.org and sum.golang.org only)
Vulnerability scanner and database to the host	the pinned scanner release and the database snapshot as identified; the binary and database files on disk between provisioning and use, and the scanner's output, are the exposure. Both are mounted read-only into execute; JSON findings come out, parsed fail-closed
Host to the model	prompt with repository excerpts out; decisions in, validated and policed
Host to GitHub	pull request bodies and branch names come in as data; a push and a pull request go out under approval

Controls, grouped by what they defend

Against instructions planted in the repository. The agent has no shell, no network tool, and no file access outside the scratch clone. Remote actions need a purpose-specific approval. Policy is evaluated by the runtime with no model input. Edits are bounded by scope on the projected diff, protected paths, budgets, and human review. Verified, including by a scenario that plants instructions in a README, a comment, and test output.

Against malicious build or test code. The execute profile has no network, a read-only snapshot and module cache, a read-only root, an empty environment, an unprivileged user, dropped capabilities, resource limits, and a timeout. Verified against a real engine.

Against a container silently running against nothing. A mount probe with unique markers fails hard when the engine cannot see host directories. Verified.

Against evidence drift. Validation runs on a tree materialized from raw objects and verified file by file, never on the working tree. Verified.

Against manifest tricks. Replace, exclude, retract, go, and toolchain directives must be byte-identical to base at every gate; the toolchain is local only; cgo, vendoring, workspaces, submodules, and local replaces are refused. Verified.

Against unauthorized dependency changes. Exactly the eligible target, once per run; transitive increases bounded by the closure; no reversions; direct dependencies preserved; tidy idempotence; cache verification; target resolution. Verified.

Against writes through aliases or escapes. Symlink components refused on every file tool, os.Root containment, explicit traversal and .git refusal, then lexical protected-path matching. Verified.

Against Git-level execution on the host. Separate git directory, isolated hooks path, global and system configuration disabled, submodule recursion off, fixed argument vectors, no shell. Verified.

Against modification of the operator's checkout. Read once at clone; dirty checkouts refused; every benchmark run asserts an unchanged status. Verified.

Against a false success claim. Readiness is code: bound validation, conclusive checks, introduced findings, manifest rules, protected paths, scope; evidence admissible only from completed steps; a frozen proposal verifies by hash, ref, tree, and parent. Verified.

Against a proposal altered between review and publication. The publication approval is bound to the proposal id and hash; on resume the proposal is re-verified and the working tree must still match. Verified.

Against credential leakage. Containers get an empty environment; the push token lives in a process-scoped variable read by a credential helper, never in arguments; the API token is a bearer header; nothing writes tokens to the store. Verified.

Against duplicate or wrong remote actions on recovery. Operations are journaled before dispatch with markers; reconciliation reads remote state across ref and pull request states and never recreates a marked pull request. Verified.

Against concurrent writers. Exclusive OS lock per run and per data directory; no takeover, no heartbeat. Verified.

Against resource exhaustion and spend. Container limits, output caps, timeouts, and step, failure, loop, call, token, cost, and time limits, plus repair budgets. Verified.

Against evidence poisoning through the build cache. Every validation, and every readiness or tool command in execute, mounts a new, empty, randomly named build cache; execute refuses to run without one. Verified by TestFreshBuildCache_IsolatesValidations and the execute, baseline, and scripted fresh-cache tests. Within one validation, build, vet, and test share a cache, so code that validation runs can still affect that validation's own result.

Against another local account writing the world-writable caches. The data directory is created owner-only and tightened or refused otherwise (TestPrivate_CreatesTightensOrRefuses). Verified for the modes; the mount below an owner-only parent verified on colima only, with native Linux Docker left to CI's integration job, which had not yet run this change.

Against a scanner or database other than the pinned and identified ones. The scanner is built per image digest in the tool profile, checked against the checksum database, and verified by sha256 and build information on the host before every scan; the database snapshot is content-addressed and verified before every scan; a mismatch is an error, never a rebuild. Only execute mounts them, read-only. Verified (TestEnsureScanner_MismatchIsRefusedNotRebuilt, TestFetch_Refusals, TestScan_TamperedInputsRefusedBeforeScan, TestScanMounts_ExecuteOnlyAndReadOnly, TestTool_IsolatedProfile).

Against a scan that did not finish being read as clean. The scanner's output is parsed fail-closed; an inconclusive scan is reported as such (vulns exit 3, outcome scan_inconclusive). One gap remains: a stream cut exactly at a message boundary after the analysis reported finishing cannot be detected, and can only drop findings, never add them. Verified, with that gap.

Against advisory text steering the proposal. Database text and call paths enter the proposal body only through one function that escapes, bounds, and quotes them in a code span. Verified (TestAdvisorySection, TestUntrusted).

Against a proposal claiming an advisory fixed on evidence that does not show it. Each scan is bound to its tree, configuration, image, scanner, database, and Go version, and readiness requires a conclusive bound post scan, every targeted finding gone, and nothing introduced or escalated. Verified (TestCheckScans).

Against an indirect upgrade undone by tidy. Gate B compares build lists in vulnerable selection. Verified (TestVerifyBuildList).

Against a hijacked or rushed release adopted at once. A version cooldown of 72 hours by default makes a too-new version, or one with no publish time, ineligible; vulnerable selection waives it for the version that clears an advisory and says so. Verified (TestCooldownReason, TestDiscover_Cooldown, TestCooldown_WaivedOnlyForTheAdvisoryFix). The publish time is what the module proxy reports; a proxy that lies about it defeats the control.

Accepted risks

Risk	Why accepted
Build cache poisoning within one validation	each validation has its own new cache, but build, vet, and test inside it share one, so code that validation runs can affect that validation's own result
Container escape	nothing beyond dropped capabilities and no-new-privileges; hostile repositories are out of scope
Egress during acquisition	restricted by Go configuration, not by the operating system; no repository code runs in those profiles
Malicious dependency version	the checksum database verifies integrity, not intent; code runs only in execute; the human reviews the pull request
Local data directory tampering	hashes catch corruption and bugs, not a local user with write access
Container engine socket access	the operator already holds it

What is not claimed

That a proposal from vulnerable selection fixes every vulnerability: it clears the findings the scanner reports in one module, against the database snapshot it names, and a module none of whose packages the scanner loads is not reported at all. That the database is correct or complete. That a standard-library finding is fixed: none is. Isolation sufficient for deliberately hostile repositories. OS-enforced egress control during dependency acquisition. Protection against a compromised container runtime or kernel. Protection of evidence from a local user with write access to the data directory. Confidentiality of repository content from whichever model provider is configured.