Secret Scanner

Scans codebase for hardcoded secrets and credentials, returning structured findings for remediation.

Purpose & Scope

• •Detect hardcoded secrets using available tools (gitleaks, trufflehog) or manual patterns
• •Classify findings by severity (Critical/High/Medium/Low)
• •Filter false positives via baseline and allowlists
• •Provide remediation guidance per finding type
• •Return normalized report to parent orchestrator (ln-760)

When to Use

• •During project bootstrap (via ln-760-security-setup)
• •Pre-commit hook validation
• •CI/CD security pipeline
• •Manual security audit

Workflow

Phase 1: Tool Detection

Step 1: Check Available Scanners

• •Check if gitleaks is installed (preferred)
• •Check if trufflehog is installed (alternative)
• •If neither available: use manual pattern matching as fallback

Step 2: Load Configuration

• •Load project .gitleaks.toml if exists (custom rules)
• •Load .gitleaksbaseline if exists (known false positives)
• •If no config: use default patterns from references/detection_patterns.md

Phase 2: Scan Execution

Step 1: Run Available Scanner

• •Execute scanner against project root
• •Capture output in structured format (JSON/SARIF preferred)
• •If tool unavailable: run manual grep patterns for high-confidence secrets

Step 2: Parse Results

• •Normalize output to common format: file, line, pattern, raw_match
• •Preserve original severity if provided by tool

Phase 3: Report Generation

Step 1: Severity Classification

• •Map findings to severity levels per references/detection_patterns.md
• •Critical: AWS keys, private keys, JWT secrets
• •High: Generic passwords, connection strings
• •Medium: API keys (may be test data)
• •Low: Potential secrets requiring manual review

Step 2: False Positive Filtering

• •Apply baseline exclusions
• •Apply allowlist patterns (placeholders, test data, docs)
• •Mark filtered items as "excluded" with reason

Step 3: Build Report

• •Group findings by severity
• •Include file path, line number, pattern matched
• •Do NOT include actual secret values in report

Phase 4: Remediation Guidance

Step 1: Attach Remediation Actions

• •For each finding, attach remediation steps from references/remediation_guide.md
• •For Critical findings: emphasize immediate rotation requirement

Step 2: Return Results

• •Return structured findings list to orchestrator
• •Include summary: total scanned, total found, by severity

Critical Rules

1. •Never log actual secret values - redact in all outputs
2. •Treat any found secret as compromised - rotation required for Critical
3. •Preserve baseline - do not remove existing baseline entries
4. •Pre-commit priority - recommend pre-commit hook if not configured
5. •Git history awareness - warn if secret may exist in history (requires git-filter-repo)

Definition of Done

• • Scan completed using available tool or manual patterns
• • Findings classified by severity
• • False positives filtered via baseline/allowlist
• • Remediation guidance attached to each finding
• • Report returned in normalized format (no raw secret values)
• • Critical findings flagged with rotation requirement

Reference Files

Version: 2.0.0 Last Updated: 2026-01-10