Agent skill

secrets-scan

Scan a git repository for leaked credentials, API keys, tokens, and other secrets using detect-secrets (uvx) and secretlint (bun). Runs both tools, reads each flagged line, and classifies findings as needing review vs. likely false positives. Use when the user asks to "scan for secrets", "check for credentials", "find leaked keys", "detect secrets", "check for API keys", "check for leaked tokens", or wants to verify no credentials are committed. Supersedes the credentials-check skill.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/akaihola/skills-akaihola/tree/main/secrets-scan

SKILL.md

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)

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

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

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

json
{
  "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)

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:

    python
    # 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:

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

Suppressing False Positives

detect-secrets – inline allowlist

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

detect-secrets – exclude a file pattern

bash
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

Plugin Detects
AWSKeyDetector AWS access keys and secret keys
AzureStorageKeyDetector Azure storage account keys
BasicAuthDetector Basic auth strings in URLs
GitHubTokenDetector GitHub personal access tokens
GitLabTokenDetector GitLab personal/project tokens
JwtTokenDetector JSON Web Tokens
PrivateKeyDetector PEM-encoded private keys
Base64HighEntropyString High-entropy base64 strings
HexHighEntropyString High-entropy hex strings
KeywordDetector passwords, secrets, tokens in code
OpenAIDetector OpenAI API keys
StripeDetector Stripe API keys
SlackDetector Slack tokens and webhooks
TwilioKeyDetector Twilio API keys
SendGridDetector SendGrid API keys
TelegramBotTokenDetector Telegram bot tokens
DiscordBotTokenDetector Discord bot tokens
MailchimpDetector Mailchimp API keys
NpmDetector npm tokens
PypiTokenDetector PyPI API tokens
ArtifactoryDetector JFrog Artifactory tokens
CloudantDetector IBM Cloudant credentials
IbmCloudIamDetector IBM Cloud IAM keys
IbmCosHmacDetector IBM COS HMAC credentials
SoftlayerDetector SoftLayer API keys
SquareOAuthDetector Square OAuth tokens

detect-secrets CLI Reference

scan options

Flag Description
--all-files Scan all files recursively, not just git-tracked
--baseline FILENAME Update an existing baseline file
--force-use-all-plugins Use latest plugins even if baseline specifies a subset
--slim Minimal baseline (not compatible with audit)
--list-all-plugins List all plugins that will be used
-p, --plugin PATH Path to a custom detector plugin
--base64-limit N Entropy limit for base64 strings (0–8, default 4.5)
--hex-limit N Entropy limit for hex strings (0–8, default 3.0)
--disable-plugin NAME Disable a plugin by class name
--exclude-lines REGEX Skip lines matching regex
--exclude-files REGEX Skip files matching regex
--exclude-secrets REGEX Skip secrets matching regex
--string [STRING] Scan a single string instead of files
-n, --no-verify Skip online verification of secrets
--only-verified Only report verified secrets
-v, --verbose Verbose output
-C PATH Run as if started in PATH
-c, --cores N Number of parallel cores (default: all)

audit options

bash
uvx detect-secrets audit .secrets.baseline

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

akaihola/skills-akaihola

youtube-to-markdown

Convert a YouTube video into clean, readable Markdown using its free auto-generated captions (no paid API needed). Use when the user asks to "convert YouTube video to markdown", "get transcript from YouTube URL", "summarise this video", or wants to turn YouTube subtitles/captions into readable text. Prefer this over youtube-transcription when the video already has auto-generated subtitles — it's free and faster. Accepts YouTube URLs.

1 0
Explore
akaihola/skills-akaihola

brave-search

Search the web using Brave Search API. Use when the user asks to "search the web", "look up current information", "find news about", "research a topic online", "check prices online", or needs up-to-date facts that may not be in the model's training data. Requires BRAVE_SEARCH_API_KEY. Supports structured web results (pages, FAQs, news, videos) and an optional AI summarizer.

1 0
Explore
akaihola/skills-akaihola

verkkokauppa

Search products on the Verkkokauppa.com Finnish webshop. This skill uses the Verkkokauppa search API directly, requiring no browser. Use when the user asks to "search Verkkokauppa", "find products on verkkokauppa.com", "verkkokauppa product search", "check Verkkokauppa prices", or mentions searching the Verkkokauppa store.

1 0
Explore
akaihola/skills-akaihola

clasohlson

Search products on the Clas Ohlson Finland webshop (clasohlson.com/fi/). This skill uses the Voyado Elevate (Apptus eSales) search API directly, requiring no browser. Use when the user asks to "search Clas Ohlson", "find products on clasohlson.com", "clas ohlson product search", "check Clas Ohlson prices", or mentions searching the Finnish Clas Ohlson store.

1 0
Explore
akaihola/skills-akaihola

bauhaus

Search products on the Bauhaus webshop (bauhaus.fi). This skill uses the Algolia search API with automatic key refresh. Use when the user asks to "search Bauhaus", "find products on bauhaus.fi", "bauhaus product search", "check Bauhaus prices", or mentions searching the Bauhaus store.

1 0
Explore
akaihola/skills-akaihola

library

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results