How do I install the Gitleaks skill?

Run npx skillmds@latest add igbuend/gitleaks in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Gitleaks skill do?

Run Gitleaks for hardcoded secrets detection in code and git history. Use when scanning for API keys, passwords, tokens, certificates, or sensitive credentials in source code and commit history. It is listed under Integrations & APIs on SkillMD.

Is Gitleaks safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Gitleaks?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Gitleaks free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Gitleaks?

igbuend (@igbuend) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Gitleaks by igbuend — Agent Skill

Name: Gitleaks
Author: igbuend

Gitleaks Secret Detection

When to Use Gitleaks

Ideal scenarios:

Scanning for hardcoded secrets in source code
Auditing git history for leaked credentials
Pre-commit hooks to prevent secret commits
CI/CD pipeline secret detection
Finding API keys, passwords, tokens, private keys
Compliance requirements for credential management

Complements other tools:

Use before manual code review to catch obvious secrets
Combine with SARIF Issue Reporter for detailed analysis
Use alongside Application Inspector for comprehensive security audit

When NOT to Use

Do NOT use this skill for:

Code vulnerability detection (use Semgrep or CodeQL)
Dependency scanning (use OSV-Scanner or Depscan)
IaC security analysis (use KICS)
Technology profiling (use Application Inspector)
Finding secrets in binary files or compiled code

Installation

# Homebrew (macOS/Linux)
brew install gitleaks

# Binary download
wget https://github.com/gitleaks/gitleaks/releases/latest/download/gitleaks-linux-amd64
chmod +x gitleaks-linux-amd64
sudo mv gitleaks-linux-amd64 /usr/local/bin/gitleaks

# Docker
docker pull ghcr.io/gitleaks/gitleaks:latest

# Go install
go install github.com/gitleaks/gitleaks/v8@latest

# Verify
gitleaks version

Core Workflow

1. Quick Scan

# Scan current directory (git repo)
gitleaks detect

# Scan specific directory
gitleaks detect --source /path/to/repo

# Scan uncommitted changes only
gitleaks protect

# Scan with no banner/color (for CI)
gitleaks detect --no-banner --no-color

2. SARIF Output

# Generate SARIF report
gitleaks detect \
  --report-format sarif \
  --report-path results.sarif

# With additional options
gitleaks detect \
  --source /path/to/repo \
  --report-format sarif \
  --report-path results.sarif \
  --no-banner \
  --no-color \
  --exit-code 0

# Redact secrets in output
gitleaks detect \
  --report-format sarif \
  --report-path results.sarif \
  --redact

3. Scan Git History

# Scan all commits
gitleaks detect --source /path/to/repo --verbose

# Scan specific commit range
gitleaks detect --log-opts="--since='2024-01-01'"

# Scan specific branch
gitleaks detect --source /path/to/repo --log-opts="origin/main"

4. Additional Formats

# JSON output
gitleaks detect --report-format json --report-path results.json

# CSV output
gitleaks detect --report-format csv --report-path results.csv

# JUnit XML
gitleaks detect --report-format junit --report-path results.xml

Configuration

Custom Config File

Create .gitleaks.toml:

title = "Gitleaks Configuration"

[extend]
# Extend default config
useDefault = true

[[rules]]
id = "custom-api-key"
description = "Custom API Key Pattern"
regex = '''(?i)api[_-]?key['\"]?\s*[:=]\s*['\"]([a-z0-9]{32,})'''
keywords = ["apikey", "api_key"]

[[rules]]
id = "slack-webhook"
description = "Slack Webhook URL"
regex = '''https://hooks\.slack\.com/services/T[a-zA-Z0-9_]{8,}/B[a-zA-Z0-9_]{8,}/[a-zA-Z0-9_]{24,}'''

[[rules]]
id = "aws-access-key"
description = "AWS Access Key"
regex = '''AKIA[0-9A-Z]{16}'''
keywords = ["AKIA"]

