repo-manager/docs/secret-detection.md

Repository secret detection

Repo Manager provides a control adapter to an external scanner. Credential custody, incident response and authorization remain with their existing owners. The adapter is initially source tooling; it does not install or activate hooks. Work: RMGR-WP-0021, coordinated by Custodian CUST-WP-0080 G07.

Scan the proposed index

rmgr secret-scan --path /path/to/repo --binary /reviewed/path/to/gitleaks

The supported executable is Gitleaks 8.30.1 Linux x64, SHA256 88f91962aa2f93ac6ab281d553b9e125f5197bbbce38f9f2437f7299c32e5509. Install/admit it separately; this command never downloads or executes an unverified replacement. The reviewed test archive and checksum came from the official release. Checksum comparison alone is not a detached signature verification or fleet installation receipt. Other platforms/versions need an explicitly reviewed pin.

The JSON result contains a fixed status, counts and affected Git blob IDs. It contains no findings, paths, matched lines or credential values. Raw scanner stdout/stderr are discarded even on errors; no findings report is written. Inspect blocked content only in an approved private review environment. Never paste it into chat, State Hub, issue bodies or CI logs.

Exit	Result	Required caller behavior
0	clean	No detection in the declared changed staged blobs
1	blocked	Reject the proposed commit and privately review the indicated objects
2	unverified	Reject; fix missing tool, unreadable index, limits or other verification failure

clean is not a statement about working-tree files, existing HEAD/history, other branches, remote refs, logs, artifacts, production credentials or complete absence of secrets. An empty staged change scans zero objects and says nothing about history. The scanner uses the upstream default detection rules; heuristic false negatives and false positives remain possible.

Input and configuration boundaries

The adapter scans complete changed staged blobs, including an initial commit, renames and partial staging. It honors Git's explicit alternate index (including git commit --only behavior), ignores Git replacement objects and refuses index changes observed during scanning. Symlink text is scanned without reading the external target. Changed gitlinks, conflicts and unreadable entries are refused.

A reviewed configuration extending the scanner's built-in defaults is supplied from an isolated temporary directory. Repository .gitleaks.toml, ignore files, inline gitleaks:allow comments and ambient scanner environment do not suppress this check. There is no implicit baseline or exception switch. False positives need a reviewed follow-up mechanism with exact scope and real approval; do not silently add broad path exclusions.

The current resource bounds are 500 distinct blobs, 8 MiB per blob and 64 MiB in total; exceeding a bound refuses instead of skipping. Individual Git and scanner calls have timeouts. The executable is hash-checked and invoked through its open file descriptor. These measures are not isolation from a hostile same-UID writer, a malicious Git installation, hook bypass or a process with repository authority.

Enforcement and response acceptance

Before activating a hook, preserve the existing generated-commit and assistant provenance checks; validate exact repository coverage, executable availability, clean commits, synthetic detections and scanner failures. Do not replace the shared hook or change global core.hooksPath merely to run this command.

Local pre-commit can be bypassed. Forge/CI enforcement must independently check all introduced objects/commits, including merge/base-history cases and unavailable scanner failures. Required checks and writers able to alter enforcement need separate admission. An actual finding needs owner classification and a governed revocation/rotation path; source removal or rejection of one commit does not revoke credentials that were already exposed. CUST-WP-0073-T05's existing founder deferral is not overridden by this adapter.

Tests

Set RMGR_TEST_GITLEAKS to the exact reviewed test executable when running pytest tests/test_secret_scan.py. Tests use disposable repositories and keys, verify commit refusal and preserved index semantics, and never contact a forge or issuer. Without the test executable, scanner-dependent tests explicitly skip; those skips are not acceptance evidence.