Secret Scanner

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

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

• 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

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

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

Phase 3: Report Generation

• 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

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

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

Phase 4: Remediation Guidance

• For each finding, attach remediation steps from

  references/remediation_guide.md

• For Critical findings: emphasize immediate rotation requirement

• 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

references/detection_patterns.md

references/gitleaks_config_template.toml

references/remediation_guide.md