pi-secrets-guard

Block secrets & PII before they land. pi-secrets-guard scans files, directories, and git diffs for hardcoded credentials (API keys, tokens, private keys) and PII (credit cards, SSNs) using a combination of format rules, Shannon-entropy detection, and Luhn validation — then stops them from being written or committed.

Part of the same family as greenloop: one core engine, four ways to run it.

Surface	How
CLI	npx pi-secrets-guard scan · … scan-diff
git pre-commit hook	… install-hook (aborts commits that add secrets)
MCP server	npx pi-secrets-guard mcp (scan_text / scan_path / scan_diff)
Claude / Cursor skill	skills/pi-secrets-guard
pi extension	import "pi-secrets-guard/pi" — blocks write/edit/bash tool calls that add secrets

Status: M1. Core (rules + entropy + diff), CLI, and MCP built and tested; pi extension typechecks against pi and awaits an in-harness run. See docs/plan.md.

Install into pi

pi install git:github.com/vaibhav-patel/pi-secrets-guard   # write/edit/bash secret-blocking extension + skill
# once published to npm:
pi install npm:pi-secrets-guard

Quick start

npm install
npm run build

node dist/cli/index.js scan .          # scan the working tree
node dist/cli/index.js scan-diff       # scan staged changes (use as a pre-commit gate)
node dist/cli/index.js install-hook    # write a git pre-commit hook

Exit code is non-zero when a finding at/above the block threshold is present (default medium), so it drops straight into CI or a git hook.

What it detects

• Secrets (rules): AWS keys, GitHub tokens & fine-grained PATs, Slack tokens/webhooks, Google API keys, Stripe keys, OpenAI keys, npm tokens, private-key blocks, JWTs, and generic secret = "…" assignments.
• High-entropy strings: base64/hex tokens above an entropy threshold (default 4.3 bits/char, which sits above hex hashes like git SHAs to avoid false positives).
• PII: credit cards (Luhn-validated), US SSNs, email addresses (low severity).

Matches are redacted in output — pi-secrets-guard never echoes the full secret.

Tuning & false positives

A pi-secrets-guard.json in the project root is honored by both the CLI and the pi extension:

{
  "blockSeverity": "medium",          // high | medium | low — what blocks (CLI --severity overrides)
  "allow": ["AKIAIOSFODNN7EXAMPLE"],  // values to never flag
  "disableRules": ["email-address"],  // rule ids to skip
  "entropy": true,                    // toggle high-entropy detection
  "entropyThreshold": 4.3             // bits/char
}

• Severity: high/medium block; low (e.g. emails) warn only. Override per-run with --severity.
• Inline allow: add # pi-secrets-guard: allow (or pragma: allowlist secret) on a line to skip it.
• Disable entropy: --no-entropy, or "entropy": false.

In pi

The extension blocks write / edit / bash tool calls that introduce a secret, with an explicit reason so the agent fixes it instead of retrying. Because a bash command can't carry an inline allow pragma, a false positive there is bypassed with /pi-secrets-guard off (disable blocking for the session; /pi-secrets-guard on re-enables, /pi-secrets-guard status shows state). /pi-secrets-guard with no argument scans the working tree.

Development

npm install
npm run build
npm test           # node --test suite
npm run typecheck

License

MIT — see LICENSE.