tegwick
77fc4c9b97
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a12d13-27f2-7163-b8c0-f682af02772c
82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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](https://github.com/gitleaks/gitleaks/releases/tag/v8.30.1).
|
|
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.
|