Secret Scanner

A comprehensive secret detection skill for AI agents. Detects API keys, tokens, passwords, private keys, and credentials across 50+ services. Features entropy-based detection, git history scanning, and CI/CD integration.

Capabilities

1. Secret Detection - Find hardcoded secrets using 200+ regex patterns
2. Entropy Analysis - Detect high-entropy strings that may be secrets
3. Provider Coverage - AWS, GCP, Azure, GitHub, Stripe, and 50+ more
4. Git History Scan - Scan entire commit history for leaked secrets
5. File Type Support - Code, configs, env files, JSON, YAML, and more
6. Risk Scoring - Score findings by severity and exposure context
7. False Positive Filtering - Smart exclusions for test data and examples
8. Remediation Guidance - Step-by-step secret rotation instructions
9. CI/CD Integration - Pre-commit hooks and GitHub Actions
10. Allowlist Support - Configure known-safe patterns to skip

Usage

/secret-scanner [command] [path] [options]

Commands

• scan <path> - Scan files or directories for secrets
• scan-git <path> - Scan git history for leaked secrets
• audit <path> - Full security audit with report generation
• verify <secret> - Check if a specific string matches secret patterns
• providers - List all supported secret providers
• report - Generate report from existing findings

Options

• --format <type> - Output format: json, markdown, sarif (default: markdown)
• --output <file> - Write results to file
• --severity <level> - Minimum severity: low, medium, high, critical
• --include <patterns> - File patterns to include
• --exclude <patterns> - File patterns to exclude
• --entropy <threshold> - Entropy threshold (default: 4.5)
• --no-entropy - Disable entropy-based detection
• --allowlist <file> - Path to allowlist configuration
• --git-depth <n> - Number of commits to scan (default: all)

Workflow

When invoked, follow this workflow:

Step 1: Determine Scan Scope

Ask the user to specify:

• Target path (file, directory, or repository)
• Scan type (current files, git history, or both)
• Whether to include entropy-based detection

Step 2: File Discovery

Use Glob to find relevant files:

# Source code
**/*.{py,js,ts,tsx,jsx,java,go,rb,php,cs,swift,kt,rs,c,cpp,h}

# Configuration
**/*.{env,json,yaml,yml,xml,toml,ini,conf,cfg,properties}

# Infrastructure
**/*.{tf,tfvars,hcl,dockerfile,docker-compose*}

# Shell scripts
**/*.{sh,bash,zsh,ps1,bat,cmd}

