security: close the four audit blockers, verify what the release signs

[jordonpeterson]

Closes the four blockers from the enterprise security audit, plus the second-tier
findings and the procedural gaps that stall intake review.

Eight commits, each self-contained and separately reviewable. Two of them
(security(cli) and security(release)) carry both an original blocker fix and a
related follow-up, because they land in the same files — the commit messages say
which is which.

The four blockers

#	Finding	Fix
1	A committed .github/CODEOWNERS -> ../../outside/f made sync/apply write outside the clone and report applied, exit 0	Contained in the CLI layer, which is the layer that knows --repo. In-repo symlinks still work
2	os.Getenv("GITHUB_TOKEN") as a flag default meant Go's flag package printed the live PAT on --help and on any flag error (CWE-532)	Env resolved after Parse; --token still wins
3	jsonValue.raw copied each value's source span — quadratic in nesting, 60 KB → 962 MB	Lazy slicing, depth cap 64, 1 MB size cap. Same file now peaks at 5.8 MB
4	Actions pinned by mutable tag in jobs holding contents: write and a tap token; nothing signed	All 9 uses: SHA-pinned, build-provenance attestation, -X version stamp, version subcommand

Beyond the blockers

• The attestation is now verified. Signing that nobody checks buys very
  little — install.sh only checked SHA-256 against checksums.txt, which ships
  on the same release from the same host, so it proved integrity in transit and
  nothing about origin.
• plan is contained. It writes nothing, so this was not an escape — but it
  produced a reviewable artifact whose codeowners_path pointed outside the
  repo, and every downstream refusal fires after that review.
• The homebrew job lost contents: write (it inherited it by declaring
  nothing) and no longer embeds the tap token in a clone URL.
• Refs that git parses as its own options are rejected — --branch '--format=…' reached git's option parser.
• GitHub API paths and queries are escaped — @org/.. is a legal owner and
  produced GET /orgs/org/teams/.., which normalizes to GET /orgs/org,
  answering 200 and reporting a nonexistent team as valid.
• The differential fuzz runs on every PR — the full 500k, not a reduced pass.

Two decisions worth your attention

gh is not an install prerequisite. The point of curl | sh is a machine
with nothing on it, and gh is absent from most base images. Requiring it would
not make those installs verified — it would make them fail, and the realistic
response is a hand-downloaded tarball, verified less than before. So
PROVENANCE=auto verifies when it can and warns loudly when it cannot;
require refuses to install without verification; skip opts out. A
verification that runs and fails is fatal in every mode.

--end-of-options is deliberately NOT used on ls-tree. Verified against
git 2.39.5:

git ls-tree -r --name-only -z --end-of-options HEAD --   →  (empty)
git ls-tree -r --name-only -z HEAD --                    →  a.txt

It turns the trailing -- into a pathspec, so the tree returns empty and every
scope silently resolves against a repo that appears to have no files. A silent
wrong answer is worse than the problem. The ref guard closes it instead;
--end-of-options is used on cat-file and rev-parse, where the grammar
leaves the separator alone.

Verification

Gate	Result
make vet	clean
go test -race ./...	16/16 packages green
actionlint / shellcheck	clean
make docs	regenerated, idempotent, committed

go.mod is still dependency-free and no go.sum exists. No test was weakened,
skipped, or deleted.

Three of the new tests initially passed vacuously and were tightened rather
than trusted: the homebrew-permissions test (the job held contents: write
precisely because it declared nothing, so the literal was not there to grep
for), the ReadFileAtRef ref-guard test (git errored on the bogus object
anyway), and the credential-URL detector (which failed on its own remediation
comment).

Not fixed — flagged for a decision

1. audit and snapshot read a symlink's target string as CODEOWNERS
   content. They read via git cat-file blob <ref>:<path>, and for a symlink
   tree entry the blob content is the link text. No escape — nothing outside is
   opened — but where plan/sync/apply now refuse, these two silently
   analyze garbage. They arguably deserve the same refusal.
2. A network failure during gh attestation verify aborts the install in
   auto mode, since a verification that runs and fails is fatal. Deliberate and
   consistent with the fail-closed R-12 posture, but it is a behavior change on a
   flaky network.
3. gh auth login --with-token writes the PAT to ~/.config/gh/hosts.yml on
   the runner. Ephemeral, standard, and strictly better than .git/config — but
   still a token at rest.
4. Commits here are unsigned. No signing key is configured on this machine
   and setting one up is your call, not something to do unasked.

Monorepo performance (O(rules × files), 9.3s on 20k files × 500 rules) was left
alone as out of scope — a scalability finding, not a security one.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR addresses the enterprise security audit’s four blockers and related follow-ups by hardening the CLI’s filesystem containment, preventing token leakage via flag defaults, bounding policy JSON parsing to avoid pathological resource usage, and tightening release/provenance integrity (workflow pinning, attestations, and verification).

