implementing-secret-scanning-with-gitleaks
This skill covers implementing Gitleaks for detecting and preventing
v1.0.03 installs+3 in 7 days36.3K StarsApache-2.0synced 12 hours ago
Install
No NotHoly CLI yet? Install it first.
$ curl -fsSL https://notholy.com/install.sh | sh$ notholy skills install mukul975/implementing-secret-scanning-with-gitleaksWrites to ~/.notholy/skills after checking the signature and the SHA-256.
SignatureSigned, ed25519
Package64782f3c…70aaa438
64782f3c643e…bac770aaa4388 files · 17.1 KBScanHigh5 findings
- secret.aws_keyassets/template.md:82
- secret.aws_keyreferences/api-reference.md:41
- Executable script shipped with the skillscripts/agent.py
Sourcegithub.com/mukul975/Anthropic-Cybersecurity-Skills/tree/main/skills/implementing-secret-scanning-with-gitleaks@54a7988
On this page
When to Use
- When developers may accidentally commit API keys, passwords, tokens, or private keys to repositories
- When establishing pre-commit gates that prevent secrets from entering the git history
- When scanning existing repository history for previously committed secrets that need rotation
- When compliance requirements mandate secret detection across all source code repositories
- When migrating from manual secret audits to automated continuous scanning
Do not use for detecting secrets in running applications or memory (use runtime secret detection), for managing secrets after detection (use Vault or AWS Secrets Manager), or for scanning container images (use Trivy or Grype).
Prerequisites
- Gitleaks v8.18+ installed via binary, Go install, or Docker
- Pre-commit framework installed for local hook integration
- Git repository with history to scan
- CI/CD platform access (GitHub Actions, GitLab CI, or equivalent)
Workflow
Step 1: Install and Run Initial Repository Scan
Perform a baseline scan of the repository to identify all existing secrets in the git history.
# Install Gitleaks
brew install gitleaks # macOS
# or download binary from https://github.com/gitleaks/gitleaks/releases
# Scan entire git history for secrets
gitleaks detect --source . --report-format json --report-path gitleaks-report.json -v
# Scan only staged changes (for pre-commit)
gitleaks protect --staged --report-format json --report-path gitleaks-staged.json
# Scan specific commit range
gitleaks detect --source . --log-opts="HEAD~10..HEAD" --report-format json
# Scan without git history (filesystem only)
gitleaks detect --source . --no-git --report-format jsonStep 2: Configure Pre-Commit Hook
Set up Gitleaks as a pre-commit hook to prevent secrets from being committed.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.21.2
hooks:
- id: gitleaks
name: gitleaks
description: Detect hardcoded secrets using Gitleaks
entry: gitleaks protect --staged --verbose --redact
language: golang
pass_filenames: false# Install pre-commit framework
pip install pre-commit
# Install hooks defined in .pre-commit-config.yaml
pre-commit install
# Run against all files (not just staged)
pre-commit run gitleaks --all-files
# Test the hook with a deliberate secret
echo 'AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"' >> test.txt
git add test.txt
git commit -m "test" # Should be blocked by gitleaksStep 3: Integrate into GitHub Actions
# .github/workflows/secret-scanning.yml
name: Secret Scanning
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
jobs:
gitleaks:
name: Gitleaks Secret Scan
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for comprehensive scanning
- name: Run Gitleaks
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} # Required for gitleaks-action v2
# Alternative: Run Gitleaks directly
- name: Install Gitleaks
run: |
wget -q https://github.com/gitleaks/gitleaks/releases/download/v8.21.2/gitleaks_8.21.2_linux_x64.tar.gz
tar -xzf gitleaks_8.21.2_linux_x64.tar.gz
chmod +x gitleaks
- name: Scan for secrets
run: |
if [ "${{ github.event_name }}" == "pull_request" ]; then
./gitleaks detect \
--source . \
--log-opts="${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}" \
--report-format sarif \
--report-path gitleaks.sarif \
--exit-code 1
else
./gitleaks detect \
--source . \
--report-format sarif \
--report-path gitleaks.sarif \
--exit-code 1 \
--baseline-path .gitleaks-baseline.json
fi
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: gitleaks.sarif
category: gitleaksStep 4: Author Custom Detection Rules
Create organization-specific rules for internal secret patterns.
# .gitleaks.toml
title = "Organization Gitleaks Configuration"
[extend]
useDefault = true # Include all default rules
# Custom rule for internal API tokens
[[rules]]
id = "internal-api-token"
description = "Internal API token for service-to-service auth"
regex = '''(?i)x-internal-token["\s:=]+["\']?([a-zA-Z0-9_\-]{40,})["\']?'''
entropy = 3.5
keywords = ["x-internal-token"]
tags = ["internal", "api"]
[[rules]]
id = "database-connection-string"
description = "Database connection string with embedded credentials"
regex = '''(?i)(postgres|mysql|mongodb|redis)://[^:]+:[^@]+@[^/]+/\w+'''
keywords = ["postgres://", "mysql://", "mongodb://", "redis://"]
tags = ["database", "credentials"]
[[rules]]
id = "jwt-secret"
description = "JWT signing secret"
regex = '''(?i)(jwt[_-]?secret|jwt[_-]?key)["\s:=]+["\']?([a-zA-Z0-9/+_\-]{32,})["\']?'''
entropy = 3.0
keywords = ["jwt_secret", "jwt-secret", "jwt_key", "jwt-key"]
# Allowlist for test files and known safe patterns
[allowlist]
description = "Global allowlist"
paths = [
'''(^|/)test(s)?/''',
'''(^|/)spec/''',
'''\.test\.(js|ts|py)$''',
'''\.spec\.(js|ts|py)$''',
'''__mocks__/''',
'''fixtures/''',
'''(^|/)vendor/''',
'''node_modules/'''
]
regexes = [
'''EXAMPLE''',
'''example\.com''',
'''test[-_]?(key|secret|token|password)''',
'''(?i)placeholder''',
'''000000+'''
]Step 5: Manage Baselines for Existing Repositories
Create a baseline of known findings to avoid blocking development while historical secrets are being rotated.
# Generate baseline from current state
gitleaks detect --source . --report-format json --report-path .gitleaks-baseline.json
# Subsequent scans compare against baseline (only new findings trigger failures)
gitleaks detect --source . --baseline-path .gitleaks-baseline.json --exit-code 1
# Review baseline periodically and remove entries as secrets are rotated
cat .gitleaks-baseline.json | python3 -m json.tool | head -50Step 6: Remediate Exposed Secrets
When a secret is detected, follow the rotation and history cleanup procedure.
# 1. Immediately rotate the exposed credential
# - Revoke the old API key/token in the service provider
# - Generate a new credential
# - Store the new credential in a secrets manager
# 2. Remove secret from git history using git-filter-repo
pip install git-filter-repo
# Create expressions file for secrets to remove
cat > /tmp/expressions.txt << 'EOF'
regex:AKIA[0-9A-Z]{16}==>REDACTED_AWS_KEY
regex:(?i)password\s*=\s*"[^"]*"==>password="REDACTED"
EOF
git filter-repo --replace-text /tmp/expressions.txt --force
# 3. Force-push the cleaned history (coordinate with team)
# git push --force --all # WARNING: Requires team coordination
# 4. Add the secret pattern to .gitleaks.toml rules
# 5. Update the baseline file to remove the resolved findingKey Concepts
| Term | Definition |
|---|---|
| Secret | Any credential, token, key, or sensitive string that should not appear in source code |
| Pre-commit Hook | Git hook that runs before a commit is created, blocking commits containing detected secrets |
| Entropy | Measure of randomness in a string; high-entropy strings are more likely to be secrets |
| Baseline | Snapshot of existing findings used to differentiate new secrets from pre-existing ones |
| Allowlist | Configuration specifying paths, patterns, or commits to exclude from detection |
| SARIF | Static Analysis Results Interchange Format for uploading findings to security dashboards |
| git-filter-repo | Tool for rewriting git history to remove sensitive data from all commits |
Tools & Systems
- Gitleaks: Open-source secret detection tool supporting pre-commit hooks, CI/CD, and historical scanning
- pre-commit: Framework for managing and maintaining multi-language pre-commit hooks
- git-filter-repo: History rewriting tool for removing secrets from git history
- TruffleHog: Alternative secret scanner with verified secret detection capabilities
- GitHub Secret Scanning: Native GitHub feature that detects secrets matching partner patterns
Common Scenarios
Scenario: Onboarding Secret Scanning on a Legacy Repository
Context: A 5-year-old repository has never been scanned. The team needs to enable secret scanning without blocking all development while historical secrets are rotated.
Approach:
- Run
gitleaks detectagainst full history and generate a baseline JSON file - Triage each finding: classify as active (needs rotation), inactive (already rotated), or false positive
- Immediately rotate all active secrets and update consuming services
- Commit the baseline file (excluding active secrets that have been fixed)
- Enable pre-commit hooks for new development immediately
- Add CI/CD scanning with the baseline to catch only new secrets
- Progressively reduce the baseline as historical secrets are rotated
Pitfalls: Generating a baseline without triaging means accepting risk on unrotated secrets. Never assume a historical secret is inactive without verifying with the service provider. Running git-filter-repo on a shared repository without coordination will cause rebase conflicts for all team members.
Output Format
Gitleaks Secret Scanning Report
=================================
Repository: org/web-application
Scan Type: Full History
Commits Scanned: 4,523
Date: 2026-02-23
FINDINGS:
Total: 12
New (not in baseline): 3
Baseline (pre-existing): 9
NEW FINDINGS (blocking):
[1] AWS Access Key ID
Rule: aws-access-key-id
File: src/config/aws.py:23
Commit: a1b2c3d (2026-02-22, [email protected])
Secret: AKIA...REDACTED
Entropy: 3.8
[2] GitHub Personal Access Token
Rule: github-pat
File: scripts/deploy.sh:15
Commit: d4e5f6g (2026-02-21, [email protected])
Secret: ghp_...REDACTED
Entropy: 4.2
[3] Internal API Token
Rule: internal-api-token
File: src/services/auth.py:89
Commit: h7i8j9k (2026-02-20, [email protected])
QUALITY GATE: FAILED (3 new findings)
Action: Rotate exposed credentials immediately.Files in this version
assets/14.7 KB
- template.md4.7 KB
references/311.8 KB
- api-reference.md4.5 KB
- standards.md2.2 KB
- workflows.md5.0 KB
scripts/217.0 KB
- agent.py7.2 KB
- process.py9.8 KB
- LICENSE11.0 KB
- SKILL.md11.1 KB
Permissions
| Permission | Declared | Found by the scan |
|---|---|---|
| Reads files | Yes | Yes |
| Writes files | Yes | Yes |
| Runs shell commands | Yes | Yes |
| Uses the network | Yes | Yes |
| Uses connectors | No | No |
| Drives a browser | No | No |
Scan findings
Reviewed on Nov 13, 2026
- HighSecret · secret.aws_keyassets/template.md:82
- HighSecret · secret.aws_keyreferences/api-reference.md:41
- MediumFile · Executable script shipped with the skillscripts/agent.py
- MediumFile · Executable script shipped with the skillscripts/process.py
- InfoLink · Links to outside domains
A clean scan lowers the risk but does not prove a package is safe. Read what you install.
| Version | Published | Commit | SHA-256 | Signature | Permission change |
|---|---|---|---|---|---|
| v1.0.0 | Nov 13, 2026 | 54a7988 | 64782f3c | Signed | – |
More from mukul975
All from this publisher- testing-for-xml-injection-vulnerabilitiesmukul975/testing-for-xml-injection-vulnerabilities5
- testing-for-sensitive-data-exposuremukul975/testing-for-sensitive-data-exposure5
- performing-jwt-none-algorithm-attackmukul975/performing-jwt-none-algorithm-attack5
- detecting-aws-credential-exposure-with-trufflehogmukul975/detecting-aws-credential-exposure-with-trufflehog5
More in Reporting and compliance
See the category- skillduty1g/skill5
- rea-ci-tests-auditmorluto/rea-ci-tests-audit4
- tracking-threat-actor-infrastructuremukul975/tracking-threat-actor-infrastructure4
- performing-authenticated-scan-with-openvasmukul975/performing-authenticated-scan-with-openvas4
- slicing-code-contexttrailofbits/slicing-code-context4
- 1337aeondave/13374
Ask anything your scope allows.
Create an account, add credits and ask the first question in the chat or the terminal.
- 1/3
Create the account
Individual or company. You can switch to a company later without losing balance or keys.
IndividualCompany - 2/3
Add credits
By card. Pay per token, no subscription.
$5.00minimum deposit - 3/3
Ask
In the chat, or install the CLI and run notholy login in your terminal.
$ notholy login