/secrets-gitleaks

name: secrets-gitleaks
description: >
  Hardcoded secret detection and prevention in git repositories and codebases using Gitleaks.
  Identifies passwords, API keys, tokens, and credentials through regex-based pattern matching
  and entropy analysis. Use when: (1) Scanning repositories for exposed secrets and credentials,
  (2) Implementing pre-commit hooks to prevent secret leakage, (3) Integrating secret detection
  into CI/CD pipelines, (4) Auditing codebases for compliance violations (PCI-DSS, SOC2, GDPR),
  (5) Establishing baseline secret detection and tracking new exposures, (6) Remediating
  historical secret exposures in git history.
version: 0.1.0
maintainer: SirAppSec
category: devsecops
tags: [secrets, gitleaks, secret-scanning, devsecops, ci-cd, credentials, api-keys, compliance]
frameworks: [OWASP, CWE, PCI-DSS, SOC2, GDPR]
dependencies:
  tools: [gitleaks, git]
references:
  - https://github.com/gitleaks/gitleaks
  - https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/
  - https://cwe.mitre.org/data/definitions/798.html

Secrets Detection with Gitleaks

Overview

Gitleaks is a secret detection tool that scans git repositories, files, and directories for hardcoded credentials including passwords, API keys, tokens, and other sensitive information. It uses regex-based pattern matching combined with Shannon entropy analysis to identify secrets that could lead to unauthorized access if exposed.

This skill provides comprehensive guidance for integrating Gitleaks into DevSecOps workflows, from pre-commit hooks to CI/CD pipelines, with emphasis on preventing secret leakage before code reaches production.

Quick Start

Scan current repository for secrets:

# Install gitleaks
brew install gitleaks  # macOS
# or: docker pull zricethezav/gitleaks:latest

# Scan current git repository
gitleaks detect -v

# Scan specific directory
gitleaks detect --source /path/to/code -v

# Generate report
gitleaks detect --report-path gitleaks-report.json --report-format json

Core Workflows

1. Repository Scanning

Scan existing repositories to identify exposed secrets:

# Full repository scan with verbose output
gitleaks detect -v --source /path/to/repo

# Scan with custom configuration
gitleaks detect --config .gitleaks.toml -v

# Generate JSON report for further analysis
gitleaks detect --report-path findings.json --report-format json

# Generate SARIF report for GitHub/GitLab integration
gitleaks detect --report-path findings.sarif --report-format sarif

**When to use**: Initial security audit, compliance checks, incident response.

2. Pre-Commit Hook Protection

Prevent secrets from being committed in the first place:

# Install pre-commit hook (run in repository root)
cat << 'EOF' > .git/hooks/pre-commit
#!/bin/sh
gitleaks protect --verbose --redact --staged
EOF

chmod +x .git/hooks/pre-commit

Use the bundled script for automated hook installation:

./scripts/install_precommit.sh

**When to use**: Developer workstation setup, team onboarding, mandatory security controls.

3. CI/CD Pipeline Integration

GitHub Actions

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

GitLab CI

gitleaks:
  image: zricethezav/gitleaks:latest
  stage: test
  script:
    - gitleaks detect --report-path gitleaks.json --report-format json --verbose
  artifacts:
    paths:
      - gitleaks.json
    when: always
  allow_failure: false

**When to use**: Automated security gates, pull request checks, release validation.

4. Baseline and Incremental Scanning

Establish security baseline and track only new secrets:

# Create initial baseline
gitleaks detect --report-path baseline.json --report-format json

# Subsequent scans detect only new secrets
gitleaks detect --baseline-path baseline.json --report-path new-findings.json -v

**When to use**: Legacy codebase remediation, phased rollout, compliance tracking.

5. Configuration Customization

Create custom `.gitleaks.toml` configuration:

title = "Custom Gitleaks Configuration"

[extend]
# Extend default config with custom rules
useDefault = true

[[rules]]
id = "custom-api-key"
description = "Custom API Key Pattern"
regex = '''(?i)(custom_api_key|custom_secret)[\s]*[=:][\s]*['"][a-zA-Z0-9]{32,}['"]'''
tags = ["api-key", "custom"]

[allowlist]
description = "Global allowlist"
paths = [
  '''\.md$''',           # Ignore markdown files
  '''test/fixtures/''',  # Ignore test fixtures
]
stopwords = [
  '''EXAMPLE''',         # Ignore example keys
  '''PLACEHOLDER''',
]

Use bundled configuration templates in `assets/`:

• `assets/config-strict.toml` - Strict detection (low false negatives)
• `assets/config-balanced.toml` - Balanced detection (recommended)
• `assets/config-custom.toml` - Template for custom rules

**When to use**: Reducing false positives, adding proprietary secret patterns, organizational standards.

Security Considerations

Sensitive Data Handling

• **Secret Redaction**: Always use `--redact` flag in logs and reports to prevent accidental secret exposure
• **Report Security**: Gitleaks reports contain detected secrets - treat as confidential, encrypt at rest
• **Git History**: Detected secrets in git history require complete removal using tools like `git filter-repo` or `BFG Repo-Cleaner`
• **Credential Rotation**: All exposed secrets must be rotated immediately, even if removed from code

Access Control

• **CI/CD Permissions**: Gitleaks scans require read access to repository content and git history
• **Report Access**: Restrict access to scan reports containing sensitive findings
• **Baseline Files**: Baseline JSON files contain secret metadata - protect wit