# Certificates and keys
**/*.{pem,key,p12,pfx,jks,keystore}

Step 3: Pattern Matching

Apply detection patterns from references/secret-patterns.md:

Critical Severity

# AWS Access Keys
AKIA[0-9A-Z]{16}

# AWS Secret Keys
(?i)aws.{0,20}['"][0-9a-zA-Z/+]{40}['"]

# GitHub Tokens
gh[pousr]_[A-Za-z0-9_]{36,255}

# Private Keys
-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----

High Severity

# Generic API Keys
(?i)(api[_-]?key|apikey)['"]?\s*[:=]\s*['"][a-zA-Z0-9_\-]{20,}['"]

# Generic Tokens
(?i)(token|bearer|auth)['"]?\s*[:=]\s*['"][a-zA-Z0-9_\-\.]{20,}['"]

# Passwords
(?i)(password|passwd|pwd)['"]?\s*[:=]\s*['"][^'"]{8,}['"]

Step 4: Entropy Analysis

For strings not matching known patterns, calculate Shannon entropy:

def calculate_entropy(string):
    """Calculate Shannon entropy of a string."""
    from collections import Counter
    import math

    if not string:
        return 0

    counts = Counter(string)
    length = len(string)

    entropy = -sum(
        (count / length) * math.log2(count / length)
        for count in counts.values()
    )

    return entropy

# Flag strings with entropy > 4.5 and length >= 20

Step 5: Context Analysis

For each potential secret:

1. Check surrounding context (variable names, comments)
2. Verify it's not in a test/example file
3. Check against allowlist
4. Determine exposure context (public repo, .env, etc.)

Step 6: Calculate Risk Score

Apply formula from references/risk-scoring.md:

Risk = (Sensitivity × 0.40) + (Exposure × 0.30) +
       (Verifiability × 0.15) + (Scope × 0.15)

Step 7: Generate Output

Format findings following examples/sample-finding.json:

{
  "id": "S-20260204-0001",
  "file": "config/settings.py",
  "line": 42,
  "secret_type": "aws_access_key",
  "provider": "AWS",
  "value_preview": "AKIA...XXXX",
  "confidence": 0.98,
  "risk_score": 95,
  "severity": "critical",
  "context": "AWS_ACCESS_KEY = 'AKIA[REDACTED]'",
  "remediation": [...],
  "verified": false
}

Supported Providers

Cloud Providers

Provider	Secret Types	Pattern Count
AWS	Access Keys, Secret Keys, Session Tokens	8
GCP	API Keys, Service Account Keys, OAuth	6
Azure	Storage Keys, Connection Strings, SAS Tokens	7
DigitalOcean	API Tokens, Spaces Keys	3
Heroku	API Keys, OAuth Tokens	2
Alibaba Cloud	Access Keys, Secret Keys	3

Code Platforms

Provider	Secret Types	Pattern Count
GitHub	Personal Access Tokens, App Tokens, OAuth	5
GitLab	Personal Tokens, Pipeline Tokens, Runner Tokens	4
Bitbucket	App Passwords, OAuth, Repository Tokens	3
npm	Auth Tokens, Publish Tokens	2
PyPI	API Tokens	1

Payment Services

Provider	Secret Types	Pattern Count
Stripe	Secret Keys, Publishable Keys, Restricted Keys	4
PayPal	Client Secrets, Access Tokens	2
Square	Access Tokens, Application IDs	2
Braintree	Access Tokens, Merchant IDs	2

Communication Services

Provider	Secret Types	Pattern Count
Twilio	Account SID, Auth Token, API Key	4
SendGrid	API Keys	2
Mailchimp	API Keys	1
Slack	Bot Tokens, User Tokens, Webhooks	4
Discord	Bot Tokens, Webhooks	2

Database Services

Provider	Secret Types	Pattern Count
MongoDB	Connection Strings	2
PostgreSQL	Connection Strings	2
MySQL	Connection Strings	2
Redis	Connection Strings, Auth Tokens	2

Other Services

Provider	Secret Types	Pattern Count
OpenAI	API Keys	2
Anthropic	API Keys	1
Firebase	API Keys, Admin SDK Keys	3
Cloudflare	API Keys, API Tokens	2
Datadog	API Keys, App Keys	2
New Relic	License Keys, API Keys	2
Auth0	Client Secrets, API Tokens	2
Okta	API Tokens	1
JWT	Tokens (signature analysis)	1

Full pattern list: references/secret-patterns.md

Git History Scanning

Scan Modes

1. Full History - Scan all commits
2. Depth Limited - Scan last N commits
3. Branch Specific - Scan specific branch
4. Diff Mode - Only scan changed lines

Usage

# Scan entire history
/secret-scanner scan-git ./repo

# Scan last 100 commits
/secret-scanner scan-git ./repo --git-depth 100

# Scan specific branch
/secret-scanner scan-git ./repo --branch feature/auth

Git-Specific Findings

{
  "commit": "abc123",
  "author": "developer@example.com",
  "date": "2026-01-15T10:30:00Z",
  "message": "Add API configuration",
  "file": "config.py",
  "secret_type": "stripe_secret_key",
  "still_present": false,
  "removed_in": "def456"
}

Entropy-Based Detection

How It Works

1. Extract string literals and values from files
2. Calculate Shannon entropy for each string
3. Flag high-entropy strings (> 4.5) that are:
   • At least 20 characters long
   • Contain mixed character classes
   • In security-sensitive contexts

Entropy Thresholds

Threshold	Detection Level	False Positive Rate
3.5	Aggressive	High
4.0	Moderate	Medium
4.5	Balanced (default)	Low
5.0	Conservative	Very Low

Context Boosting

Entropy findings are boosted if found in:

• Variable names containing: key, secret, token, password, auth
• Files: .env, secrets.*, credentials.*
• Config sections: [credentials], [auth]

False Positive Handling

Built-in Exclusions

1. Test Files - *_test.*, *_spec.*, test_*.*, __tests__/*
2. Example Files - example.*, sample.*, demo.*
3. Documentation - *.md, *.rst, docs/*
4. Mock Data - Files containing "mock", "fake", "dummy"
5. Known Safe Patterns:
   • AKIAIOSFODNN7EXAMPLE (AWS example key)
   • sk_test_* (Stripe test keys)
   • pk_test_* (Stripe test publishable keys)
   • xoxb-PLACEHOLDER-EXAMPLE-TOKEN (Slack example)

Allowlist Configuration

Create .secret-scanner-allowlist.yaml:

# Allowlist configuration
patterns:
  # Regex patterns to ignore
  - "EXAMPLE_[A-Z_]+"
  - "test_api_key_\\d+"

paths:
  # Files/directories to skip
  - "test/"
  - "fixtures/"
  - "*.example"

hashes:
  # SHA256 hashes of known false positives
  - "abc123..."

comments:
  # Inline comments that suppress warnings
  - "# secret-scanner:ignore"
  - "// nosecret"

Risk Scoring

Severity Levels

Score	Severity	Response	Examples
90-100	Critical	Immediate	AWS keys, private keys, prod DB passwords
70-89	High	Within 4 hours	API keys, OAuth tokens, service accounts
50-69	Medium	Within 24 hours	Test API keys, internal tokens
25-49	Low	Within 1 week	Entropy matches, partial credentials
0-24	Info	Review	Possible false positives

Factor Weights

• Sensitivity (40%): Type of secret and potential damage
• Exposure (30%): Where the secret was found
• Verifiability (15%): Can the secret be validated as real
• Scope (15%): Blast radius if exploited

Full methodology: references/risk-scoring.md

Remediation Workflow

Step 1: Immediate Actions

1. Revoke the secret - Invalidate immediately in provider console
2. Rotate credentials - Generate new secret
3. Update applications - Deploy new credentials
4. Audit access logs - Check for unauthorized usage

Step 2: Clean Up

1. Remove from code - Delete the hardcoded secret
2. Clean git history - Use BFG or git filter-branch
3. Force push - Update all branches
4. Invalidate caches - Clear CI/CD caches

Step 3: Prevention

1. Add to .gitignore - Prevent future commits
2. Install pre-commit hook - Block commits with secrets
3. Use secrets manager - AWS Secrets Manager, HashiCorp Vault
4. Environment variables - Store secrets in environment

Provider-specific instructions: references/remediation.md

CI/CD Integration

Pre-Commit Hook

# Install the pre-commit hook
cp scripts/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Pre-commit Framework

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: secret-scanner
        name: Secret Scanner
        entry: python scripts/detect-secrets.py
        language: python
        types: [file]
        pass_filenames: true

GitHub Actions

# .github/workflows/secret-scan.yml
name: Secret Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git scanning
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Run Secret Scan
        run: |
          python scripts/detect-secrets.py . --format sarif --output results.sarif
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Environment Variables

# Configure behavior
export SECRET_SCANNER_SEVERITY=high      # Minimum severity to report
export SECRET_SCANNER_ENTROPY=4.5        # Entropy threshold
export SECRET_SCANNER_BLOCK=true         # Block on findings
export SECRET_SCANNER_ALLOWLIST=.secret-scanner-allowlist.yaml

Output Formats

JSON (findings.json)

Structured array with all findings and metadata.

Markdown (report.md)

Human-readable report with:

• Executive summary
• Findings by severity
• Provider breakdown
• Remediation checklist

SARIF

Static Analysis Results Interchange Format for GitHub Security tab integration.

Security Guardrails

1. Never output full secrets - Show only prefix/suffix with masking
2. Secure temporary files - Use scratchpad, clean up after
3. No secret logging - Redact from all log output
4. Verification is optional - Don't auto-verify against live APIs
5. Respect allowlists - Honor configured exclusions

References

• references/secret-patterns.md - All detection patterns
• references/provider-patterns.md - Provider-specific patterns
• references/entropy-detection.md - Entropy analysis methodology
• references/risk-scoring.md - Risk scoring methodology
• references/remediation.md - Secret rotation guides
• references/allowlist-config.md - Allowlist configuration

Examples

• examples/sample-finding.json - Example finding output
• examples/sample-report.md - Example audit report
• examples/allowlist.yaml - Example allowlist configuration

Scripts

• scripts/detect-secrets.py - Main secret detection script
• scripts/scan-git-history.py - Git history scanner
• scripts/entropy-analyzer.py - Entropy-based detection
• scripts/generate-report.py - Report generation
• scripts/pre-commit-hook.sh - Git pre-commit hook