secret-detection

# Skill: Secret Detection > **Expertise:** trufflehog, gitleaks, git-secrets, pre-commit hooks, CI scanning, secret rotation playbook. ## When to load When setting up secret scanning pre-commit or in CI, investigating a potential credential leak, or remediating secrets found in git history. ## Pre-Commit Hook Setup ```bash # Install pre-commit pip install pre-commit # .pre-commit-config.yaml repos: - repo: https://github.com/trufflesecurity/trufflehog rev: v3.88.0 hooks: - id: trufflehog name: TruffleHog — secret scan entry: trufflehog git file://. --since-commit HEAD --only-verified --fail language: system pass_filenames: false - repo: https://github.com/gitleaks/gitleaks rev: v8.21.0 hooks: - id: gitleaks name: Gitleaks — detect hardcoded secrets ``` ```bash # Install hooks for all team members (add to onboarding docs) pre-commit install pre-commit install --hook-type commit-msg # Run against all files (one-time audit) pre-commit run trufflehog --all-files pre-commit run gitleaks --all-files ``` ## CI: trufflehog (GitHub Actions) ```yaml - name: Scan for secrets (trufflehog) uses: trufflesecurity/trufflehog@main with: path: ./ base: ${{ github.event.repository.default_branch }} head: HEAD extra_args: > --only-verified --fail --format json --json-output trufflehog-results.json continue-on-error: false # hard fail - name: Upload results if: failure() uses: actions/upload-artifact@v4 with: name: secret-scan-results path: trufflehog-results.json ``` ## CI: gitleaks (GitLab CI) ```yaml secret-scan: stage: validate image: zricethezav/gitleaks:latest script: - gitleaks detect --source . --config .gitleaks.toml --redact --exit-code 1 --report-format json --report-path gitleaks-report.json artifacts: when: on_failure paths: [gitleaks-report.json] ``` ## gitleaks Configuration (.gitleaks.toml) ```toml # .gitleaks.toml title = "MyProject Gitleaks Config" [extend] useDefault = true # use built-in rules + extend # Custom rule: internal API keys [[rules]] id = "internal-api-key" description = "Internal API Key" regex = '''MYCOMPANY_API_KEY_[A-Za-z0-9]{32}''' tags = ["key", "internal"] # Allowlist: suppress known false positives [allowlist] description = "Global allowlist" regexes = [ '''EXAMPLE_.*''', # example values in docs '''test_.*_key''', # test fixtures ] paths = [ '''.gitleaks.toml''', # this file itself '''tests/fixtures/''', # test data ] commits = [ "abc123def456" # specific commit with known false positive ] ``` ## Full Repo Audit (historical scan) ```bash # Scan all branches and full history trufflehog git file://. \ --only-verified \ --format json | tee trufflehog-full-audit.json # Gitleaks: scan full history gitleaks detect \ --source . \ --log-opts "--all" \ --report-format json \ --report-path gitleaks-full-audit.json # Summary: count findings by type cat trufflehog-full-audit.json | jq 'group_by(.DetectorName) | map({type: .[0].DetectorName, count: length})' ``` ## Incident Response: Secret Exposed in Git ```bash # STOP: rotate the secret FIRST, before anything else # Only after rotation (new secret is active and old one invalid): # 1. Remove from git history using git-filter-repo (safer than filter-branch) pip install git-filter-repo git filter-repo \ --replace-text <(echo 'EXPOSED_SECRET==>REMOVED') \ --force # 2. Force push (coordinate with team — everyone must re-clone) git push --force --all git push --force --tags # 3. Notify all contributors to re-clone (old clones have the secret in history) # 4. Check if GitHub/GitLab cached the secret (check forks, PRs, CI logs) # GitHub: check cached pipelines in CI for the old secret # GitLab: check CI job logs, pipeline artifacts # 5. Audit: who may have cloned or cached the repo during exposure window # Check VCS audit logs for clone events # 6. File security incident report ``` ## False Positive Management ```bash # Inline suppression (trufflehog) SOME_VAR="obviously-not-a-secret" # trufflehog:ignore # Inline suppression (gitleaks) SOME_VAR="test-value" # gitleaks:allow # .gitleaksignore file (commit-hash based) # Get commit hash of false positive commit: git log --oneline | grep "Add example config" # Add to .gitleaksignore: echo "abc123def456:path/to/file.yaml" >> .gitleaksignore ```