Security: Secret Detection
This skill activates when performing secret detection, credential scanning, or implementing security checks for leaked sensitive data in code repositories.
When to Use This Skill
Activate when:
-
Scanning repositories for leaked secrets, API keys, or credentials
-
Setting up pre-commit hooks for secret detection
-
Auditing codebases for exposed passwords or tokens
-
Implementing CI/CD security pipelines
-
Checking git history for accidentally committed secrets
-
Validating that .gitignore excludes sensitive files
Pre-Commit Hook (Automatic)
When this skill is loaded, a pre-commit hook automatically scans staged files for secrets before every git commit command. This provides defense-in-depth by catching secrets before they enter git history.
Hook Behavior
git commit -m "message" ↓ PreToolUse hook fires ↓ Extract staged files ↓ Run gitleaks --no-git ↓ ┌─ Clean ─┴─ Secrets ─┐ ↓ ↓ Allow Block commit commit (exit code 2)
What Gets Scanned
-
Only staged files are scanned (not the entire working tree)
-
Uses .gitleaks-baseline.json if present to ignore known false positives
-
Uses .gitleaks.toml if present for custom detection rules
When Secrets Are Detected
If the hook detects secrets, the commit is blocked with guidance:
[gitleaks] SECRETS DETECTED in staged files! [gitleaks] Commit blocked. Remove secrets before committing. [gitleaks] [gitleaks] Options: [gitleaks] 1. Remove the secret from the file [gitleaks] 2. Use environment variables instead [gitleaks] 3. Add to .gitleaks-baseline.json if false positive
Container Runtime Requirements
The hook requires a container runtime to run gitleaks. It auto-detects:
-
Apple Container (macOS 26+)
-
Docker (Docker Desktop or Engine)
-
Colima via mise
If no runtime is available, the hook logs a warning and allows the commit.
When to Use security-review Instead
Use the security-review skill for:
-
STRIDE threat modeling
-
Security architecture reviews
-
Vulnerability assessments
-
Security documentation and reports
-
Risk prioritization
-
Attack surface analysis
Task Use security
Use security-review
Scan for secrets in code ✓
Detect leaked API keys ✓
Pre-commit secret scanning ✓
STRIDE threat modeling
✓
Security architecture review
✓
Vulnerability assessment
✓
Security report documentation
✓
Risk prioritization
✓
Gitleaks
Gitleaks is an open-source tool for detecting secrets and sensitive information in git repositories. It scans commit history and file contents for patterns matching known secret formats.
Common Secrets Detected
-
AWS Access Keys and Secret Keys
-
Google Cloud API Keys
-
GitHub Personal Access Tokens
-
Private Keys (RSA, SSH, PGP)
-
Database Connection Strings
-
JWT Tokens
-
Stripe API Keys
-
Slack Tokens
-
Generic Passwords and API Keys
Basic Usage
Scan current directory
gitleaks detect --source="." -v
Scan with JSON report
gitleaks detect --source="." -v --report-path=report.json --report-format=json
Scan only staged changes (pre-commit)
gitleaks protect --staged
Scan git history
gitleaks detect --source="." --log-opts="--all"
Configuration
Create a .gitleaks.toml file to customize detection:
[extend]
Extend default rules
useDefault = true
[[rules]] id = "custom-api-key" description = "Custom API Key Pattern" regex = '''(?i)custom[-]?api[-]?key['"]?\s*[=:]\s*'"''' keywords = ["custom_api_key", "custom-api-key"]
[allowlist] paths = [ '''.gitleaks.toml$''', '''(.)?test(.)''', '''.git''' ]
regexes = [ '''EXAMPLE_.*''', '''REDACTED''' ]
Exit Codes
-
0 : No leaks found
-
1 : Leaks detected
-
Other: Configuration or runtime error
Scripts
This skill includes scripts for running gitleaks with automatic container runtime detection.
gitleaks.nu (Nushell)
Cross-platform Nushell script with automatic runtime detection:
Run with auto-detected runtime
nu scripts/gitleaks.nu
Specify runtime
nu scripts/gitleaks.nu --runtime docker nu scripts/gitleaks.nu --runtime container # Apple Container (macOS 26+) nu scripts/gitleaks.nu --runtime colima
Generate report
nu scripts/gitleaks.nu --report ./report.json
Use custom config
nu scripts/gitleaks.nu --config ./.gitleaks.toml
Scan specific path
nu scripts/gitleaks.nu --path ./src
gitleaks.sh (Bash)
Bash script with the same capabilities:
Run with auto-detected runtime
./scripts/gitleaks.sh
Specify runtime
./scripts/gitleaks.sh --runtime docker ./scripts/gitleaks.sh -R container
Generate report
./scripts/gitleaks.sh --report ./report.json
Use custom config
./scripts/gitleaks.sh --config ./.gitleaks.toml
Container Runtimes
The scripts support three container runtimes with automatic detection:
Detection Priority
-
Apple Container (macOS 26+) - Native macOS containerization
-
Docker - Docker Desktop or Docker Engine
-
Colima - Lightweight container runtime via mise
Apple Container (macOS 26+)
Native container support in macOS 26 and later:
Check status
container system status
Start runtime
container system start
Run gitleaks
container run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v
Docker
Docker Desktop or Docker Engine:
Check status
docker info >/dev/null 2>&1
Start (macOS)
open -a Docker
Run gitleaks
docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v
Colima via mise
Lightweight runtime managed through mise:
Check status
mise exec colima@latest -- colima status
Start runtime
mise exec colima@latest -- colima start
Run gitleaks
mise exec colima@latest -- docker run -v $(pwd):/code zricethezav/gitleaks detect --source="/code" -v
Using mise exec provides automatic installation and version management without requiring global installation.
Pre-Commit Integration
Add gitleaks to pre-commit hooks:
.pre-commit-config.yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.0
hooks:
- id: gitleaks
Install and run:
pre-commit install pre-commit run gitleaks --all-files
CI/CD Integration
GitHub Actions
name: Gitleaks
on: [push, pull_request]
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 }}
GitLab CI
gitleaks: stage: security image: zricethezav/gitleaks:latest script: - gitleaks detect --source="." -v allow_failure: false
Baseline Management
Create a baseline to ignore known false positives:
Generate baseline
gitleaks detect --source="." -v --baseline-path=.gitleaks-baseline.json
Scan using baseline
gitleaks detect --source="." -v --baseline-path=.gitleaks-baseline.json
Add .gitleaks-baseline.json to version control to track acknowledged findings.
Best Practices
Shift-Left Security
-
Enable gitleaks in pre-commit hooks to catch secrets before they enter history
-
Run scans on every PR in CI/CD pipelines
-
Scan regularly even if not making changes
When Secrets Are Found
-
Revoke immediately - Rotate the exposed credential
-
Remove from history - Use git filter-branch or BFG Repo Cleaner
-
Add to .gitignore - Prevent future commits of sensitive files
-
Update baseline - If false positive, add to baseline
Prevention
-
Use environment variables for secrets
-
Use secret management tools (Vault, AWS Secrets Manager)
-
Add secret patterns to .gitignore
-
Configure IDE plugins to warn about secrets
-
Use .env.example files without real values
Mise Tasks Template
Copy the mise tasks from templates/mise.toml to add gitleaks scanning to any project:
Available tasks after copying template
mise gitleaks # Scan with Apple Container (default) mise gitleaks:docker # Scan with Docker mise gitleaks:colima # Scan with Colima
mise gitleaks:stop # Stop all runtimes mise gitleaks:stop:container mise gitleaks:stop:docker mise gitleaks:stop:colima
The tasks automatically:
-
Detect and use .gitleaks-baseline.json if present
-
Start the container runtime if not running
-
Scan the repository root
Key Principles
-
Defense in depth: Run checks at multiple stages (local, CI, scheduled)
-
Fail fast: Block PRs with detected secrets
-
Zero tolerance: Treat all secret exposures as security incidents
-
Continuous monitoring: Schedule regular scans of entire history
-
Clear ownership: Define who handles secret remediation