Exit Codes & Safety Notes

Exit codes

Code	Meaning
0	No findings at or above the active threshold, or command completed successfully.
1	Scan or MCP audit findings met or exceeded the active threshold.
2	Blocking AI pre-hook triggered, or a scan/MCP audit runtime or configuration error occurred.

The --fail-on option and the [thresholds] section of shk.toml control which severity counts against the threshold. See Thresholds.

Safety notes

Area	Behavior	Boundary / check
Local processing	Scanning and masking run locally	Pattern-based detection; not a complete replacement for dedicated secret scanning platforms
Documents	Extract text from Office and text-layer PDFs	Image-only PDFs need external OCR. No extracted text produces an informational skip
Office masking	Write a new .docx / .xlsx / .pptx with --output	Requires shk.toml; output to sensitive env files and protected home configuration is refused
JSON reports	redacted_value is [REDACTED]	value_hash appears only with --with-value-hash. Deterministic fingerprints use public rule IDs; low-entropy values may be guessed by dictionary attack
Audit logs	Counts, tool, phase, rule IDs, action categories, display path	No matched values, prompt bodies, or command text. Use shk audit --no-paths to omit path labels
Allowlist hashes	Suppress findings for a particular value	Not cryptographic secret storage
Post-tool hooks	Inspect after the action	Non-blocking

Scan scope and changes to files

Operation	Scope / changes
scan --git-history	Committed blobs reachable from Git refs. Start with --preview; narrow with --ref, --since, or --max-commits
scan --changed-since <rev>	Current-branch files changed since the merge base with <rev>, useful for PR CI
doctor ignore --fix	Append missing .gitignore patterns; never remove existing entries
doctor workflows --fix	Fix actions/checkout steps missing persist-credentials: false. Requires shk.toml and edits flagged workflows in place

Detection combines hand-tuned shk rules and gitleaks-derived secret.gitleaks.* rules. Treat reports containing value hashes as sensitive artifacts.

Env secret store threat model

By default, shk env stores dotenv private keys in the OS keyring. Teams can opt in to 1Password for shared vault distribution, centralized revocation, and Business audit logs.

1Password is primarily a team operations upgrade (distribution, offboarding, audit). It also avoids persisting keys in the local keyring. Desktop app authorization can persist for a CLI session, so it is not a guarantee of biometric approval on every shk env run. Prefer short vault auto-lock and 1Password Business access logs for visibility.

See Env Secret Store and shk env key migrate.

Reporting a vulnerability

Please report security issues privately through the process described in the repository's SECURITY.md rather than in public issues.