spillscan — Configuration

Configuration

False-positive allowlist

Some secret-shaped strings are fine to keep: a docs example key, a fixture token, a JWT from a public tutorial. List them once and spillscan stops reporting them. Allowlisted findings are left out of scan, left untouched by redact, and left out of the MCP scan_report (which only reports how many it hid). On main; ships in the next release.

Where the list comes from:

~/.config/spillscan/allow.txt (or $XDG_CONFIG_HOME/spillscan/allow.txt), read automatically when it exists.
--allow FILE on scan, redact and undo, repeatable, added on top. A missing file is an error, not a silent no-op.
--no-allow ignores every list, for when you want the raw reading.

One entry per line; # starts a comment. Keys on one line must all match; separate lines are alternatives.

# ~/.config/spillscan/allow.txt
fp:3f9a1c0b7e21                             # by fingerprint
rule:jwt path:~/.claude/projects/*docs*/**  # rule + place
path:~/.codex/sessions/2026/01/**           # a whole place
rule:generic-assign                         # a whole rule
value:AKIAIOSFODNN7EXAMPLE                  # fake literal

Key	Matches
`fp:`	The value whose fingerprint starts with these hex chars (8 to 64; scan prints 12). The fingerprint is a domain-separated SHA-256 of the value, so you can allowlist a finding without the value ever being printed or stored.
`rule:`	A detector id (see Reference). A typo is an error with a suggestion.
`path:`	A glob over the transcript's absolute path. `` stays inside one segment, `*` crosses segments, `?` is one character, `~/` is your home. Without `/` it matches the file name; a relative glob matches the trailing segments, like `.gitignore`.
`value:`	The exact literal. Only for values that are fake by construction: unlike `fp:`, it stores the value in the file.

A bad line stops the run with file:line and what to write instead (a bare 3f9a1c0b7e21 gets "write it as fp:3f9a1c0b7e21"). When scan hid something, it says so: allowlisted=2 in the header and a line naming the list. The follow-up redact commands it prints repeat any --allow file, so the scrub skips exactly what the survey hid.

Why no per-project file: transcripts live under your home, not in a repo, and spillscan runs from any directory. A list that changed with the current directory would make the same scan give different readings.

undo re-runs the scrub on each .bak to check the file is unchanged; pass it the same --allow files you scrubbed with. It also accepts a scrub that ran before the allowlist existed.

Claude Code PreToolUse

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "spillscan guard" }]
    }]
  }
}

Put this in .claude/settings.json (project) or user settings. The guard splits on && || ; | and re-scans bash -c / sh -c bodies for env, printenv, cat .env*, /proc/*/environ, kubectl get secret.