---
slug: "pi-secrets-guard"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/vaibhav-patel/pi-secrets-guard@main/README.md"
repo: "https://github.com/vaibhav-patel/pi-secrets-guard"
source_file: "README.md"
branch: "main"
---
# 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](https://github.com/vaibhav-patel/pi-green-loop): 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`](https://github.com/vaibhav-patel/pi-secrets-guard/blob/HEAD/skills/pi-secrets-guard/SKILL.md) |
| **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](https://github.com/vaibhav-patel/pi-secrets-guard/blob/HEAD/docs/plan.md).

## Install into pi

```bash
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

```bash
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**:

```jsonc
{
  "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

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

## License

MIT — see [LICENSE](https://github.com/vaibhav-patel/pi-secrets-guard/tree/HEAD/LICENSE).