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.

The configuration below is an example — a fully working implementation lives in the reference repository

The YAML and commands on this page are examples that show the essentials. For a complete, copy-and-run pipeline (including policy files and a sample app), see the Best Practice repository.

Tags in these examples versus production settings

The examples below keep mutable tags such as @v7 for readability. A tag can be repointed to a different commit later, so in production pin each action to a full commit SHA and grant only the permissions a job needs with a permissions: block. See Pipeline Security for the reasoning and the procedure.

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 (CLI core)¹
truffleHog	Deep history scanning + verification	Regex + entropy + API verification	AGPL-3.0

¹ The Gitleaks CLI itself is MIT, but the GitHub Actions wrapper gitleaks/gitleaks-action switched to a commercial license from v2.0.0. See Gitleaks Setup below.

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

---

Gitleaks Setup

gitleaks-action requires a license key for organization repositories

Since v2.0.0, gitleaks/gitleaks-action is free for personal-account repositories but requires a license key from gitleaks.io for organization-account repositories (a free Starter license covers 1 repository; more requires a paid plan), passed via the GITLEAKS_LICENSE secret. To stay fully free, call the Gitleaks CLI binary or the official Docker image directly instead of the Action wrapper, as shown below.

GitHub Actions

YAML

# .github/workflows/secret-detection.yml

name: Secret Detection — Gitleaks

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

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

      - name: Run Gitleaks (CLI, MIT license, free for organizations too)
        run: |
          docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:latest \
            detect --source /repo --verbose --redact

GitLab CI

YAML

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

secret-detection:
  stage: test
  image: ghcr.io/gitleaks/gitleaks:latest
  script:
    - gitleaks git .
      --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.

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.

YAML

# .pre-commit-config.yaml

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2 # the [[allowlists]] syntax requires v8.21 or later
    hooks:
      - id: gitleaks

Bash

# 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.

Bash

# 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

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

---

Secret Detection Result Analyzer

Upload a Gitleaks results file to get immediate response steps by exposed secret type.

Preview with a sample first (no API key required)

You can view the response steps for a pre-built sample scan result right away, without an API key. Get a feel for what the tool produces first, then run a real analysis on your own results below.

Run a real analysis on your own results

This tool requires an Anthropic API key

It calls the Anthropic API directly from your browser. Enter your own Anthropic API key to use it right away. Your key and inputs are sent only from your browser to Anthropic (they never pass through a trustedoss server). Usage is billed to your own Anthropic account.

In Practice

The Apache-2.0 project TRUSCA runs this check today. Open secret-scan.yml: gitleaks hard-fails the build on any leak and writes the result as SARIF, with detected values redacted in the log.

A leaked secret cannot be un-leaked, which is why this one area is worth gating from day one.

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

Bash

cd agents/en/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

---

Next Steps

• Secret inclusion risks in container images: Container Security
• Integrate the full pipeline: Pipeline Design