# Secret Scanner

> Static secret/token scanning for codebases and git repos: detects leaked credentials (AWS, GitHub, OpenAI, Anthropic, Stripe, Google, Slack, private keys, JWTs) using gitleaks v8.30.1 pattern table + Shannon entropy gating + allowlist noise filters. Stdlib-only Python script with JSON/Markdown/text reports, redaction, CI exit-code gate.

- **Type:** Skill
- **Install:** `agentstack add skill-bestdeejay-design-agent-skills-secret-scanner`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bestdeejay-design](https://agentstack.voostack.com/s/bestdeejay-design)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bestdeejay-design](https://github.com/bestdeejay-design)
- **Source:** https://github.com/bestdeejay-design/agent-skills/tree/main/skills/secret-scanner
- **Website:** https://bestdeejay-design.github.io/agent-skills/

## Install

```sh
agentstack add skill-bestdeejay-design-agent-skills-secret-scanner
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/gitleaks/gitleaks), 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)

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

```bash
# 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](https://github.com/bestdeejay-design)
- **Source:** [bestdeejay-design/agent-skills](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bestdeejay-design-agent-skills-secret-scanner
- Seller: https://agentstack.voostack.com/s/bestdeejay-design
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.