diff --git a/bin/gstack-redact-prepush b/bin/gstack-redact-prepush index 98e9b931c..31a87c97e 100755 --- a/bin/gstack-redact-prepush +++ b/bin/gstack-redact-prepush @@ -24,6 +24,10 @@ * - `pii.email` skips the pusher's own address, `gstack.redact.allowEmail` * entries, and addresses already in the destination's commit metadata * (see emailScanOptions). + * - `.gstack-redact-allowlist`, read from each pushed commit (never the + * working tree), lists exact matched spans reviewed as benign, one per + * line, `#` comments. Only a finding whose matched text equals an entry is + * suppressed; every push that carries entries lists what they suppressed. * - GSTACK_REDACT_PREPUSH=skip → log + exit 0 (escape valve). * * Installed/uninstalled via `gstack-redact install-prepush-hook` (see the @@ -549,11 +553,40 @@ function emailScanOptions(historyRevs: string[], trackingRemote: string | null): }; } +const ALLOWLIST_PATH = ".gstack-redact-allowlist"; +const ALLOWLIST_MAX_BYTES = 64 * 1024; + +/** + * Entries of the allowlist committed in `sha`. Read from the pushed commit so + * a suppression exists only as a reviewable commit. Absent, unreadable or + * oversized means no entries: the file can record a reviewed exception, never + * loosen the scan by accident. + */ +function committedAllowlist(sha: string): string[] { + const spec = `${sha}:${ALLOWLIST_PATH}`; + const size = Number(git(["cat-file", "-s", spec]).trim()); + if (!size) return []; + if (size > ALLOWLIST_MAX_BYTES) { + process.stderr.write( + `gstack-redact-prepush: ${ALLOWLIST_PATH} in ${sha.slice(0, 12)} is over ${ALLOWLIST_MAX_BYTES} bytes; ignoring it.\n`, + ); + return []; + } + return git(["cat-file", "blob", spec]).split("\n") + .map((l) => l.trim()) + .filter((l) => l && !l.startsWith("#")); +} + +/** File line (and commit) of a finding. Never the matched value. */ +function findingWhere(f: Finding, part: AddedFile): string { + const line = part.lines[f.line - 1]; + return `${part.file || "(unknown file)"}${line ? `:${line}` : ""}` + + (part.commit ? ` in commit ${part.commit.slice(0, 12)}` : ""); +} + /** One MEDIUM report line: rule id, file line (and commit), and the fix. Never the matched value. */ function mediumLine(f: Finding, part: AddedFile): string { - const line = part.lines[f.line - 1]; - const where = `${part.file || "(unknown file)"}${line ? `:${line}` : ""}` + - (part.commit ? ` in commit ${part.commit.slice(0, 12)}` : ""); + const where = findingWhere(f, part); const fix = f.id === "pii.email" ? "remove the address, or allow it: git config --add gstack.redact.allowEmail
" : "remove the value before it becomes public"; @@ -574,7 +607,8 @@ function main() { .filter(Boolean) .map((l) => l.split(/\s+/)); - const parts: AddedFile[] = []; + const parts: Array<{ part: AddedFile; allowlist: string[] }> = []; + const allowEntries = new Set(); const historyRevs = new Set(); let trackingRemote: string | null = null; @@ -610,7 +644,9 @@ function main() { ); process.exit(1); } - parts.push(...added.filter((part) => part.text.trim())); + const allowlist = committedAllowlist(localSha); + for (const entry of allowlist) allowEntries.add(entry); + for (const part of added) if (part.text.trim()) parts.push({ part, allowlist }); historyRevs.add(localSha); if (!ZERO.test(remoteSha) && objectExists(remoteSha)) historyRevs.add(remoteSha); else { @@ -628,9 +664,21 @@ function main() { // Sliced (see scanAddedLines) so a large-but-legitimate diff is actually // scanned rather than blocked unscanned on the engine's size cap. // Scanned per file so a pattern can use the file's type (#3048). - for (const part of parts) { + // An allowlisted span is found by scanning with and without the entries, + // so the report names exactly what they suppressed. + const allowed: string[] = []; + const findingKey = (f: Finding) => `${f.id}:${f.line}:${f.col}`; + for (const { part, allowlist } of parts) { const opts = { repoVisibility: "private" as const, ...emails.options, ...(part.file ? { sourcePath: part.file } : {}) }; - for (const f of scanAddedLines(part.text, opts)) { + const findings = scanAddedLines(part.text, opts); + const kept = allowlist.length + ? new Set(scanAddedLines(part.text, { ...opts, allowlist }).map(findingKey)) + : null; + for (const f of findings) { + if (kept && !kept.has(findingKey(f))) { + if (f.severity === "HIGH" || f.severity === "MEDIUM") allowed.push(` ${f.severity} ${f.id} ${findingWhere(f, part)}\n`); + continue; + } if (f.severity === "HIGH") allHigh.push(f); else if (f.severity === "MEDIUM") { mediums.push(mediumLine(f, part)); @@ -639,6 +687,14 @@ function main() { } } + if (allowEntries.size > 0) { + process.stderr.write( + `gstack-redact-prepush: ${ALLOWLIST_PATH} (${allowEntries.size} entr${allowEntries.size === 1 ? "y" : "ies"}) ` + + `suppressed ${allowed.length} finding(s) in this push${allowed.length ? ":" : "."}\n`, + ); + for (const line of allowed) process.stderr.write(line); + } + if (mediums.length > 0) { process.stderr.write( `gstack-redact-prepush: ${mediums.length} MEDIUM finding(s) in pushed diff (PII/internal). ` + @@ -673,7 +729,9 @@ function main() { process.stderr.write(` HIGH ${f.id} ${f.preview}\n`); } process.stderr.write( - "\nRotate the credential (a pushed secret is compromised) and remove it from the diff.\n", + "\nRotate the credential (a pushed secret is compromised) and remove it from the diff.\n" + + `If the value is a known-benign sample, commit its exact matched text as a line of ${ALLOWLIST_PATH}\n` + + "at the repo root instead of reshaping code to dodge the pattern; every push lists what that file suppresses.\n", ); } diff --git a/docs/CONTRIBUTOR_REFERENCE.md b/docs/CONTRIBUTOR_REFERENCE.md index 45a05a3f8..b6b89d996 100644 --- a/docs/CONTRIBUTOR_REFERENCE.md +++ b/docs/CONTRIBUTOR_REFERENCE.md @@ -134,6 +134,9 @@ determined leaker (a CHANGELOG line that does would fail a hostile screenshotter - **Config keys:** `redact_repo_visibility` (public|private|unknown, local-only override for repos gh/glab can't read), `redact_prepush_hook` (true|false). There is intentionally NO key to disable HIGH blocking. +- **Committed allowlist:** `.gstack-redact-allowlist` at the root of the pushed commit lists + exact matched spans reviewed as benign; the pre-push hook suppresses only a + finding whose span equals an entry and lists every suppression on each push. - **Audit:** the /spec semantic pass appends a content-free record (categories + body sha256, no spec text) to `~/.gstack/security/semantic-reviews.jsonl` (0600). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f71008f53..64c78c1bf 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1120,6 +1120,24 @@ up deployed, so it still blocks. **Fix.** Use `postgres://postgres:postgres@localhost:5432/...` in local and CI config, or read the URL from an env var. If the credential is real, rotate it. Bypass once: `GSTACK_REDACT_PREPUSH=skip git push`. +If the URL is a reviewed, public dev-only value, list it in +[`.gstack-redact-allowlist`](#redact-allowlist). + + +### `.gstack-redact-allowlist ( entries) suppressed finding(s) in this push` + +**Meaning.** The pushed commit carries `.gstack-redact-allowlist` at the repo +root. Each line (after trimming; `#` starts a comment) is one exact matched +span: the whole `postgres://USER:PASSWORD@host:port` URL for +`db.url_with_password`, the key for a key pattern, the address for `pii.email`. A finding is suppressed only when its +matched text equals an entry, so a password alone, a substring, or a different +key still reports and still blocks. The hook reads the file from each pushed +commit, never the working tree, and ignores a file over 64 KiB. Every push that +carries entries prints this line and each suppressed finding's file and line. +It works alongside `gstack.redact.allowEmail`, which stays a local setting. + +**Fix.** Nothing, if every listed suppression is the reviewed value. Remove an +entry that no longer applies; rotate a credential that is real. ### `pii.ip_public` MEDIUM on a four-part version number diff --git a/test/redact-prepush-hook.test.ts b/test/redact-prepush-hook.test.ts index 36ced9365..66727b828 100644 --- a/test/redact-prepush-hook.test.ts +++ b/test/redact-prepush-hook.test.ts @@ -191,6 +191,100 @@ describe("release version exemption (#2856)", () => { }); }); +describe("committed allowlist (.gstack-redact-allowlist)", () => { + const HOOK_ALLOWLIST = ".gstack-redact-allowlist"; + const pushOf = (base: string, head: string) => `refs/heads/main ${head} refs/heads/main ${base}\n`; + const commitAllowlist = (content: string): string => { + return commit(HOOK_ALLOWLIST, content, "allowlist"); + }; + const DEV_URL = ["postgres://", "app:devpass", "@db:5432"].join(""); + + test("an exact committed span passes and the suppression is listed", () => { + const base = git(["rev-parse", "HEAD"]); + commit("config.txt", "key " + FAKE_AWS_KEY + "\n", "add key"); + const head = commitAllowlist("# docs sample key\n" + FAKE_AWS_KEY + "\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(0); + expect(stderr).not.toContain("BLOCKED"); + expect(stderr).toContain(".gstack-redact-allowlist (1 entry) suppressed 2 finding(s) in this push:"); + expect(stderr).toContain("HIGH aws.access_key config.txt:1"); + expect(stderr).toContain("HIGH aws.access_key .gstack-redact-allowlist:2"); + }); + + test("a different credential still blocks next to an allowlisted one", () => { + const base = git(["rev-parse", "HEAD"]); + const otherKey = ["AKIA", "FEDCBA0987654321"].join(""); + commit("config.txt", "ok " + FAKE_AWS_KEY + "\nleak " + otherKey + "\n", "one benign one real"); + const head = commitAllowlist(FAKE_AWS_KEY + "\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).toContain("BLOCKED"); + expect(stderr).toContain("suppressed 2 finding(s)"); + const blocked = stderr.slice(stderr.indexOf("BLOCKED")); + expect(blocked.match(/HIGH {2}aws\.access_key/g)).toHaveLength(1); + }); + + test("a substring of the matched span does not suppress it", () => { + const base = git(["rev-parse", "HEAD"]); + commit("compose.txt", "DATABASE_URL=" + DEV_URL + "\n", "dev url"); + const head = commitAllowlist("app:devpass\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).toContain("db.url_with_password"); + expect(stderr).toContain("suppressed 0 finding(s) in this push."); + }); + + test("the whole matched URL suppresses that URL only", () => { + const base = git(["rev-parse", "HEAD"]); + const prodUrl = ["postgres://", "app:devpass", "@prod.internal:5432"].join(""); + commit("compose.txt", "DATABASE_URL=" + DEV_URL + "\nPROD_URL=" + prodUrl + "\n", "two urls"); + const head = commitAllowlist(DEV_URL + "\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).toContain("HIGH db.url_with_password compose.txt:1"); + expect(stderr).toMatch(/BLOCKED[\s\S]*HIGH {2}db\.url_with_password/); + }); + + test("an uncommitted allowlist in the working tree suppresses nothing", () => { + const base = git(["rev-parse", "HEAD"]); + const head = commit("config.txt", "key " + FAKE_AWS_KEY + "\n", "add key"); + fs.writeFileSync(path.join(repo, HOOK_ALLOWLIST), FAKE_AWS_KEY + "\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).not.toContain("suppressed"); + }); + + test("an oversized allowlist is ignored and the scan stays strict", () => { + const base = git(["rev-parse", "HEAD"]); + commit("config.txt", "key " + FAKE_AWS_KEY + "\n", "add key"); + const head = commitAllowlist(FAKE_AWS_KEY + "\n" + "#".repeat(65 * 1024) + "\n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).toContain("is over 65536 bytes; ignoring it"); + }); + + test("entries cover MEDIUM emails alongside gstack.redact.allowEmail", () => { + const base = git(["rev-parse", "HEAD"]); + git(["config", "--add", "gstack.redact.allowEmail", "carol@corp.io"]); + commit("notes.md", "contact bob@corp.io or carol@corp.io or dave@corp.io\n", "contacts"); + const head = commitAllowlist(" bob@corp.io \n"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(0); + expect(stderr).toContain("MEDIUM pii.email notes.md:1"); + expect(stderr).toContain("suppressed 2 finding(s)"); + expect(stderr).toContain("1 MEDIUM finding(s) in pushed diff"); + }); + + test("the block message names the allowlist without one present", () => { + const base = git(["rev-parse", "HEAD"]); + const head = commit("config.txt", "key " + FAKE_AWS_KEY + "\n", "add key"); + const { code, stderr } = runHook(pushOf(base, head)); + expect(code).toBe(1); + expect(stderr).toContain("commit its exact matched text as a line of .gstack-redact-allowlist"); + expect(stderr).not.toContain("suppressed"); + }); +}); + describe("diff direction + special refs", () => { test("only NEW content is scanned (remote..local), not pre-existing", () => { // Put a secret in the FIRST commit (already on remote), then push a clean commit.