Secrets Detection (SEC)

Analyze source code, configuration files, and git history for hardcoded credentials, API keys, tokens, private keys, and other sensitive material that should never appear in version control. Secrets in code are among the most immediately exploitable vulnerabilities -- a single leaked API key can lead to full account compromise within minutes.

Supported Flags

Read ../../shared/schemas/flags.md for the full flag specification. This skill supports all cross-cutting flags. Key behaviors:

Flag	Secrets-Specific Behavior
`--scope`	Default `changed`. Secrets analysis scans all file types including config, YAML, JSON, .env, scripts, and source code.
`--depth quick`	Scanners only (gitleaks/trufflehog), no manual pattern analysis.
`--depth standard`	Full file read of scoped files + Grep heuristics for patterns scanners miss.
`--depth deep`	Standard + scan git history for previously committed and removed secrets.
`--depth expert`	Deep + verify whether detected secrets are still active/valid, DREAD scoring.
`--severity`	Filter output. Most secrets findings are `critical` or `high`.
`--fix`	Generate remediation: remove secret, add to .gitignore, rotate credential.

Detection Patterns

Read references/detection-patterns.md for the full pattern catalog with language-specific examples, regex heuristics, and false positive guidance.

Pattern Summary:

API keys and tokens hardcoded in source code
Passwords and credentials in configuration files
.env files committed to version control
Private keys (RSA, EC, PGP) in repository
Database connection strings with embedded credentials
High-entropy strings matching secret patterns

Workflow

Step 1: Determine Scope

Parse --scope flag (default: changed).
Resolve to a concrete file list.
Include ALL file types -- secrets can appear anywhere: .py, .js, .ts, .java, .go, .env, .yml, .yaml, .json, .xml, .toml, .ini, .cfg, .conf, .properties, .tf, .tfvars, .sh, .bash, .zsh, .dockerfile, docker-compose.*, *.pem, *.key.
Check for .gitignore coverage of sensitive file patterns.

Step 2: Check for Scanners

Detect available scanners in priority order:

Scanner	Detect	Secrets Coverage
gitleaks	`which gitleaks`	150+ secret patterns, git history scanning, custom rules
trufflehog	`which trufflehog`	700+ credential detectors, live verification of found secrets
trivy	`which trivy`	Secrets detection as part of broader filesystem scan

Record which scanners are available and which are missing. If none are available, note: "No scanner available -- findings based on code pattern analysis only."

Step 3: Run Scanners

For each available scanner, run against the scoped files:

gitleaks detect --source <target> --report-format json --report-path /dev/stdout --no-banner
trufflehog filesystem --json <target>

At --depth deep, also scan git history:

gitleaks detect --source <target> --report-format json --report-path /dev/stdout --no-banner --log-opts="--all"
trufflehog git --json file://<target>

Normalize scanner output to the findings schema (see ../../shared/schemas/findings.md). Use the severity mapping from ../../shared/schemas/scanners.md.

Step 4: Claude Analysis

Read each scoped file and analyze for secret patterns not caught by scanners:

Identify secret-like values: Look for strings matching API key formats, base64-encoded credentials, high-entropy strings in assignment contexts.
Check context: Is the value in a variable named key, secret, token, password, credential, api_key, or similar?
Verify not placeholder: Exclude values like YOUR_API_KEY_HERE, changeme, xxx, dummy, test, example, placeholder.
Check .gitignore: Are .env, *.pem, *.key, credentials.json patterns in .gitignore? Flag missing patterns.
Deduplicate: Merge Claude findings with scanner findings.

At --depth deep or --depth expert:

Trace secret usage across files to map exposure surface.
Check if secrets are loaded from environment variables (good) vs hardcoded (bad).
Verify secret rotation practices (key age, rotation infrastructure).

Step 5: Report

Output findings using the format from ../../shared/schemas/findings.md.

Each finding must include:

id: SEC-001, SEC-002, etc.
title: Secret type and location (e.g., "AWS access key in config.py").
severity: Based on secret type, exposure scope, and verification status.
location: File, line, and masked snippet (NEVER include the full secret).
description: What type of secret was found and how it is exposed.
impact: What an attacker can access with this secret.
fix: Remove from code, add to .gitignore, rotate credential, use env vars.
references: CWE-798, CWE-321, CWE-312.

CRITICAL: Never output the actual secret value in findings. Always mask the middle portion: AKIA****XMPL.

What to Look For

These are the primary secret patterns to detect. Each has detailed examples and regex heuristics in references/detection-patterns.md.

AWS access keys: AKIA[0-9A-Z]{16} patterns in source code
Generic API keys: Long alphanumeric strings assigned to key/token variables
Passwords in config: password = "...", DB_PASSWORD, connection strings
Private keys: -----BEGIN RSA PRIVATE KEY----- and similar PEM headers
OAuth/JWT secrets: Client secrets, signing keys, bearer tokens
Cloud provider tokens: GCP service account keys, Azure connection strings
.env files committed: Entire environment files with production secrets
Git history secrets: Secrets that were committed then "removed" but remain in history
High-entropy strings: Base64 or hex strings in suspicious contexts
Connection strings: Database URIs with embedded username:password

Scanner Integration

Primary: gitleaks (fast, comprehensive pattern matching), trufflehog (live verification) Secondary: trivy (secrets as part of broader scanning) Fallback: Grep regex patterns from references/detection-patterns.md

When scanners are available, run them first and use Claude analysis to:

Validate scanner findings (filter false positives like example values).
Find secret patterns scanners miss (custom key formats, obfuscated secrets).
Assess impact based on secret type and code context.

When no scanners are available, Claude performs full pattern-based analysis using the Grep heuristics from references/detection-patterns.md and contextual code reading. Report these findings with confidence: medium.

Output Format

Use finding ID prefix SEC (e.g., SEC-001, SEC-002).

All findings follow the schema in ../../shared/schemas/findings.md with:

references.cwe: "CWE-798" (hardcoded credentials) or "CWE-312" (cleartext storage)
references.owasp: "A07:2021" (Identification and Authentication Failures)
metadata.tool: "secrets"
metadata.framework: "specialized"
metadata.category: "SEC"

CWE Mapping by Secret Type:

Secret Type	CWE	Typical Severity
Hardcoded password	CWE-798	critical
API key in source	CWE-798	critical
Private key committed	CWE-321	critical
.env file committed	CWE-312	high
Connection string with credentials	CWE-798	critical
High-entropy string (unverified)	CWE-798	medium
Missing .gitignore for secret files	CWE-312	medium

Summary Table

After all findings, output a summary:

| Secret Type        | Critical | High | Medium | Low |
|--------------------|----------|------|--------|-----|
| API Keys/Tokens    |          |      |        |     |
| Passwords          |          |      |        |     |
| Private Keys       |          |      |        |     |
| Connection Strings |          |      |        |     |
| .env / Config      |          |      |        |     |
| Git History        |          |      |        |     |

Followed by: top 3 priorities, scanner coverage notes, rotation recommendations, and overall assessment.