Changes:

• Add containment/ref-guard rails to prevent repo-controlled inputs (symlinks, dash-leading refs) from causing writes outside --repo or reaching git’s option parser.
• Prevent credential leakage by deferring $GITHUB_TOKEN resolution until after flag parsing; introduce a version command with release-time -X stamping.
• Strengthen supply-chain integrity by SHA-pinning GitHub Actions, producing/using build provenance attestations, and verifying provenance in install.sh (with a defined PROVENANCE= policy).

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/supplychain/supplychain_test.go	Adds workflow-level supply-chain gates (action pinning, attestation markers, OIDC permission, version stamping).
tools/supplychain/permissions_test.go	Adds least-privilege and credential-in-URL workflow gates, plus workflow job parsing.
tools/supplychain/install_verify_test.go	Adds tests ensuring install/docs verify provenance (and handle missing gh).
tools/difftest/main.go	Adds optional seed argument and prints it for reproducible fuzz runs.
SECURITY.md	Adds a repository security policy and provenance verification guidance.
README.md	Documents provenance verification and `PROVENANCE=auto
Makefile	Clarifies difftest reproducibility and how to vary seed.
LICENSE	Updates copyright holder name.
internal/policy/policy.go	Adds size cap for policy loads to prevent large-file OOMs.
internal/policy/jsonsrc.go	Removes quadratic raw-span copying; adds depth cap and located “too deep” error.
internal/policy/bounds_test.go	Adds tests guarding depth/size/linear allocation, and positive controls.
internal/gittree/refguard_test.go	Adds tests for rejecting dash-leading refs and ensuring normal refs still work.
internal/gittree/gittree.go	Adds ValidateRef and applies it to git calls; uses --end-of-options where safe.
internal/ghapi/urlescape_test.go	Adds tests ensuring path/query construction can’t traverse/expand segments or inject query params.
internal/ghapi/ghapi.go	Escapes path segments and query params to prevent normalization-based false positives.
internal/cli/token_redaction_test.go	Adds regression tests ensuring tokens never print but still authenticate.
internal/cli/sync.go	Documents trusted operator paths; validates refs early; adds extra containment pre-check.
internal/cli/containment_test.go	Adds end-to-end tests preventing CODEOWNERS symlink escapes and artifact lies.
internal/cli/cli.go	Adds Version stamping and version/--version command; adds write-path containment helpers.
install.sh	Verifies build provenance via gh attestation verify with PROVENANCE= modes and clear failure semantics.
docs/BEHAVIOR.md	Regenerates behavior docs to reflect new/updated tests.
CONTRIBUTING.md	Adds contribution constraints and workflow/test guidance.
CHANGELOG.md	Adds changelog entries describing the security/supply-chain changes.
.github/workflows/release.yml	SHA-pins actions, adds provenance attestation + OIDC perms, stamps version, reduces homebrew job privileges, removes token-in-URL.
.github/workflows/ci.yml	SHA-pins actions; adds difftest job running full 500k cases.
.github/dependabot.yml	Enables Dependabot for SHA-pinned GitHub Actions updates only.
.github/CODEOWNERS	Adds repo ownership to satisfy the tool’s own audit expectations.

Suppressed comments (2)

tools/supplychain/permissions_test.go:95

• This test reads workflowFiles(t)["release.yml"] inline without checking that the file exists. If release.yml is renamed/missing, splitJobs will parse an empty string and the resulting error will be misleading. Resolve release.yml once with an ok-check, then pass the body to splitJobs.

func TestSupplyChain_HomebrewJobCannotWriteThisRepository(t *testing.T) {
	jobs := splitJobs(t, workflowFiles(t)["release.yml"])
	block, ok := jobs["homebrew"]
	if !ok {
		t.Skipf("no `homebrew` job in release.yml; jobs present: %v", jobNames(jobs))

tools/supplychain/supplychain_test.go:146

• This test indexes workflowFiles(t)["release.yml"] directly, which can lead to misleading results if the workflow file is renamed/missing (the empty string will fail the assertion, but without a clear diagnostic about the missing file). Mirror the explicit presence check used earlier in this file so a missing/renamed workflow is reported clearly.

func TestSupplyChain_ReleaseStampsAVersionIntoTheBinary(t *testing.T) {
	body := workflowFiles(t)["release.yml"]
	if !strings.Contains(body, "-X ") && !strings.Contains(body, "-X\t") {
		t.Errorf("release.yml builds with -ldflags but never stamps a version via -X.\nWithout it `codeowners-tool version` cannot report the build, and an operator holding a binary cannot tell whether it is the one with a given fix.")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.