GitLab Secret Detection Configuration & Tuning Prompt

You are a senior security engineer who has rolled out GitLab Secret Detection across many projects — tuning rules, handling false positives, doing full-history scans, integrating with credential revocation workflows.

I will provide:
- The symptom (FP rate high, leaked secret found, custom credentials not detected)
- Current Secret Detection config (template includes, exclusions)
- The credential type pattern that's missed or false-positive
- Whether full-history scan needed
- The revocation/rotation process

Your job:

1. **How GitLab Secret Detection works**:
   - Uses Gitleaks under the hood
   - Default ruleset covers AWS keys, GitHub PATs, Slack tokens, Stripe keys, generic API tokens, etc.
   - On MR: scans the diff against target branch
   - On default branch: scans the latest commit
   - History scan: configurable
2. **Enable**:
   ```yaml
   include:
   - template: Security/Secret-Detection.gitlab-ci.yml

   secret_detection:
     variables:
       SECRET_DETECTION_EXCLUDED_PATHS: "tests/fixtures/, examples/, docs/api-examples/"
       SECRET_DETECTION_HISTORIC_SCAN: "false"   # set true for full-history (slow)
   ```
3. **For custom rules**:
   - Provide a `.gitleaks.toml` config; GitLab respects it via `SECRET_DETECTION_RULESET_GIT_REFERENCE`
   - Or override via `gitleaks` config file in repo
4. **For false positives**:
   - Exclude paths via `SECRET_DETECTION_EXCLUDED_PATHS`
   - Add `# gitleaks:allow` comment near false-positive line (newer GitLab)
   - Vulnerability dismiss in Security Dashboard with reason
   - Custom rule with `allowlist` regex
5. **For full-history scan**:
   - `SECRET_DETECTION_HISTORIC_SCAN: "true"` — scans full git history (potentially slow)
   - Useful after enabling for the first time — find historic leaks
   - One-off; don't run on every pipeline
6. **For when a real leak is found**:
   - **Step 1: Revoke the credential** at the source (AWS, Stripe, etc.)
   - Step 2: Rotate to new credential
   - Step 3: Update consumers
   - Step 4 (optional): Scrub from git history (BFG / git filter-branch) — note: caches in mirrors, forks, GitHub etc. may persist
7. **For integration with credential lifecycle**:
   - GitHub has revoke-on-leak for AWS, others; GitLab self-managed needs manual
   - Webhook → revocation script for detected leaks
8. **Common false positives**:
   - Test fixtures with fake credentials
   - Documentation examples
   - Encrypted/sealed-secrets files
   - SBOM / lock files containing checksums that look like tokens

Mark DESTRUCTIVE: scrubbing git history (force-push rewriting; downstream forks break), ignoring a real leak ("we'll rotate later"), assuming history scrub equals security (caches matter).

---

Symptom: [DESCRIBE]
Current config:
```yaml
[PASTE secret_detection variables block]
```
Custom rules (if any): [DESCRIBE]
Goal: [tune / scan history / respond to leak]

Why this prompt works

Secret Detection is one of the highest-value scanners — leaking a token is a real incident. Tuning to balance false positives against missed real leaks is delicate. This prompt walks the workflow.

How to use it

1. Enable on every project. It’s cheap and high-value.
2. For repos with many fixtures, set SECRET_DETECTION_EXCLUDED_PATHS.
3. Run a one-time historic scan on new projects.
4. When a real leak is found, rotate FIRST, then history-scrub.

Useful commands

# Local scan (verify before pushing)
docker run --rm -v $(pwd):/repo zricethezav/gitleaks:latest detect --source /repo --verbose

# Full-history local scan
docker run --rm -v $(pwd):/repo zricethezav/gitleaks:latest detect --source /repo --no-git -v

# Pre-commit hook
# .pre-commit-config.yaml:
# - repo: https://github.com/gitleaks/gitleaks
#   rev: v8.18.0
#   hooks:
#   - id: gitleaks

# Search via API (GitLab vulnerabilities)
curl --header "PRIVATE-TOKEN: <t>" \
    "https://gitlab.example.com/api/v4/projects/<id>/vulnerabilities?report_type=secret_detection" | jq

# History scrub with BFG (use with care)
java -jar bfg.jar --replace-text passwords.txt repo.git
git -C repo.git reflog expire --expire=now --all && git -C repo.git gc --prune=now --aggressive

# History scrub with git-filter-repo
pip install git-filter-repo
git filter-repo --replace-text passwords.txt
git push --force-with-lease

Patterns

Enable + exclusions

include:
- template: Security/Secret-Detection.gitlab-ci.yml

secret_detection:
  variables:
    SECRET_DETECTION_EXCLUDED_PATHS: |
      tests/fixtures/, examples/, docs/examples/,
      sealed-secrets/, *.encrypted

One-time historic scan

historic-secret-scan:
  extends: [.secret-analyzer]
  variables:
    SECRET_DETECTION_HISTORIC_SCAN: "true"
  rules:
    - if: $RUN_HISTORIC_SCAN == "true"
      when: always
# Trigger via:
# curl -X POST -F "ref=main" -F "variables[RUN_HISTORIC_SCAN]=true" \
#     -F "token=<trigger>" "$GITLAB/api/v4/projects/<id>/trigger/pipeline"

Custom Gitleaks rules

# .gitleaks.toml (in repo root, applied automatically)
[allowlist]
  description = "Allowed patterns"
  paths = [
    '''tests/fixtures''',
    '''docs/examples'''
  ]
  regexes = [
    '''AKIAIOSFODNN7EXAMPLE''',  # AWS docs canonical example key
  ]

[[rules]]
  id = "internal-jwt"
  description = "Internal JWT signing key"
  regex = '''myorg_jwt_[A-Za-z0-9]{32,}'''
  tags = ["secret", "jwt"]

Inline suppression

# Bad — real-looking but fake credential
API_KEY = "sk_test_fake_key_for_testing"  # gitleaks:allow

Webhook-driven revocation

# Webhook receiver in your security platform
# 1. Receives GitLab webhook on `vulnerability_created` (Premium event)
# 2. Parses for secret_detection findings
# 3. Calls AWS/Stripe/GitHub APIs to revoke detected token
# 4. Creates a GitLab issue documenting the action

Leak response runbook

1. Notify: Open security incident channel
2. Revoke: Disable the credential at provider (AWS console, Stripe dashboard)
3. Audit: Check provider logs for unauthorized use
4. Rotate: Generate new credential
5. Update: Push new secret to GitLab variables / external secret manager
6. Verify: CI/CD using new credential successfully
7. Scrub (optional): Rewrite git history to remove
8. Communicate: Notify any teams using the credential
9. Post-mortem: How did the leak happen? Prevent recurrence

Common findings this catches

• High FP rate from test fixtures → exclude paths.
• Custom internal token format not detected → add .gitleaks.toml rule.
• Historic scan finds dozens of stale leaks → triage; rotate any still-valid.
• # gitleaks:allow overused — review periodically; suppression shouldn’t be the default response.
• Leak in MR scanned but legacy commits unchecked → run historic scan.
• Secret in lockfile / vendored content → exclude path or whitelist regex.
• Leak revoked but history not scrubbed → caches/mirrors may retain; weigh history rewrite cost.

When to escalate

• Suspected credential abuse — security incident response; involve cloud provider’s abuse team.
• Mass leak across many projects — coordinated rotation; comms plan.
• History rewrite needed across many forks/mirrors — coordinate; some forks may resist.