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

• Scans and masking run locally.
• Document scanning extracts text from Office documents and text-layer PDFs. Image-only PDFs require OCR outside shk; when no text can be extracted, scan reports an informational skip finding.
• Office document masking writes a new .docx, .xlsx, or .pptx file and requires --output.
• shk scan --git-history scans committed blobs reachable from Git refs. Use --preview to inspect candidate counts before a broad history scan, and --ref, --since, or --max-commits to narrow the scope.
• shk scan --changed-since <rev> scans files changed on the current branch relative to a merge base with <rev>, which is useful for PR CI.
• Built-in detection is pattern-based and includes hand-tuned shk rules plus generated gitleaks-derived secret.gitleaks.* rules; use it as an AI/local workflow guardrail, not as a complete replacement for dedicated secret scanning platforms.
• JSON reports use redacted_value: "[REDACTED]"; value_hash is omitted unless --with-value-hash is passed.
• Value hashes are deterministic fingerprints keyed by public rule IDs. Low-entropy values can be recoverable by dictionary attack, so treat reports containing value hashes as sensitive artifacts.
• Hook audit logs contain metadata such as counts, tool name, hook phase, rule IDs, action categories, and display path; they do not store raw matched values, prompt bodies, or command text.
• Use shk audit to summarize .shk/audit.log; add --no-paths when path labels should not be printed.
• Allowlist value_hash entries are deterministic fingerprints for suppression, not cryptographic secret storage.
• Post-tool hooks are non-blocking.
• doctor ignore --fix appends missing patterns to .gitignore; it does not remove existing entries.
• doctor workflows flags actions/checkout steps missing persist-credentials: false; --fix requires shk.toml and edits flagged workflows in place.
• mask --output requires shk.toml and refuses sensitive env files and protected home configuration files.

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.