Secrets Scan

Secrets Scan

Scan a git repository for leaked credentials using two complementary tools:

• detect-secrets (Yelp, PyPI) – entropy-based detection of 26+ secret types including AWS keys, GitHub tokens, private keys, and high-entropy strings
• secretlint (npm) – pattern-based detection tuned to known token formats (Slack xoxb-*, npm tokens, GCP service account keys, etc.)

Running both catches what each misses individually. The automation script (scripts/scan.py) handles setup, runs both tools, reads the flagged lines, auto-classifies findings, and emits a combined Markdown report.

Quick Start (automation script)

# Scan the current directory (git-tracked files, both tools)
uv run /path/to/skills-akaihola/secrets-scan/scripts/scan.py

# Scan a specific repo
uv run /path/to/skills-akaihola/secrets-scan/scripts/scan.py /path/to/repo

# JSON output (for programmatic use or piping)
uv run /path/to/skills-akaihola/secrets-scan/scripts/scan.py --json

# detect-secrets only (faster; skip secretlint setup)
uv run /path/to/skills-akaihola/secrets-scan/scripts/scan.py --no-secretlint

# Include non-git-tracked files
uv run /path/to/skills-akaihola/secrets-scan/scripts/scan.py --all-files

The script exits with code 0 when all findings are classified as likely false positives, or code 1 when any finding needs human review.

Running the Tools Manually

detect-secrets

# Scan current directory (git-tracked files only)
uvx detect-secrets scan

# Scan all files, excluding .venv/ and node_modules/
uvx detect-secrets scan --all-files \
  --exclude-files '\.venv/' \
  --exclude-files '\.git/' \
  --exclude-files 'node_modules/'

# Scan a single string
uvx detect-secrets scan --string 'AKIAIOSFODNN7EXAMPLE'

# Suppress noisy HexHighEntropyString detector
uvx detect-secrets scan --disable-plugin HexHighEntropyString

# Generate a baseline for pre-commit use
uvx detect-secrets scan > .secrets.baseline
uvx detect-secrets audit .secrets.baseline

secretlint

secretlint requires a config file and its rule package to be co-installed. Set up once in a temp directory, then run on git-tracked files:

# One-time setup
mkdir -p /tmp/sl-check
echo '{"name":"sl-check","version":"1.0.0","private":true}' \
  > /tmp/sl-check/package.json
echo '{"rules":[{"id":"@secretlint/secretlint-rule-preset-recommend"}]}' \
  > /tmp/sl-check/.secretlintrc.json
cd /tmp/sl-check
bun add --silent secretlint @secretlint/secretlint-rule-preset-recommend

# Run against repo (from repo root)
git ls-files | grep -v '\.venv' | grep -v node_modules \
  | xargs /tmp/sl-check/node_modules/.bin/secretlint \
      --secretlintrc /tmp/sl-check/.secretlintrc.json

# JSON output
git ls-files | xargs /tmp/sl-check/node_modules/.bin/secretlint \
  --format json --secretlintrc /tmp/sl-check/.secretlintrc.json

Interpreting Results

detect-secrets output

{
  "results": {
    "path/to/file.py": [
      {
        "type": "AWS Access Key",
        "filename": "path/to/file.py",
        "hashed_secret": "abc123...",
        "is_verified": false,
        "line_number": 42
      }
    ]
  }
}

"results": {} means no secrets found. The secret value is hashed; use the line number to read the actual content.

secretlint output (JSON)

[
  {
    "filePath": "/abs/path/to/file",
    "messages": [
      {
        "ruleId": "@secretlint/secretlint-rule-slack",
        "messageId": "SLACK_TOKEN",
        "message": "found slack token: ****",
        "loc": { "start": { "line": 7, "column": 24 } },
        "severity": "error",
        "docsUrl": "https://github.com/secretlint/secretlint/..."
      }
    ]
  }
]

Classifying Findings

For every finding, read the flagged line. Then apply this decision tree:

Does the line contain a placeholder?
  → "your_key_here", "changeme", "example.com", "INSERT_", etc.
  → AWS doc example key: AKIAIOSFODNN7EXAMPLE
  → Generic connection string: "username:password@localhost"
  YES → Likely false positive. Add # pragma: allowlist secret comment.

Is it in a test fixture or documentation file?
  YES → Likely false positive. Review context.

Is it a high-entropy string in a third-party library (e.g. yt_dlp, node_modules)?
  YES → False positive. Exclude the path from future scans.

Otherwise → Real finding. Rotate the credential immediately.

See references/classifying-findings.md for a full table of common false positive patterns and remediation steps.

Handling Real Secrets

1. Rotate immediately – treat the credential as compromised. Revoke and re-issue even if the commit is old; assume it was scraped.

2. Remove from source – use an environment variable or a secrets manager:

   # Before
   API_KEY = "klevu-15488592134928913"
   
   # After
   import os
   API_KEY = os.environ["KLEVU_API_KEY"]
   

3. Rewrite history (optional) – git filter-repo or BFG Repo Cleaner can strip the secret from all commits, but only matters if the repo is private and you have not pushed to a public remote.

4. Add to baseline to silence future scans for confirmed false positives:

   uvx detect-secrets scan > .secrets.baseline
   # commit .secrets.baseline
   

Suppressing False Positives

detect-secrets – inline allowlist

API_KEY = "klevu-example-key"  # pragma: allowlist secret

detect-secrets – exclude a file pattern

uvx detect-secrets scan --exclude-files '\.venv/' --exclude-files 'tests/fixtures/'

secretlint – ignore file

Create .secretlintignore in the repo root (gitignore syntax):

.venv/
node_modules/
tests/fixtures/

detect-secrets Plugin Reference

detect-secrets CLI Reference

scan options

audit options

uvx detect-secrets audit .secrets.baseline

Interactive workflow: generates .secrets.baseline, then audit lets you mark each finding as true/false positive.