[allowlist]
description = "Allowlist for false positives"
regexes = [
  '''EXAMPLE_API_KEY''',
  '''placeholder-secret''',
  '''test-token-123'''
]
paths = [
  '''.gitleaks.toml''',
  '''README.md''',
  '''docs/'''
]

Use Custom Config

gitleaks detect --config .gitleaks.toml

# With SARIF output
gitleaks detect \
  --config .gitleaks.toml \
  --report-format sarif \
  --report-path results.sarif

Ignoring False Positives

Inline Comments

# gitleaks:allow
api_key = "this-is-a-test-key-not-real"

password = "example-password"  # gitleaks:allow

.gitleaksignore File

Create .gitleaksignore:

# Ignore specific findings by fingerprint
fingerprint:abc123def456

# Ignore files
tests/fixtures/secrets.txt
docs/examples/*.py

# Ignore commits
commit:a1b2c3d4e5f6

Baseline Mode

# Create baseline of existing findings
gitleaks detect --report-path baseline.json --report-format json

# Scan only new findings
gitleaks detect --baseline-path baseline.json

CI/CD Integration (GitHub Actions)

name: Gitleaks

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  gitleaks:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for complete scan

      - name: Run Gitleaks
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}  # Optional: for Gitleaks Pro

      - name: Generate SARIF
        if: always()
        run: |
          gitleaks detect \
            --report-format sarif \
            --report-path gitleaks.sarif \
            --no-banner \
            --no-color \
            --exit-code 0

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: gitleaks.sarif
          category: gitleaks

      - name: Upload Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: gitleaks-results
          path: gitleaks.sarif

Pre-commit Hook

Install Pre-commit

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.21.2
    hooks:
      - id: gitleaks
EOF

# Install hook
pre-commit install

# Test
pre-commit run --all-files

Manual Git Hook

# Create .git/hooks/pre-commit
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
gitleaks protect --staged --verbose --redact
EOF

chmod +x .git/hooks/pre-commit

Common Use Cases

1. Initial Repository Audit

# Full history scan with SARIF output
gitleaks detect \
  --source /path/to/repo \
  --report-format sarif \
  --report-path full-audit.sarif \
  --verbose

# Review results
sarif summary full-audit.sarif

2. Pre-deployment Scan

# Scan only uncommitted changes
gitleaks protect --staged --verbose

# If secrets found, prevent commit
gitleaks protect --staged --exit-code 1

3. CI/CD Pipeline Integration

# Baldwin.sh pattern
gitleaks dir \
  --source /workspace/src \
  --report-format sarif \
  --report-path /workspace/output/sarif/gitleaks.sarif \
  --no-banner \
  --no-color \
  --ignore-gitleaks-allow \
  --exit-code 0

4. Remediation Workflow

# 1. Initial scan
gitleaks detect --report-format json --report-path findings.json

# 2. Review and create baseline
gitleaks detect --report-path baseline.json --report-format json

# 3. Track only new leaks
gitleaks detect --baseline-path baseline.json --verbose

# 4. After cleanup, verify
gitleaks detect --exit-code 1  # Fail if any secrets found

Understanding Output

SARIF Structure

Gitleaks SARIF v2.1.0 includes:

Rules: Each secret type (API key, password, token, etc.)
Results: Specific locations where secrets were found
Properties:
- commit: Git commit hash (if applicable)
- file: File path
- startLine: Line number
- endLine: Line number
- match: Redacted or full secret (depending on --redact)
- secret: The detected secret (if not redacted)

JSON Output Example

{
  "Description": "AWS Access Key",
  "StartLine": 42,
  "EndLine": 42,
  "StartColumn": 15,
  "EndColumn": 50,
  "Match": "AKIA****************",
  "Secret": "AKIA1234567890ABCDEF",
  "File": "config/aws.py",
  "SymlinkFile": "",
  "Commit": "a1b2c3d4e5f6g7h8",
  "Entropy": 4.5,
  "Author": "developer@example.com",
  "Email": "developer@example.com",
  "Date": "2024-01-15T10:30:00Z",
  "Message": "Add AWS configuration",
  "Tags": [],
  "RuleID": "aws-access-token",
  "Fingerprint": "a1b2c3d4e5f6g7h8:config/aws.py:aws-access-token:42"
}

Advanced Features

Entropy Detection

# Enable entropy scanning (experimental)
gitleaks detect --verbose --log-level debug

Custom Rules Only

# Disable default rules, use custom only
gitleaks detect --config custom-rules.toml --no-default-config

Scanning Specific Files

# Scan only Python files
gitleaks detect --source /code --log-opts="--all -- '*.py'"

# Exclude vendor directories
gitleaks detect --source /code --log-opts="--all -- . ':!vendor'"

Performance Considerations

# Faster scans: limit git log depth
gitleaks detect --log-opts="--max-count=1000"

# Scan only recent commits
gitleaks detect --log-opts="--since='1 month ago'"

# Parallel processing (default)
gitleaks detect --source /large/repo

Limitations

Binary files: Limited detection in compiled/binary files
Obfuscation: Misses heavily obfuscated or encoded secrets
Context-aware: Can't determine if secret is actually valid/active
False positives: Regex-based, may flag test data or examples
Git required: Directory scans work, but git history scanning needs .git

Rationalizations to Reject

Shortcut	Why It's Wrong
"Gitleaks found nothing = no secrets"	Obfuscated, encrypted, or dynamically constructed secrets are missed
"Only scan code, skip git history"	Secrets in history can still be exploited; attackers check git logs
"Disable in CI for speed"	Secret leaks are critical; speed should never compromise security
"Mark all as false positive"	Each finding needs review; some may be valid credentials
"Don't use --redact in reports"	Unredacted secrets in reports can leak to logs, artifacts, or dashboards

References

Repository: https://github.com/gitleaks/gitleaks
Documentation: https://gitleaks.io/
Default Rules: https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml
SARIF Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
Pre-commit Hook: https://github.com/gitleaks/gitleaks#pre-commit

Gitleaks

File contents

Gitleaks Secret Detection

When to Use Gitleaks

When NOT to Use

Installation

Core Workflow

1. Quick Scan

2. SARIF Output

3. Scan Git History

4. Additional Formats

Configuration

Custom Config File

Use Custom Config

Ignoring False Positives

Inline Comments

.gitleaksignore File

Baseline Mode

CI/CD Integration (GitHub Actions)

Pre-commit Hook

Install Pre-commit

Manual Git Hook

Common Use Cases

1. Initial Repository Audit

2. Pre-deployment Scan

3. CI/CD Pipeline Integration

4. Remediation Workflow

Understanding Output

SARIF Structure

JSON Output Example

Advanced Features

Entropy Detection

Custom Rules Only

Scanning Specific Files

Performance Considerations

Limitations

Rationalizations to Reject

References

Frequently asked questions

Gitleaks

File contents

Gitleaks Secret Detection

When to Use Gitleaks

When NOT to Use

Installation

Core Workflow

1. Quick Scan

2. SARIF Output

3. Scan Git History

4. Additional Formats

Configuration

Custom Config File

Use Custom Config

Ignoring False Positives

Inline Comments

.gitleaksignore File

Baseline Mode

CI/CD Integration (GitHub Actions)

Pre-commit Hook

Install Pre-commit

Manual Git Hook

Common Use Cases

1. Initial Repository Audit

2. Pre-deployment Scan

3. CI/CD Pipeline Integration

4. Remediation Workflow

Understanding Output

SARIF Structure

JSON Output Example

Advanced Features

Entropy Detection

Custom Rules Only

Scanning Specific Files

Performance Considerations

Limitations

Rationalizations to Reject

References

Related skills

Frequently asked questions

How do I install the Gitleaks skill?

What does the Gitleaks skill do?

Is Gitleaks safe to use?

Which AI agents work with Gitleaks?

Is Gitleaks free to use?

Who published Gitleaks?