Secret Detection

Why Secret Detection Matters

Committed secrets remain in git history even after deletion

Even if you overwrite with force push, exposed secrets may remain in already-cloned repositories, forks, and CI caches. Exposed secrets must be revoked and reissued immediately.

Common mistake: Teams often commit AWS Access Keys, GitHub Tokens, DB passwords, and private keys hardcoded in .env or config files. In public repositories, automated bots can collect them within minutes.

Cost impact: There are frequent cases where a single exposed cloud key results in millions of KRW in charges. Incident response costs are often hundreds of times higher than detection and prevention costs.

Tool Comparison

Tool	Key Characteristics	Detection Method	License
Gitleaks	Fast and simple configuration	Regex + entropy	MIT
truffleHog	Deep history scanning + verification	Regex + entropy + API verification	AGPL-3.0

For baseline CI/CD pipelines, Gitleaks is recommended. For auditing full history in existing repositories, truffleHog is recommended.

Gitleaks Setup

GitHub Actions

# .github/workflows/secret-detection.yml

name: Secret Detection — Gitleaks

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # scan full history

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

# .gitlab-ci.yml (secret-detection job section)

secret-detection:
  stage: test
  image: zricethezav/gitleaks:latest
  script:
    - gitleaks detect
      --source .
      --config .gitleaks.toml
      --exit-code 1
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Exception Handling Configuration

Manage patterns excluded from detection in .gitleaks.toml.

# .gitleaks.toml

[extend]
useDefault = true

[[allowlists]]
description = "dummy secret for testing"
regexes = [
  '''(?i)example''',
  '''(?i)dummy''',
  '''(?i)test[-_]?key''',
]

[[allowlists]]
description = "exclude specific file"
paths = [
  '''tests/fixtures/.*''',
  '''docs/.*\.md''',
]

pre-commit Hook Setup

Blocking before commit with pre-commit avoids waiting for CI

Blocking at local commit time reduces the CI fail -> fix -> re-push cycle.

# .pre-commit-config.yaml

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

# install pre-commit
pip install pre-commit

# register hooks
pre-commit install

Full Existing Repository Scan — truffleHog

When adopting secret detection, it is recommended to run a one-time audit of full git history with truffleHog.

# scan full history
trufflehog git file://. --only-verified

# scan specific branch only
trufflehog git file://. --branch main --only-verified

The --only-verified option outputs only truly valid secrets, reducing false positives.

Exposure Response Procedure

Immediately revoke and reissue: Disable exposed keys/tokens immediately in the corresponding service (AWS, GitHub, GCP, etc.) and issue new keys.
Clean history: Remove from history using git filter-repo or BFG Repo Cleaner. Note this does not affect repositories already cloned.
Review access logs: Review API call logs made with the key during the exposure window.
Prevent recurrence: Review .gitleaks.toml exception rules, strengthen team training, and consider introducing a secret manager (e.g., Vault).

Self-Study

Revoke actually exposed secrets immediately before analysis

Generate secret response procedures with Claude Code

The analyzer above is available directly in your browser. If you need type-specific revocation CLI commands and git history cleanup scripts, use the agent below.

Prerequisite: Clone the Trusted OSS repository

cd agents/secret-analyst
claude

The agent automatically performs the following:

Automatically classifies secret types (AWS, GitHub, DB, etc.)
Generates type-specific revocation and reissue CLI commands
Generates git filter-repo / BFG history cleanup scripts
Generates .gitleaks.toml false-positive exception examples