Detection with secret scanning — gitleaks, truffleHog, and the CI gate

Detection is the only preventive measure that catches a secret before it is committed, and the only detective measure that catches one after the leak. The lesson is the detector landscape: gitleaks, TruffleHog, the native GitHub and GitLab scanners, and the gate that turns a report into a control.

The detector landscape

• gitleaks ships with hundreds of regex rules for known providers (AWS, GitHub, Stripe, OpenAI) and falls back to Shannon entropy for unknown high-entropy strings. Fast enough for a pre-commit hook, strict enough for a CI gate.

gitleaks detect --source . --verbose

gitleaks protect --staged --verbose

• TruffleHog focuses on high-entropy strings and verifies them against the live provider. The difference between “matched a regex” and “verified live” is the difference between a queue of alerts and a queue of confirmed incidents.
• GitHub native secret scanning runs on every push and partners with major providers; in some cases it auto-revokes the credential.
• GitLab native secret detection runs as a pipeline stage with a broad default ruleset.

Production teams typically run gitleaks in CI as the gate, TruffleHog on a nightly schedule, and the native scanner for partner-token coverage.

flowchart LR
    A["commit attempt"] --> B["pre-commit: gitleaks protect"]
    B -->|"clean"| C["push"]
    B -->|"finding"| Z["block commit"]
    C --> D["CI: gitleaks detect"]
    D -->|"clean"| E["merge"]
    D -->|"finding"| Y["fail build"]
    E --> F["nightly: TruffleHog history"]

The CI gate

The shape in GitHub Actions:

name: secret-scan
on:
  pull_request:
    branches: [main]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${ secrets.GITHUB_TOKEN }

The step fails the build when gitleaks finds a secret; the failed build locks the merge; the engineer is forced to remove the secret or escalate. The override requires a senior reviewer’s approval and is logged in the audit trail.

Regex and entropy trade-off

Regex rules match a known provider’s credential format. False-positive rate is low; false-negative rate is high because the unknown credential is not in the ruleset.

Entropy rules flag any string of sufficient length and randomness. False-positive rate is high because base64 blobs look like secrets; false- negative rate is low because unknown credentials are flagged.

The production trade-off is both, with careful tuning. gitleaks’s default ruleset is the starting point: regex for known providers, entropy with a high threshold (Shannon entropy greater than 4.5) for unknown. The cost of false positives is review fatigue; the cost of false negatives is a leaked secret.

The position of the gate

Three positions exist; the production answer is all three:

• Pre-commit (engineer’s machine). Runs gitleaks protect --staged before the commit. Fastest catch; skippable with --no-verify.
• Pre-receive (forge or mirror). Runs on every push. Cheapest catch; needs forge support.
• CI (pipeline). Runs on every pull request. Most visible catch; the commit lands on the branch before the gate runs.

The three are layered. The pre-commit hook catches the secret the engineer did not realise was a secret; the pre-receive hook catches the push that bypassed the local hook; the CI gate catches the push that bypassed both; the nightly full-history scan catches the historical commits that were scanned before the ruleset was complete.

Production discipline

1. The gate is the merge, not the alert. A detector that prints a report and lets the merge proceed is a reporting tool. The gateway is the build that fails; the merge that is blocked.
2. The ruleset is owned. The team owns the ruleset for the credentials the team issues; the ruleset changes when the credentials change.
3. Verification is the difference between a queue and a backlog. A regex match is a candidate. A verified credential is an incident.

Cross-course references

• Linux for Production Sysadmins - Part XXXIV (ConfigMgmt) covers the rotation that runs after a verified finding.
• Ansible for Production Sysadmins - Part XXXVII (RepoArch) covers the allowlist for vault content.
• Terraform for Production Sysadmins - Parts IX-XII (State) cover committed .tf files and variable files the detector must scan.

Quiz