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).

| Source | Command | |---|---| | File | python3 secret_scanner.py --path path/to/file | | Directory (recursive) | python3 secret_scanner.py --path path/to/dir | | Git repo (tracked files) | secret_scanner.py --git /path/to/repo | | stdin (blob) | cat file | secret_scanner.py |

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 AnalogWhat we borrow gitleaks (GitHub, MIT)Pattern table, entropy thresholds, global/path allowlists, redaction, exit-code CI model TruffleHog v3Typed-detector philosophy; verified vs unverified` framing (we stay offline) Yelp detect-secretsQuoted-string scanning to cut noise; keyword-anchored entropy NVIDIA SkillSpectorTwo-stage analysis; severity scoring; false-positive baseline/suppression

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bestdeejay-design
• Source: bestdeejay-design/agent-skills
• License: MIT
• Homepage: https://bestdeejay-design.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.