# secret-scanner 🔐

**Catch leaked secrets in a diff/file before you commit, push or open a PR.**

`secret-scanner` scans a blob of code, text or a unified git diff for **leaked secrets** and returns a `CLEAN` / `REVIEW` / `LEAK` verdict. Every finding includes the **secret type, provider, severity and `line:column`**, a **masked** excerpt (the full secret is never echoed), and a remediation note.

Detection is **100% local** — the content you scan is never sent anywhere.

- **MCP server** for Claude / Cursor / any agent: `npx -y secret-scanner-mcp`
- **Pay-per-call x402 API**: `POST /pro/scan` ($0.02 USDC on Base, no sign-up)
- **Free HTTP API**: `POST /scan` (rate-limited)

## What it catches

| Category | Examples |
|---|---|
| 🔑 Provider keys | AWS (`AKIA…`), GitHub (`ghp_…`, fine-grained), OpenAI (`sk-…`), Anthropic (`sk-ant-…`), Stripe (`sk_live_…`), Google (`AIza…`, `GOCSPX-…`), Slack (`xox…`), Twilio, SendGrid, Mailgun, npm (`npm_…`), PyPI, Telegram, Discord, Shopify, Square, DigitalOcean, Cloudflare, Vault, Doppler |
| 📜 Private keys | RSA / EC / DSA / OpenSSH / PGP / encrypted private-key blocks, GCP service-account JSON |
| 🗄️ Connection strings | `postgres://`, `mysql://`, `mongodb+srv://`, `redis://` URIs with embedded passwords; JDBC `password=`; basic-auth URLs |
| 🎫 Tokens | JWTs, generic `api_key = "…"` assignments |
| 🎲 Unknown secrets | high Shannon-entropy base64/hex blobs that look like credentials even without a known prefix |

## MCP server (free)

```json
{
  "mcpServers": {
    "secret-scanner": { "command": "npx", "args": ["-y", "secret-scanner-mcp"] }
  }
}
```

Tool: **`scan_for_secrets`** — params `content` (string, required), `deep` (boolean, optional; adds offline format-validity hints).

Or connect over HTTP at `POST /mcp` (free).

## HTTP API

```bash
# Free (rate-limited 30/h/IP)
curl -X POST https://secret-scanner.vercel.app/scan \
  -H 'content-type: application/json' \
  -d '{"content":"AWS_KEY=AKIAIOSFODNN7EXAMPLE"}'

# Paid, deep, unlimited (x402 — agent pays $0.02 USDC automatically)
curl -X POST https://secret-scanner.vercel.app/pro/scan \
  -H 'content-type: application/json' \
  -d '{"content":"<your diff>"}'
```

Example response:

```json
{
  "verdict": "LEAK",
  "score": 80,
  "summary": "1 potential secret(s) across 1 line(s): AWS×1. Verdict LEAK.",
  "lines": 1,
  "findings": [
    {
      "rule": "aws-access-key-id",
      "title": "AWS Access Key ID",
      "provider": "AWS",
      "severity": "high",
      "line": 1,
      "column": 9,
      "match": "AKIA…MPLE (20 chars)",
      "remediation": "Rotate the IAM key immediately in the AWS console and remove it from history."
    }
  ],
  "meta": { "deep": false, "bytes": 28, "truncated": false, "rulesEvaluated": 35, "entropyFindings": 0 }
}
```

## Why pay-per-call?

The free tier is rate-limited. The `/pro/scan` route is gated by [x402](https://x402.org): your agent pays **$0.02 USDC** per call on Base automatically — no account, no API key. It settles on-chain to the operator's receiving wallet. Deep mode adds offline structural-validity hints for formats whose shape can be verified without any network call.

## Privacy

The scan runs in-process. The content you submit is **not stored and not forwarded** to any third party. Secrets in findings are always masked (`AKIA…MPLE (20 chars)`), never returned in full.

## License

MIT