Secret Scanner

Secret Scanner — leaked credential detection

Load this skill when you need to scan a codebase, directory, or git repo for leaked secrets/tokens/keys (before publishing a repo, before a release, or during security review).

The scanner is static and offline by design: patterns come from the gitleaks v8.30.3 default config, the canonical open-source secret-detection rule set, and detection uses the same Shannon-entropy gating semantics as gitleaks. No network calls are made — a format match is reported as potential, not verified.

The scanner script

scripts/secret_scanner.py — pure Python 3 stdlib (no dependencies).

Detected pattern families (19 rules)

Critical: AWS Access Key ID (AKIA/ASIA/ABIA/A3T…) & secret key, GitHub PAT classic/fine-grained/refresh tokens, OpenAI (sk-*T3BlbkFJ*), Anthropic (sk-ant-api03-…AA), Stripe (sk_live_/rk_live_), Google API key (AIza…), private keys (PEM/OpenSSH/PGP blocks). High: Slack app/bot/user tokens and webhooks, Perplexity (pplx-…). Medium: JWT, generic keyword-anchored API keys.

False-positive suppression (allowlists)

• Placeholders: $VAR, ${VAR}, {{ }}, %VAR%, true/false/null, ****, EXAMPLE, xxxx, your-, placeholder, TODO — never reported
• Noise paths: node_modules/, vendor/, .git/, lockfiles (package-lock.json, go.sum, poetry.lock, …), minified JS, binaries, images, fonts
• Entropy gate: every entropy-sensitive rule skips values whose Shannon entropy ≤ rule minimum (gitleaks semantics)

Capabilities

• --json / --markdown / text (default) report formats
• --redact N — mask secrets in output (keeps first N chars; CI-safe)
• --max-mb N — skip huge files (default 10 MB)
• --exit-code — exit 1 when findings present (CI gate), else 0

Usage example (typical)

# Full directory scan, JSON report for CI
python3 secret_scanner.py --path ./my-repo --json --redact 8 --exit-code

# Scann only tracked files of a repo
python3 secret_scanner.py --git /Users/me/projects/lovii_demo

# Markdown human-readable report
python3 secret_scanner.py --path ./app --markdown > scan-report.md

Interpretation guidance

• Critical + live risk (AWS/GitHub/OpenAI/Anthropic/etc.) → rotate the credential first, then scrub history. Assume a committed secret is compromised (forks, cache, CI logs, bots).
• Medium (generic/JWT) → verify context before alarming; check whether the value appears in tests/fixtures/docs.
• Allowlisted but suspicious → check if .env.example contains a real key instead of a YOUR_KEY placeholder.
• Only the operator can confirm whether a secret is still live — offline heuristic check (token length/grammar, EXAMPLE suffix) is automatic.

Canonical patterns

Full deep dive with upstream sources in references/canonical-patterns.md. Key canons:

• gitleaks rule table (v8.30.3 config/gitleaks.toml) — the canonical regex set; entropy per-rule minimums
• Shannon entropy gating — detect/utils.go#L117-L134; skip when entropy <= rule.Entropy (strictly greater)
• Global & path allowlists — placeholders + lockfiles + binaries
• SkillSpector two-stage model — static → heuristic/human triage, baseline suppression for re-scans
• Remediation order — rotate first, scrub second (gitleaks/TruffleHog guidance; git filter-repo/BFG for history)

Files

• SKILL.md — this file
• skill.json — manifest
• scripts/secret_scanner.py — the stdlib scanner (pattern table + entropy + allowlists)
• references/canonical-patterns.md — gitleaks/Detect-secrets/TruffleHog/ SkillSpector deep dive with per-rule regexes and sources

Canonical analogues

Full source depth — in references/canonical-patterns.md. Backbone:

Installation

# For opencode
cp -r skills/secret-scanner ~/.config/opencode/skills/

# For other agents
# Copy the skill folder to your skills directory; requires Python 3.

Security note: this tool finds potential secrets. It never comments them out, does not attempt to "verify" them online, and never rewrites source files. Operators must rotate real secrets and scrub history manually — see references/canonical-patterns.md → Remediation workflow.