secret-scanner

name	secret-scanner
description	Scan a codebase for hardcoded secrets — API keys, tokens, private keys and passwords — using a custom regex + Shannon-entropy engine. Use when the user asks to "find secrets", "check for leaked credentials", "scan for API keys", do a pre-commit secret check, or audit a repo before making it public.
license	MIT

Secret Scanner

A dependency-free engine that finds committed credentials by combining high-signal vendor regex rules (AWS, GitHub, GCP, Stripe, OpenAI, Anthropic, Slack, …) with Shannon-entropy gating to catch generic secrets while keeping false positives low.

When to use this skill

• "Are there any secrets / API keys committed in this repo?"
• "Scan this folder before I open-source it."
• Pre-commit / pre-push credential checks.
• Investigating a suspected leak.

How to run it

The engine has no third-party dependencies — just Python 3.9+.

# Human-readable report (default)
python skills/secret-scanner/engine.py .

# Machine-readable JSON (pipe into other tooling)
python skills/secret-scanner/engine.py . --json

# Tune entropy sensitivity (lower = more findings)
python skills/secret-scanner/engine.py src/ --min-entropy 3.0

# Include test directories (skipped by default)
python skills/secret-scanner/engine.py . --include-tests

Exit codes: 0 clean · 1 findings present · 2 usage error. This makes it drop-in for CI: a non-zero exit fails the build.

How to interpret results

Each finding reports severity, rule_id, path:line:column, a redacted preview of the value (never the full secret), and the measured entropy.

Severity guide:

• critical — live credential material (private keys, cloud secret keys, provider tokens). Rotate immediately.
• high — access key IDs, third-party API keys.
• medium — generic password=/secret= assignments.
• low — JWTs and other context-dependent values; verify before acting.

Recommended workflow for Claude

1. Run the scanner with --json and parse the findings.
2. For each finding, open the file at the reported line to confirm it is a real secret and not a placeholder/test fixture.
3. Report confirmed leaks grouped by severity, and advise the user to rotate the credential (committing a fix does not un-leak git history).
4. If the secret is in git history, recommend git filter-repo / BFG and credential rotation — deleting the line is not enough.

False positives

The engine already filters obvious placeholders (example, <your-key>, xxxx, changeme, ${ENV}, etc.) and gates generic rules behind entropy. If a finding is a known dummy value, treat it as noise. To re-check with stricter entropy, raise --min-entropy.

Notes

• Binary files, node_modules, .git, virtualenvs and oversized files are skipped automatically.
• The scanner never prints full secret values — only redacted previews.