secrets-gitleaks — Skillopedia

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 Sc…

'', # Ignore markdown files\n '''test/fixtures/''', # Ignore test fixtures\n]\nstopwords = [\n '''EXAMPLE''', # Ignore example keys\n '''PLACEHOLDER''',\n]\n```\n\nUse bundled configuration templates in `assets/`:\n- `assets/config-strict.toml` - Strict detection (low false negatives)\n- `assets/config-balanced.toml` - Balanced detection (recommended)\n- `assets/config-custom.toml` - Template for custom rules\n\n**When to use**: Reducing false positives, adding proprietary secret patterns, organizational standards.\n\n## Security Considerations\n\n### Sensitive Data Handling\n\n- **Secret Redaction**: Always use `--redact` flag in logs and reports to prevent accidental secret exposure\n- **Report Security**: Gitleaks reports contain detected secrets - treat as confidential, encrypt at rest\n- **Git History**: Detected secrets in git history require complete removal using tools like `git filter-repo` or `BFG Repo-Cleaner`\n- **Credential Rotation**: All exposed secrets must be rotated immediately, even if removed from code\n\n### Access Control\n\n- **CI/CD Permissions**: Gitleaks scans require read access to repository content and git history\n- **Report Access**: Restrict access to scan reports containing sensitive findings\n- **Baseline Files**: Baseline JSON files contain secret metadata - protect with same controls as findings\n\n### Audit Logging\n\nLog the following for compliance and incident response:\n- Scan execution timestamps and scope (repository, branch, commit range)\n- Number and types of secrets detected\n- Remediation actions taken (credential rotation, commit history cleanup)\n- False positive classifications and allowlist updates\n\n### Compliance Requirements\n\n- **PCI-DSS 3.2.1**: Requirement 6.5.3 - Prevent hardcoded credentials in payment applications\n- **SOC2**: CC6.1 - Logical access controls prevent unauthorized credential exposure\n- **GDPR**: Article 32 - Appropriate security measures for processing personal data credentials\n- **CWE-798**: Use of Hard-coded Credentials\n- **CWE-259**: Use of Hard-coded Password\n- **OWASP A07:2021**: Identification and Authentication Failures\n\n## Bundled Resources\n\n### Scripts (`scripts/`)\n\n- `install_precommit.sh` - Automated pre-commit hook installation with configuration prompts\n- `scan_and_report.py` - Comprehensive scanning with multiple output formats and severity classification\n- `baseline_manager.py` - Baseline creation, comparison, and incremental scan management\n\n### References (`references/`)\n\n- `detection_rules.md` - Comprehensive list of built-in Gitleaks detection rules with CWE mappings\n- `remediation_guide.md` - Step-by-step secret remediation procedures including git history cleanup\n- `false_positives.md` - Common false positive patterns and allowlist configuration strategies\n- `compliance_mapping.md` - Detailed mapping to PCI-DSS, SOC2, GDPR, and OWASP requirements\n\n### Assets (`assets/`)\n\n- `config-strict.toml` - High-sensitivity configuration (maximum detection)\n- `config-balanced.toml` - Production-ready balanced configuration\n- `config-custom.toml` - Template with inline documentation for custom rules\n- `precommit-config.yaml` - Pre-commit framework configuration\n- `github-action.yml` - Complete GitHub Actions workflow template\n- `gitlab-ci.yml` - Complete GitLab CI pipeline template\n\n## Common Patterns\n\n### Pattern 1: Initial Repository Audit\n\nFirst-time secret scanning for security assessment:\n\n```bash\n# 1. Clone repository with full history\ngit clone --mirror https://github.com/org/repo.git audit-repo\ncd audit-repo\n\n# 2. Run comprehensive scan\ngitleaks detect --report-path audit-report.json --report-format json -v\n\n# 3. Generate human-readable report\n./scripts/scan_and_report.py --input audit-report.json --format markdown --output audit-report.md\n\n# 4. Review findings and classify false positives\n# Edit .gitleaks.toml to add allowlist entries\n\n# 5. Create baseline for future scans\ncp audit-report.json baseline.json\n```\n\n### Pattern 2: Developer Workstation Setup\n\nProtect developers from accidental secret commits:\n\n```bash\n# 1. Install gitleaks locally\nbrew install gitleaks # macOS\n# or use package manager for your OS\n\n# 2. Install pre-commit hook\n./scripts/install_precommit.sh\n\n# 3. Test hook with dummy commit\necho \"api_key = 'EXAMPLE_KEY_12345'\" > test.txt\ngit add test.txt\ngit commit -m \"test\" # Should be blocked by gitleaks\n\n# 4. Clean up test\ngit reset HEAD~1\nrm test.txt\n```\n\n### Pattern 3: CI/CD Pipeline with Baseline\n\nProgressive secret detection in continuous integration:\n\n```bash\n# In CI pipeline script:\n\n# 1. Check if baseline exists\nif [ -f \".gitleaks-baseline.json\" ]; then\n # Incremental scan - only new secrets\n gitleaks detect \\\n --baseline-path .gitleaks-baseline.json \\\n --report-path new-findings.json \\\n --report-format json \\\n --exit-code 1 # Fail on new secrets\nelse\n # Initial scan - create baseline\n gitleaks detect \\\n --report-path .gitleaks-baseline.json \\\n --report-format json \\\n --exit-code 0 # Don't fail on first scan\nfi\n\n# 2. Generate SARIF for GitHub Security tab\nif [ -f \"new-findings.json\" ] && [ -s \"new-findings.json\" ]; then\n gitleaks detect \\\n --baseline-path .gitleaks-baseline.json \\\n --report-path results.sarif \\\n --report-format sarif\nfi\n```\n\n### Pattern 4: Custom Rule Development\n\nAdd organization-specific secret patterns:\n\n```toml\n# Add to .gitleaks.toml\n\n[[rules]]\nid = \"acme-corp-api-key\"\ndescription = \"ACME Corp Internal API Key\"\nregex = '''(?i)acme[_-]?api[_-]?key[\\s]*[=:][\\s]*['\"]?([a-f0-9]{40})['\"]?'''\nsecretGroup = 1\ntags = [\"api-key\", \"acme-internal\"]\n\n[[rules]]\nid = \"acme-corp-database-password\"\ndescription = \"ACME Corp Database Password Format\"\nregex = '''(?i)(db_pass|database_password)[\\s]*[=:][\\s]*['\"]([A-Z][a-z0-9@#$%]{15,})['\"]'''\nsecretGroup = 2\ntags = [\"password\", \"database\", \"acme-internal\"]\n\n# Test custom rules\n# gitleaks detect --config .gitleaks.toml -v\n```\n\n## Integration Points\n\n### CI/CD Integration\n\n- **GitHub Actions**: Use `gitleaks/gitleaks-action@v2` for native integration with Security tab\n- **GitLab CI**: Docker-based scanning with artifact retention for audit trails\n- **Jenkins**: Execute via Docker or installed binary in pipeline stages\n- **CircleCI**: Docker executor with orb support\n- **Azure Pipelines**: Task-based integration with results publishing\n\n### Security Tools Ecosystem\n\n- **SIEM Integration**: Export JSON findings to Splunk, ELK, or Datadog for centralized monitoring\n- **Vulnerability Management**: Import SARIF reports into Snyk, SonarQube, or Checkmarx\n- **Secret Management**: Integrate findings with HashiCorp Vault or AWS Secrets Manager rotation workflows\n- **Ticketing Systems**: Automated Jira/ServiceNow ticket creation for remediation tracking\n\n### SDLC Integration\n\n- **Design Phase**: Include secret detection requirements in security architecture reviews\n- **Development**: Pre-commit hooks provide immediate feedback to developers\n- **Code Review**: PR/MR checks prevent secrets from reaching main branches\n- **Testing**: Scan test environments and infrastructure-as-code\n- **Deployment**: Final validation gate before production release\n- **Operations**: Periodic scanning of deployed configurations and logs\n\n## Troubleshooting\n\n### Issue: Too Many False Positives\n\n**Symptoms**: Legitimate code patterns flagged as secrets (test fixtures, examples, placeholders)\n\n**Solution**:\n1. Review findings to identify patterns: `grep -i \"example\\|test\\|placeholder\" gitleaks-report.json`\n2. Add to allowlist in `.gitleaks.toml`:\n ```toml\n [allowlist]\n paths = ['''test/''', '''examples/''', '''\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'']\n stopwords = [\"EXAMPLE\", \"PLACEHOLDER\", \"YOUR_API_KEY_HERE\"]\n ```\n3. Use commit allowlists for specific false positives:\n ```toml\n [allowlist]\n commits = [\"commit-sha-here\"]\n ```\n4. Consult `references/false_positives.md` for common patterns\n\n### Issue: Performance Issues on Large Repositories\n\n**Symptoms**: Scans taking excessive time (>10 minutes), high memory usage\n\n**Solution**:\n1. Use `--log-opts` to limit git history: `gitleaks detect --log-opts=\"--since=2024-01-01\"`\n2. Scan specific branches: `gitleaks detect --log-opts=\"origin/main\"`\n3. Use baseline approach to scan only recent changes\n4. Consider shallow clone for initial scans: `git clone --depth=1000`\n5. Parallelize scans across multiple branches or subdirectories\n\n### Issue: Pre-commit Hook Blocking Valid Commits\n\n**Symptoms**: Developers unable to commit code with legitimate patterns\n\n**Solution**:\n1. Add inline comment to bypass hook: `# gitleaks:allow`\n2. Update `.gitleaks.toml` allowlist for the specific pattern\n3. Use `--redact` to safely review findings: `gitleaks protect --staged --redact`\n4. Temporary bypass (use with caution): `git commit --no-verify`\n5. Review with security team if pattern is genuinely needed\n\n### Issue: Secrets Found in Git History\n\n**Symptoms**: Secrets detected in old commits, already removed from current code\n\n**Solution**:\n1. Rotate compromised credentials immediately (highest priority)\n2. For public repositories, consider full history rewrite using:\n - `git filter-repo` (recommended): `git filter-repo --path-glob '*.env' --invert-paths`\n - BFG Repo-Cleaner: `bfg --delete-files credentials.json`\n3. Force-push cleaned history: `git push --force`\n4. Notify all contributors to rebase/re-clone\n5. See `references/remediation_guide.md` for detailed procedures\n6. Document incident in security audit log\n\n### Issue: Custom Secret Patterns Not Detected\n\n**Symptoms**: Organization-specific secrets not caught by default rules\n\n**Solution**:\n1. Develop regex pattern: Test at regex101.com with sample secrets\n2. Add custom rule to `.gitleaks.toml`:\n ```toml\n [[rules]]\n id = \"custom-secret-id\"\n description = \"Description\"\n regex = '''your-pattern-here'''\n secretGroup = 1 # Capture group containing actual secret\n ```\n3. Test pattern: `gitleaks detect --config .gitleaks.toml -v --no-git`\n4. Consider entropy threshold if pattern is ambiguous:\n ```toml\n [[rules.Entropies]]\n Min = \"3.5\"\n Max = \"7.0\"\n Group = \"1\"\n ```\n5. Validate with known true positives and negatives\n\n## Advanced Configuration\n\n### Entropy-Based Detection\n\nFor secrets without clear patterns, use Shannon entropy analysis:\n\n```toml\n[[rules]]\nid = \"high-entropy-strings\"\ndescription = \"High entropy strings that may be secrets\"\nregex = '''[a-zA-Z0-9]{32,}'''\nentropy = 4.5 # Shannon entropy threshold\nsecretGroup = 0\n```\n\n### Composite Rules (v8.28.0+)\n\nDetect secrets spanning multiple lines or requiring context:\n\n```toml\n[[rules]]\nid = \"multi-line-secret\"\ndescription = \"API key with usage context\"\nregex = '''api_key[\\s]*='''\n\n[[rules.composite]]\npattern = '''initialize_client'''\nlocation = \"line\" # Must be within same line proximity\ndistance = 5 # Within 5 lines\n```\n\n### Global vs Rule-Specific Allowlists\n\n```toml\n# Global allowlist (highest precedence)\n[allowlist]\ndescription = \"Organization-wide exceptions\"\npaths = ['''vendor/''', '''node_modules/''']\n\n# Rule-specific allowlist\n[[rules]]\nid = \"generic-api-key\"\n[rules.allowlist]\ndescription = \"Exceptions only for this rule\"\nregexes = ['''key\\s*=\\s*EXAMPLE''']\n```\n\n## References\n\n- [Gitleaks Official Documentation](https://github.com/gitleaks/gitleaks)\n- [OWASP A07:2021 - Identification and Authentication Failures](https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/)\n- [CWE-798: Use of Hard-coded Credentials](https://cwe.mitre.org/data/definitions/798.html)\n- [CWE-259: Use of Hard-coded Password](https://cwe.mitre.org/data/definitions/259.html)\n- [CWE-321: Use of Hard-coded Cryptographic Key](https://cwe.mitre.org/data/definitions/321.html)\n- [PCI-DSS Requirements](https://www.pcisecuritystandards.org/)\n- [SOC2 Security Criteria](https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html)\n---","attachment_filenames":["assets/config-balanced.toml","assets/config-custom.toml","assets/config-strict.toml","assets/github-action.yml","assets/gitlab-ci.yml","assets/precommit-config.yaml","references/compliance_mapping.md","references/detection_rules.md","references/EXAMPLE.md","references/false_positives.md","references/remediation_guide.md","skill-report.json"],"attachments":[{"filename":"assets/config-balanced.toml","content":"# Gitleaks Balanced Configuration\n# Production-ready configuration balancing security and developer experience\n# Use for: Most production repositories\n\ntitle = \"Gitleaks Balanced Configuration\"\n\n[extend]\n# Extend default Gitleaks rules\nuseDefault = true\n\n[allowlist]\ndescription = \"Balanced allowlist for common false positives\"\n\n# Standard non-production paths\npaths = [\n '''test/.*''',\n '''tests/.*''',\n '''.*/fixtures/.*''',\n '''.*/testdata/.*''',\n '''spec/.*''',\n '''examples?/.*''',\n '''docs?/.*''',\n '''\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''\\.rst

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''\\.txt

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''node_modules/.*''',\n '''vendor/.*''',\n '''third[_-]party/.*''',\n '''\\.min\\.js

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''\\.min\\.css

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''dist/.*''',\n '''build/.*''',\n '''target/.*''',\n '''.*/mocks?/.*''',\n]\n\n# Common placeholder patterns\nstopwords = [\n \"example\",\n \"placeholder\",\n \"your_api_key_here\",\n \"your_key_here\",\n \"your_secret_here\",\n \"replace_me\",\n \"replaceme\",\n \"changeme\",\n \"change_me\",\n \"insert_key_here\",\n \"xxxxxx\",\n \"000000\",\n \"123456\",\n \"abcdef\",\n \"sample\",\n \"dummy\",\n \"fake\",\n \"test_key\",\n \"test_secret\",\n \"test_password\",\n \"test_token\",\n \"mock\",\n \"TODO\",\n]\n\n# Public non-secrets\nregexes = [\n '''-----BEGIN CERTIFICATE-----''',\n '''-----BEGIN PUBLIC KEY-----''',\n '''data:image/[^;]+;base64,''',\n '''[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}''', # UUID\n]\n\n# Manually verified false positives (add with comments)\ncommits = []\n\n# Custom rules for organization-specific patterns can be added below\n\n# Example: Allowlist template files\n# [[rules]]\n# id = \"generic-api-key\"\n# [rules.allowlist]\n# paths = ['''config/.*\\.template

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', '''config/.*\\.example

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'']\n","content_type":"text/plain; charset=utf-8","language":"toml","size":1659,"content_sha256":"2393b2b0e7e85c92eb8a5ac5b3649ad3de8500b53c606d322fe1e57eb794930d"},{"filename":"assets/config-custom.toml","content":"# Gitleaks Custom Configuration Template\n# Use this as a starting point for organization-specific detection rules\n\ntitle = \"Custom Gitleaks Configuration\"\n\n[extend]\n# Extend default Gitleaks rules with custom rules\nuseDefault = true\n\n# =============================================================================\n# GLOBAL ALLOWLIST\n# =============================================================================\n# Global allowlists apply to ALL rules and have highest precedence\n\n[allowlist]\ndescription = \"Global allowlist for organization-wide exceptions\"\n\n# Paths to exclude from scanning\npaths = [\n # Test and documentation\n '''test/.*''',\n '''docs?/.*''',\n '''examples?/.*''',\n\n # Dependencies\n '''node_modules/.*''',\n '''vendor/.*''',\n\n # Build artifacts\n '''dist/.*''',\n '''build/.*''',\n]\n\n# Known placeholder values\nstopwords = [\n \"example\",\n \"placeholder\",\n \"your_key_here\",\n \"test\",\n \"mock\",\n \"dummy\",\n]\n\n# Public non-secrets\nregexes = [\n '''-----BEGIN CERTIFICATE-----''',\n '''-----BEGIN PUBLIC KEY-----''',\n]\n\n# Manually verified commits (add with explanatory comments)\ncommits = []\n\n# =============================================================================\n# CUSTOM DETECTION RULES\n# =============================================================================\n# Add organization-specific secret patterns here\n\n# Example: Custom API Key Pattern\n[[rules]]\nid = \"acme-corp-api-key\"\ndescription = \"ACME Corp Internal API Key\"\n# Regex pattern to match your organization's API key format\n# Use triple-quoted strings for complex patterns\nregex = '''(?i)acme[_-]?api[_-]?key[\\s]*[=:][\\s]*['\"]?([a-zA-Z0-9]{40})['\"]?'''\n# Capture group containing the actual secret (for entropy analysis)\nsecretGroup = 1\n# Tags for categorization and filtering\ntags = [\"api-key\", \"acme-internal\"]\n\n# Optional: Rule-specific allowlist (lower precedence than global)\n#[rules.allowlist]\n#paths = ['''config/defaults\\.yaml''']\n#stopwords = [\"DEFAULT_KEY\"]\n\n# Example: Custom Database Password Pattern\n[[rules]]\nid = \"acme-corp-db-password\"\ndescription = \"ACME Corp Database Password Format\"\n# Matches company-specific password format\nregex = '''(?i)(db_pass|database_password)[\\s]*[=:][\\s]*['\"]([A-Z][a-z0-9@#$%]{15,})['\"]'''\nsecretGroup = 2\ntags = [\"password\", \"database\", \"acme-internal\"]\n\n# Example: High-Entropy Detection with Custom Threshold\n[[rules]]\nid = \"high-entropy-string\"\ndescription = \"High entropy string (potential secret)\"\n# Match strings of 32+ alphanumeric characters\nregex = '''[a-zA-Z0-9+/]{32,}'''\n# Shannon entropy threshold (0.0 - 8.0, higher = more random)\nentropy = 4.5\n# Which capture group to analyze (0 = entire match)\nsecretGroup = 0\ntags = [\"entropy\", \"generic\"]\n\n[rules.allowlist]\n# Allowlist base64-encoded images\nregexes = ['''data:image/[^;]+;base64,''']\n\n# Example: Custom Service Account Key\n[[rules]]\nid = \"acme-corp-service-account\"\ndescription = \"ACME Corp Service Account JSON Key\"\n# Detect JSON structure with specific fields\nregex = '''\"type\":\\s*\"acme_service_account\"'''\ntags = [\"service-account\", \"acme-internal\"]\n\n# Example: Custom OAuth Token Format\n[[rules]]\nid = \"acme-corp-oauth-token\"\ndescription = \"ACME Corp OAuth Token\"\n# Custom token format: acme_oauth_v1_\u003c40 hex chars>\nregex = '''acme_oauth_v1_[a-f0-9]{40}'''\ntags = [\"oauth\", \"token\", \"acme-internal\"]\n\n# =============================================================================\n# TESTING CUSTOM RULES\n# =============================================================================\n# Test your custom rules with:\n# gitleaks detect --config config-custom.toml -v\n#\n# Test against specific file:\n# gitleaks detect --config config-custom.toml --source path/to/file --no-git\n#\n# Test regex pattern online:\n# https://regex101.com/ (select Golang flavor)\n#\n# =============================================================================\n\n# =============================================================================\n# ENTROPY ANALYSIS GUIDE\n# =============================================================================\n# Entropy values (Shannon entropy):\n# 0.0 - 2.5: Very low (repeated characters, simple patterns)\n# 2.5 - 3.5: Low (common words, simple sequences)\n# 3.5 - 4.5: Medium (mixed case, some randomness)\n# 4.5 - 5.5: High (strong randomness, likely secret)\n# 5.5 - 8.0: Very high (cryptographic randomness)\n#\n# Recommended thresholds:\n# - API keys: 4.5+\n# - Passwords: 3.5+\n# - Tokens: 4.5+\n# - Generic secrets: 5.0+\n# =============================================================================\n\n# =============================================================================\n# REGEX CAPTURE GROUPS\n# =============================================================================\n# Use capture groups to extract the actual secret from surrounding text:\n#\n# regex = '''api_key\\s*=\\s*\"([a-zA-Z0-9]+)\"'''\n# ^^^^^^^^^\n# Group 1\n#\n# secretGroup = 1 # Analyze only the key value, not 'api_key = \"\"'\n#\n# This improves entropy analysis accuracy and reduces false positives.\n# =============================================================================\n\n# =============================================================================\n# COMPOSITE RULES (Advanced)\n# =============================================================================\n# Gitleaks v8.28.0+ supports composite rules for context-aware detection\n# Useful for secrets that require nearby context (multi-line patterns)\n\n#[[rules]]\n#id = \"composite-api-key\"\n#description = \"API key with usage context\"\n#regex = '''api_key\\s*='''\n#\n#[[rules.composite]]\n#pattern = '''initialize_client'''\n#location = \"line\" # \"line\", \"fragment\", or \"commit\"\n#distance = 5 # Within 5 lines\n#\n# This detects api_key = \"...\" only when \"initialize_client\" appears within 5 lines\n# =============================================================================\n","content_type":"text/plain; charset=utf-8","language":"toml","size":5930,"content_sha256":"044b70c4ad746c17b843b2f850064935103c56edcc2fbdd33cb5e7671439db6c"},{"filename":"assets/config-strict.toml","content":"# Gitleaks Strict Configuration\n# High-sensitivity detection with minimal allowlisting\n# Use for: Security-critical repositories, financial services, healthcare\n\ntitle = \"Gitleaks Strict Configuration\"\n\n[extend]\n# Use all default Gitleaks rules\nuseDefault = true\n\n[allowlist]\ndescription = \"Minimal allowlist - only proven false positives\"\n\n# Only allow in build artifacts and dependencies\npaths = [\n '''node_modules/.*''',\n '''vendor/.*''',\n '''\\.min\\.js

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''\\.min\\.css

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n]\n\n# Only obvious non-secret patterns\nstopwords = [\n \"EXAMPLE_DO_NOT_USE\",\n \"PLACEHOLDER_REPLACE_ME\",\n]\n\n# All commits must be manually verified before allowlisting\ncommits = []\n\n# Additional strict rules for high-value targets\n\n[[rules]]\nid = \"strict-env-file\"\ndescription = \"Detect any .env files (should not be in repo)\"\nregex = '''.*'''\npath = '''\\.env

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

''\ntags = [\"env-file\", \"strict\"]\n\n[[rules]]\nid = \"strict-config-secrets\"\ndescription = \"Config files with potential secrets\"\nregex = '''(?i)(password|secret|key|token|credential)[\\s]*[=:][\\s]*['\"]?([a-zA-Z0-9!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.\u003c>\\/?]{8,})['\"]?'''\nsecretGroup = 2\ntags = [\"config\", \"strict\"]\n[rules.allowlist]\npaths = ['''test/.*''']\nstopwords = [\"EXAMPLE\"]\n","content_type":"text/plain; charset=utf-8","language":"toml","size":1213,"content_sha256":"a90e31fb17e16612006e3ea81edc1db354c78f4e06341f61b0ad48e7a3405758"},{"filename":"assets/github-action.yml","content":"# GitHub Actions Workflow for Gitleaks Secret Scanning\n# Save as: .github/workflows/gitleaks.yml\n\nname: Secret Scanning with Gitleaks\n\non:\n push:\n branches:\n - main\n - develop\n - 'release/**'\n pull_request:\n branches:\n - main\n - develop\n schedule:\n # Run daily at 2 AM UTC\n - cron: '0 2 * * *'\n workflow_dispatch: # Allow manual triggers\n\n# Cancel in-progress runs when new commit pushed\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n gitleaks-scan:\n name: Scan for Secrets\n runs-on: ubuntu-latest\n\n permissions:\n # Required for uploading SARIF results to GitHub Security tab\n security-events: write\n # Required for checking out private repos\n contents: read\n\n steps:\n - name: Checkout Repository\n uses: actions/checkout@v4\n with:\n # Fetch full history for comprehensive scanning\n fetch-depth: 0\n\n - name: Run Gitleaks Scan\n id: gitleaks\n uses: gitleaks/gitleaks-action@v2\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n # Optional: Use custom configuration\n # GITLEAKS_CONFIG: .gitleaks.toml\n\n # Optional: Generate JSON report for further processing\n - name: Generate JSON Report\n if: always() # Run even if secrets found\n run: |\n docker run --rm -v ${{ github.workspace }}:/repo \\\n zricethezav/gitleaks:latest \\\n detect --source /repo \\\n --report-path /repo/gitleaks-report.json \\\n --report-format json \\\n --exit-code 0 || true\n\n # Optional: Upload JSON report as artifact\n - name: Upload Scan Report\n if: always()\n uses: actions/upload-artifact@v4\n with:\n name: gitleaks-report\n path: gitleaks-report.json\n retention-days: 30\n\n # Optional: Generate SARIF report for GitHub Security tab\n - name: Generate SARIF Report\n if: always()\n run: |\n docker run --rm -v ${{ github.workspace }}:/repo \\\n zricethezav/gitleaks:latest \\\n detect --source /repo \\\n --report-path /repo/gitleaks.sarif \\\n --report-format sarif \\\n --exit-code 0 || true\n\n # Optional: Upload SARIF report to GitHub Security\n - name: Upload SARIF to GitHub Security\n if: always()\n uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: gitleaks.sarif\n category: gitleaks\n\n # Optional: Comment on PR with findings\n - name: Comment PR with Findings\n if: failure() && github.event_name == 'pull_request'\n uses: actions/github-script@v7\n with:\n script: |\n const fs = require('fs');\n try {\n const report = JSON.parse(fs.readFileSync('gitleaks-report.json', 'utf8'));\n const findings = report.length;\n\n const comment = `## 🔒 Secret Scanning Results\n\n ⚠️ **${findings} potential secret(s) detected!**\n\n Please review the findings and take immediate action:\n 1. **Do not merge** this PR until secrets are removed\n 2. Rotate any exposed credentials immediately\n 3. Remove secrets from code and use environment variables\n 4. Review the security tab for detailed findings\n\n See [Secret Scanning Guide](https://github.com/${{ github.repository }}/blob/main/docs/secret-scanning.md) for remediation steps.`;\n\n github.rest.issues.createComment({\n issue_number: context.issue.number,\n owner: context.repo.owner,\n repo: context.repo.repo,\n body: comment\n });\n } catch (error) {\n console.log('No report file or error reading it:', error.message);\n }\n\n # Optional: Post to Slack on failure\n - name: Notify Slack on Failure\n if: failure()\n uses: slackapi/slack-github-action@v1\n with:\n payload: |\n {\n \"text\": \"🚨 Secrets detected in ${{ github.repository }}\",\n \"blocks\": [\n {\n \"type\": \"section\",\n \"text\": {\n \"type\": \"mrkdwn\",\n \"text\": \"*Secret Scanning Alert*\\n\\nSecrets detected in repository: `${{ github.repository }}`\\nBranch: `${{ github.ref_name }}`\\nCommit: `${{ github.sha }}`\\n\\n\u003c${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Details>\"\n }\n }\n ]\n }\n env:\n SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}\n SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK\n\n # Optional: Baseline scanning for incremental detection\n baseline-scan:\n name: Incremental Scan Against Baseline\n runs-on: ubuntu-latest\n if: github.event_name == 'push'\n\n steps:\n - name: Checkout Repository\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Download Existing Baseline\n continue-on-error: true\n run: |\n # Download baseline from artifact storage or S3\n # Example: aws s3 cp s3://bucket/.gitleaks-baseline.json .\n echo \"Baseline download would go here\"\n\n - name: Run Incremental Scan\n run: |\n docker run --rm -v ${{ github.workspace }}:/repo \\\n zricethezav/gitleaks:latest \\\n detect --source /repo \\\n --baseline-path /repo/.gitleaks-baseline.json \\\n --report-path /repo/new-findings.json \\\n --report-format json \\\n --exit-code 1 || true\n\n - name: Upload New Findings\n if: always()\n uses: actions/upload-artifact@v4\n with:\n name: new-findings\n path: new-findings.json\n retention-days: 90\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":5960,"content_sha256":"cdf3ffb6245b1bd7e7bb677dff7894d75968cf4013c05de001505ec0496873a5"},{"filename":"assets/gitlab-ci.yml","content":"# GitLab CI Pipeline for Gitleaks Secret Scanning\n# Save as: .gitlab-ci.yml or include in existing pipeline\n\n# Define stages\nstages:\n - security\n - report\n\n# Default Docker image for security jobs\nimage: docker:latest\n\nservices:\n - docker:dind\n\nvariables:\n # Gitleaks Docker image\n GITLEAKS_IMAGE: zricethezav/gitleaks:latest\n # Report output path\n REPORT_PATH: gitleaks-report.json\n # SARIF output for GitLab Security Dashboard\n SARIF_PATH: gl-secret-detection-report.json\n\n# Secret scanning job\ngitleaks-scan:\n stage: security\n image: $GITLEAKS_IMAGE\n\n # Run on all branches and merge requests\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'\n - if: '$CI_COMMIT_BRANCH =~ /^(develop|release)/'\n\n script:\n # Run Gitleaks scan\n - echo \"Running Gitleaks secret detection...\"\n - |\n gitleaks detect \\\n --source . \\\n --report-path $REPORT_PATH \\\n --report-format json \\\n --verbose || true\n\n # Convert to GitLab SARIF format for Security Dashboard\n - |\n gitleaks detect \\\n --source . \\\n --report-path $SARIF_PATH \\\n --report-format sarif \\\n --verbose || true\n\n # Check if secrets were found\n - |\n if [ -s \"$REPORT_PATH\" ] && [ \"$(cat $REPORT_PATH)\" != \"null\" ]; then\n echo \"⚠️ Secrets detected! Review findings below.\"\n cat $REPORT_PATH | jq -r '.[] | \"File: \\(.File)\\nLine: \\(.StartLine)\\nRule: \\(.RuleID)\\n\"'\n exit 1\n else\n echo \"✅ No secrets detected\"\n fi\n\n artifacts:\n paths:\n - $REPORT_PATH\n - $SARIF_PATH\n reports:\n # GitLab Security Dashboard integration\n secret_detection: $SARIF_PATH\n when: always\n expire_in: 30 days\n\n # Allow failure for initial rollout, then set to false\n allow_failure: false\n\n# Optional: Incremental scanning with baseline\ngitleaks-incremental:\n stage: security\n image: $GITLEAKS_IMAGE\n\n # Only run on merge requests\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n\n script:\n # Download baseline from artifacts or storage\n - echo \"Downloading baseline...\"\n - |\n if [ -f \".gitleaks-baseline.json\" ]; then\n echo \"Using baseline from repository\"\n else\n echo \"No baseline found, running full scan\"\n fi\n\n # Run incremental scan\n - |\n if [ -f \".gitleaks-baseline.json\" ]; then\n gitleaks detect \\\n --source . \\\n --baseline-path .gitleaks-baseline.json \\\n --report-path new-findings.json \\\n --report-format json \\\n --exit-code 1 || true\n\n if [ -s \"new-findings.json\" ] && [ \"$(cat new-findings.json)\" != \"null\" ]; then\n echo \"⚠️ New secrets detected since baseline!\"\n cat new-findings.json | jq .\n exit 1\n fi\n fi\n\n artifacts:\n paths:\n - new-findings.json\n when: always\n expire_in: 7 days\n\n# Optional: Create baseline on main branch\ncreate-baseline:\n stage: security\n image: $GITLEAKS_IMAGE\n\n # Only run on main/master branch\n rules:\n - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'\n when: manual # Manual trigger to avoid overwriting\n\n script:\n - echo \"Creating new baseline...\"\n - |\n gitleaks detect \\\n --source . \\\n --report-path .gitleaks-baseline.json \\\n --report-format json \\\n --exit-code 0 || true\n\n artifacts:\n paths:\n - .gitleaks-baseline.json\n expire_in: 365 days\n\n# Optional: Generate human-readable report\ngenerate-report:\n stage: report\n image: python:3.11-slim\n\n dependencies:\n - gitleaks-scan\n\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'\n\n script:\n - pip install jinja2\n - |\n python3 \u003c\u003c 'EOF'\n import json\n import sys\n from datetime import datetime\n\n try:\n with open('gitleaks-report.json', 'r') as f:\n findings = json.load(f)\n\n if not findings:\n print(\"✅ No secrets detected\")\n sys.exit(0)\n\n print(\"# Gitleaks Secret Detection Report\")\n print(f\"\\n**Generated**: {datetime.now().isoformat()}\")\n print(f\"**Total Findings**: {len(findings)}\\n\")\n\n for idx, finding in enumerate(findings, 1):\n print(f\"\\n## Finding {idx}\")\n print(f\"- **File**: {finding.get('File', 'unknown')}\")\n print(f\"- **Line**: {finding.get('StartLine', 'unknown')}\")\n print(f\"- **Rule**: {finding.get('RuleID', 'unknown')}\")\n print(f\"- **Description**: {finding.get('Description', 'unknown')}\")\n print(f\"- **Commit**: {finding.get('Commit', 'N/A')}\\n\")\n\n except FileNotFoundError:\n print(\"No report file found\")\n except json.JSONDecodeError:\n print(\"No findings in report\")\n EOF\n\n artifacts:\n paths:\n - gitleaks-report.json\n\n# Optional: Comment on merge request\ncomment-mr:\n stage: report\n image: alpine:latest\n\n dependencies:\n - gitleaks-scan\n\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n\n before_script:\n - apk add --no-cache curl jq\n\n script:\n - |\n if [ -s \"$REPORT_PATH\" ] && [ \"$(cat $REPORT_PATH)\" != \"null\" ]; then\n FINDING_COUNT=$(cat $REPORT_PATH | jq '. | length')\n\n COMMENT=\"## 🔒 Secret Scanning Results\\n\\n\"\n COMMENT=\"${COMMENT}⚠️ **${FINDING_COUNT} potential secret(s) detected!**\\n\\n\"\n COMMENT=\"${COMMENT}Please review the findings and take immediate action:\\n\"\n COMMENT=\"${COMMENT}1. **Do not merge** this MR until secrets are removed\\n\"\n COMMENT=\"${COMMENT}2. Rotate any exposed credentials immediately\\n\"\n COMMENT=\"${COMMENT}3. Remove secrets from code and use CI/CD variables\\n\\n\"\n COMMENT=\"${COMMENT}See pipeline artifacts for detailed findings.\"\n\n # Post comment to merge request\n curl --request POST \\\n --header \"PRIVATE-TOKEN: $GITLAB_TOKEN\" \\\n --data-urlencode \"body=$COMMENT\" \\\n \"$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes\"\n fi\n\n allow_failure: true\n\n# Optional: Scheduled nightly scan\nnightly-scan:\n stage: security\n image: $GITLEAKS_IMAGE\n\n # Run on schedule only\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"schedule\"'\n\n script:\n - echo \"Running comprehensive nightly secret scan...\"\n - |\n gitleaks detect \\\n --source . \\\n --report-path nightly-scan.json \\\n --report-format json \\\n --verbose\n\n artifacts:\n paths:\n - nightly-scan.json\n when: always\n expire_in: 90 days\n\n # Send notifications on failure\n after_script:\n - |\n if [ $? -ne 0 ]; then\n echo \"Secrets detected in nightly scan!\"\n # Add notification logic (email, Slack, etc.)\n fi\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":6881,"content_sha256":"7168ecb3a89abf16eae9ac7085da3c3c145fb722d9a2995b245e2cd7e1bb1d38"},{"filename":"assets/precommit-config.yaml","content":"# Pre-commit Framework Configuration for Gitleaks\n# Install pre-commit: pip install pre-commit\n# Install hooks: pre-commit install\n# Run manually: pre-commit run --all-files\n#\n# More info: https://pre-commit.com/\n\nrepos:\n - repo: https://github.com/gitleaks/gitleaks\n rev: v8.18.0 # Update to latest version: https://github.com/gitleaks/gitleaks/releases\n hooks:\n - id: gitleaks\n name: Gitleaks - Secret Detection\n description: Scan staged changes for hardcoded secrets\n entry: gitleaks protect --verbose --redact --staged\n language: system\n pass_filenames: false\n # Optional: Custom configuration\n # args: ['--config', '.gitleaks.toml']\n\n # Optional: Additional security hooks\n\n # Detect private keys\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: detect-private-key\n name: Detect Private Keys\n\n # Check for AWS credentials\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: detect-aws-credentials\n name: Detect AWS Credentials\n args: ['--allow-missing-credentials']\n\n # Prevent large files (may contain secrets)\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: check-added-large-files\n name: Check for Large Files\n args: ['--maxkb=1000']\n\n # Check for merge conflicts\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: check-merge-conflict\n name: Check for Merge Conflicts\n\n # Ensure files end with newline\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: end-of-file-fixer\n name: Fix End of Files\n\n # Trim trailing whitespace\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.5.0\n hooks:\n - id: trailing-whitespace\n name: Trim Trailing Whitespace\n\n# Configuration for pre-commit.ci (optional CI service)\nci:\n autofix_prs: false\n autoupdate_schedule: monthly\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":2048,"content_sha256":"b80493323fdb8db8c8d581307884e7633fbf31ae3c6ef7f7428928c5e3b6a254"},{"filename":"references/compliance_mapping.md","content":"# Compliance Framework Mapping\n\nDetailed mapping of Gitleaks secret detection to compliance and security frameworks.\n\n## Table of Contents\n\n- [OWASP Top 10](#owasp-top-10)\n- [CWE (Common Weakness Enumeration)](#cwe-common-weakness-enumeration)\n- [PCI-DSS](#pci-dss)\n- [SOC 2](#soc-2)\n- [GDPR](#gdpr)\n- [NIST Cybersecurity Framework](#nist-cybersecurity-framework)\n- [ISO 27001](#iso-27001)\n- [HIPAA](#hipaa)\n- [Compliance Reporting](#compliance-reporting)\n\n## OWASP Top 10\n\n### A07:2021 – Identification and Authentication Failures\n\n**Relevance**: Hardcoded credentials lead to authentication bypass and unauthorized access.\n\n**Gitleaks Coverage**:\n- Detects hardcoded passwords, API keys, tokens\n- Identifies database connection strings with embedded credentials\n- Finds SSH keys, certificates, and cryptographic secrets\n\n**Control Implementation**:\n```yaml\n# CI/CD check to prevent authentication failures\nname: OWASP A07 - Authentication Control\non: [push, pull_request]\njobs:\n secrets-scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - name: Scan for hardcoded credentials (OWASP A07)\n uses: gitleaks/gitleaks-action@v2\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n**Evidence for Auditors**:\n- Gitleaks scan reports (JSON/SARIF format)\n- CI/CD pipeline logs showing regular scans\n- Pre-commit hook installation across developer workstations\n- Remediation tracking for detected secrets\n\n### A01:2021 – Broken Access Control\n\n**Relevance**: Exposed API keys and tokens can bypass access control mechanisms.\n\n**Gitleaks Coverage**:\n- Cloud provider credentials (AWS, GCP, Azure)\n- Service account keys and OAuth tokens\n- Administrative API keys\n\n**Control Implementation**:\n- Implement secret scanning before deployment\n- Rotate credentials when exposure detected\n- Review cloud provider audit logs for unauthorized access\n\n### A02:2021 – Cryptographic Failures\n\n**Relevance**: Hardcoded cryptographic keys compromise encryption.\n\n**Gitleaks Coverage**:\n- Private keys (RSA, DSA, EC)\n- JWT signing secrets\n- Encryption keys in configuration files\n\n**Evidence**:\n- Detection rules for CWE-321 (Use of Hard-coded Cryptographic Key)\n- Remediation procedures for exposed cryptographic material\n\n## CWE (Common Weakness Enumeration)\n\n### CWE-798: Use of Hard-coded Credentials\n\n**Description**: Software contains hard-coded credentials (e.g., password, cryptographic key).\n\n**CVSS Base Score**: Typically 7.5 - 9.8 (High to Critical)\n\n**Gitleaks Detection**:\n- All API key rules\n- Database connection strings\n- Service account credentials\n- Generic password patterns\n\n**Remediation Mapping**:\n```toml\n# Tag all findings with CWE-798\n[[rules]]\nid = \"generic-api-key\"\ndescription = \"Generic API Key (CWE-798)\"\nregex = '''(?i)api_key\\s*=\\s*[\"']([a-zA-Z0-9]{32,})[\"']'''\ntags = [\"api-key\", \"CWE-798\"]\n```\n\n### CWE-259: Use of Hard-coded Password\n\n**Description**: Software contains hard-coded password.\n\n**Gitleaks Detection**:\n- Password variables in code\n- Database connection strings with passwords\n- Configuration files with password fields\n\n**Example Finding**:\n```json\n{\n \"RuleID\": \"generic-password\",\n \"Description\": \"Hard-coded password detected\",\n \"File\": \"config/database.py\",\n \"Line\": 42,\n \"CWE\": \"CWE-259\"\n}\n```\n\n### CWE-321: Use of Hard-coded Cryptographic Key\n\n**Description**: Use of hard-coded cryptographic key in product.\n\n**Gitleaks Detection**:\n- Private key files (PEM format)\n- JWT signing secrets\n- Encryption keys in source code\n\n### CWE-522: Insufficiently Protected Credentials\n\n**Description**: Product transmits or stores authentication credentials in insufficiently protected form.\n\n**Gitleaks Coverage**: Detects credentials stored in source code (inadequate protection).\n\n### CWE-257: Storing Passwords in a Recoverable Format\n\n**Description**: Storing passwords in a recoverable format makes them vulnerable.\n\n**Gitleaks Coverage**: Identifies plaintext passwords in configuration and code.\n\n## PCI-DSS\n\n### Requirement 6.5.3: Insecure Cryptographic Storage\n\n**Control Objective**: Protect stored cardholder data.\n\n**Gitleaks Implementation**:\n- Scan payment processing code for embedded API keys (Stripe, PayPal, etc.)\n- Detect hardcoded encryption keys\n- Identify database credentials used for cardholder data access\n\n**Compliance Evidence**:\n```bash\n# Generate PCI-DSS compliance report\ngitleaks detect \\\n --source ./payment-processing \\\n --report-format json \\\n --report-path pci-compliance-scan.json\n\n# Extract payment-related findings\njq '.[] | select(.Tags[] | contains(\"payment\"))' pci-compliance-scan.json\n```\n\n### Requirement 8.2.1: Strong Cryptography for Authentication\n\n**Control Objective**: Use strong authentication credentials.\n\n**Gitleaks Implementation**:\n- Detect weak/hardcoded authentication tokens\n- Identify test credentials in production code paths\n\n### Requirement 10.2: Logging and Monitoring\n\n**Control Objective**: Implement automated audit trails.\n\n**Gitleaks Implementation**:\n```python\n# Log all secret detection events\nimport logging\nimport json\n\nwith open('gitleaks-findings.json', 'r') as f:\n findings = json.load(f)\n\nfor finding in findings:\n logging.warning(\n f\"PCI-DSS Violation: Hardcoded credential detected\",\n extra={\n \"rule\": finding[\"RuleID\"],\n \"file\": finding[\"File\"],\n \"line\": finding[\"StartLine\"],\n \"compliance_requirement\": \"PCI-DSS 6.5.3\"\n }\n )\n```\n\n### PCI-DSS Reporting Template\n\n```markdown\n# PCI-DSS Requirement 6.5.3 - Secret Scanning Report\n\n**Reporting Period**: Q1 2024\n**Scan Date**: 2024-01-15\n**Scope**: All repositories handling cardholder data\n\n## Summary\n- **Repositories Scanned**: 15\n- **Secrets Detected**: 3\n- **Remediation Status**: All resolved within 24 hours\n\n## Findings\n\n| Finding ID | Rule | Severity | File | Status | Remediation Date |\n|------------|------|----------|------|--------|------------------|\n| F001 | stripe-api-key | CRITICAL | payment/config.py | Resolved | 2024-01-15 |\n| F002 | database-password | HIGH | db/setup.sql | Resolved | 2024-01-15 |\n| F003 | aws-access-key | HIGH | deploy/config.yml | Resolved | 2024-01-16 |\n\n## Control Effectiveness\n✅ Automated secret scanning implemented\n✅ All findings remediated within SLA\n✅ Pre-commit hooks prevent new violations\n```\n\n## SOC 2\n\n### CC6.1: Logical and Physical Access Controls\n\n**Control Activity**: Implement controls to prevent unauthorized access to system resources.\n\n**Gitleaks Implementation**:\n- Automated detection of exposed credentials\n- Pre-commit hooks to prevent credential commits\n- CI/CD gates blocking deployments with secrets\n\n**SOC 2 Evidence Package**:\n1. Secret scanning policy and procedures\n2. Gitleaks configuration file (`.gitleaks.toml`)\n3. CI/CD pipeline configurations\n4. Scan execution logs (last 12 months)\n5. Remediation tracking (issue tickets)\n6. Training materials for developers\n\n### CC6.6: Logical Access - Provisioning\n\n**Control Activity**: Provision access based on role, revoke when no longer needed.\n\n**Gitleaks Implementation**:\n- Detection of service account keys and tokens\n- Audit trail of credential exposure and rotation\n- Automated revocation workflows\n\n### CC7.2: System Monitoring\n\n**Control Activity**: Monitor system for security events and anomalies.\n\n**Gitleaks Implementation**:\n```yaml\n# Continuous monitoring workflow\nname: SOC2 CC7.2 - Security Monitoring\non:\n schedule:\n - cron: '0 2 * * *' # Daily at 2 AM\njobs:\n security-scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - name: Secret Detection Scan\n uses: gitleaks/gitleaks-action@v2\n - name: Report to SIEM\n run: |\n curl -X POST https://siem.company.com/api/events \\\n -H \"Content-Type: application/json\" \\\n -d @gitleaks-report.json\n```\n\n### SOC 2 Audit Response Template\n\n```markdown\n# SOC 2 Control CC6.1 - Secret Scanning Control\n\n**Control Description**: Automated secret scanning prevents unauthorized access through exposed credentials.\n\n**Control Design**:\n1. Pre-commit hooks block credential commits at developer workstation\n2. CI/CD pipeline scans all pull requests before merge\n3. Nightly scans of all production repositories\n4. Automated alerting to security team for violations\n\n**Control Operating Effectiveness**:\n- **Frequency**: Continuous (pre-commit) + Daily (scheduled scans)\n- **Population**: 247 repositories, 85 developers\n- **Sample Period**: January 1 - December 31, 2024\n- **Samples Tested**: 52 weekly scan reports\n- **Exceptions**: 0\n\n**Evidence of Operation**:\n- Attached: gitleaks-audit-log-2024.json\n- Attached: remediation-tracking.csv\n- Attached: developer-training-records.pdf\n```\n\n## GDPR\n\n### Article 32: Security of Processing\n\n**Requirement**: Implement appropriate technical measures to ensure security of personal data.\n\n**Gitleaks Implementation**:\n- Detect API keys for services processing personal data\n- Identify database credentials for systems storing personal data\n- Scan for OAuth tokens with user data access scopes\n\n**GDPR Compliance Mapping**:\n\n| GDPR Requirement | Gitleaks Control | Evidence |\n|------------------|------------------|----------|\n| Art. 32(1)(a) - Pseudonymization | Detect database credentials protecting personal data | Scan reports |\n| Art. 32(1)(b) - Confidentiality | Prevent credential exposure in source code | Pre-commit hooks |\n| Art. 32(2) - Risk Assessment | Regular security scanning | Scan schedules |\n| Art. 33 - Breach Notification | Detection triggers incident response | Alert logs |\n\n### Data Breach Notification\n\nIf Gitleaks detects exposed credentials accessing personal data:\n\n```bash\n#!/bin/bash\n# gdpr-incident-response.sh\n\n# Assess if personal data is at risk\necho \"1. Identify data accessed by exposed credential\"\necho \"2. Determine if data is personal data under GDPR\"\necho \"3. Assess likelihood of unauthorized access\"\n\n# 72-hour notification requirement\necho \"If personal data breach confirmed:\"\necho \"- Notify supervisory authority within 72 hours\"\necho \"- Document: nature of breach, data categories affected, likely consequences, measures taken\"\n```\n\n## NIST Cybersecurity Framework\n\n### Identify (ID.AM): Asset Management\n\n**Subcategory**: ID.AM-2 - Software platforms and applications are inventoried.\n\n**Gitleaks Implementation**: Catalog all repositories with secret scanning coverage.\n\n### Protect (PR.AC): Access Control\n\n**Subcategory**: PR.AC-1 - Identities and credentials are managed.\n\n**Gitleaks Implementation**:\n- Automated detection of exposed credentials\n- Credential lifecycle management (rotation after exposure)\n\n### Detect (DE.CM): Security Continuous Monitoring\n\n**Subcategory**: DE.CM-4 - Malicious code is detected.\n\n**Gitleaks Implementation**: Secrets considered \"malicious\" when hardcoded.\n\n### Respond (RS.AN): Analysis\n\n**Subcategory**: RS.AN-1 - Notifications are investigated.\n\n**Gitleaks Implementation**: Alert triage and investigation procedures.\n\n### Recover (RC.RP): Recovery Planning\n\n**Subcategory**: RC.RP-1 - Recovery plan is executed during or after an event.\n\n**Gitleaks Implementation**: Credential rotation and git history cleanup procedures.\n\n## ISO 27001\n\n### A.9.2.4: Management of Secret Authentication Information\n\n**Control**: Allocation of secret authentication information shall be controlled through a formal management process.\n\n**Gitleaks Implementation**:\n- Detect deviations from secret management process (hardcoded secrets)\n- Enforce secret management policy through pre-commit hooks\n\n### A.9.4.3: Password Management System\n\n**Control**: Password management systems shall be interactive and ensure quality passwords.\n\n**Gitleaks Implementation**: Prevent password hardcoding in source code.\n\n### A.12.6.1: Management of Technical Vulnerabilities\n\n**Control**: Obtain information about technical vulnerabilities and take appropriate measures.\n\n**Gitleaks Implementation**: Continuous vulnerability scanning for credential exposure.\n\n## HIPAA\n\n### § 164.312(a)(1): Access Control\n\n**Standard**: Implement technical policies to allow only authorized access to ePHI.\n\n**Gitleaks Implementation**:\n- Detect credentials for systems accessing ePHI\n- Prevent unauthorized access through exposed credentials\n\n### § 164.308(a)(1)(ii)(D): Information System Activity Review\n\n**Standard**: Implement procedures to regularly review records of information system activity.\n\n**Gitleaks Implementation**:\n```bash\n# Weekly HIPAA compliance review\ngitleaks detect \\\n --source ./healthcare-systems \\\n --report-format json \\\n > hipaa-weekly-scan.json\n\n# Review findings for ePHI access credentials\njq '.[] | select(.Tags[] | contains(\"database\") or contains(\"api-key\"))' \\\n hipaa-weekly-scan.json\n```\n\n### § 164.312(b): Audit Controls\n\n**Standard**: Implement hardware, software, procedures to record and examine system activity.\n\n**Gitleaks Implementation**: Audit trail of secret detection events.\n\n## Compliance Reporting\n\n### Automated Compliance Report Generation\n\n```python\n#!/usr/bin/env python3\n\"\"\"Generate compliance report from Gitleaks findings.\"\"\"\n\nimport json\nimport sys\nfrom datetime import datetime\n\n# Compliance framework mappings\nCOMPLIANCE_MAPPINGS = {\n \"CWE-798\": [\"OWASP-A07\", \"PCI-DSS-6.5.3\", \"SOC2-CC6.1\", \"ISO27001-A.9.2.4\"],\n \"CWE-259\": [\"OWASP-A07\", \"PCI-DSS-8.2.1\", \"SOC2-CC6.1\", \"ISO27001-A.9.4.3\"],\n \"CWE-321\": [\"OWASP-A02\", \"PCI-DSS-6.5.3\", \"ISO27001-A.12.3.1\"],\n}\n\ndef generate_compliance_report(findings_file, framework):\n \"\"\"Generate compliance-specific report.\"\"\"\n\n with open(findings_file, 'r') as f:\n findings = json.load(f)\n\n # Filter findings relevant to framework\n relevant_findings = []\n for finding in findings:\n cwe = finding.get(\"CWE\", \"\")\n if framework in COMPLIANCE_MAPPINGS.get(cwe, []):\n relevant_findings.append(finding)\n\n # Generate report\n report = {\n \"framework\": framework,\n \"generated\": datetime.now().isoformat(),\n \"total_findings\": len(relevant_findings),\n \"findings\": relevant_findings,\n \"compliance_status\": \"NON-COMPLIANT\" if relevant_findings else \"COMPLIANT\"\n }\n\n return report\n\nif __name__ == \"__main__\":\n if len(sys.argv) != 3:\n print(\"Usage: compliance_report.py \u003cfindings.json> \u003cframework>\")\n print(\"Frameworks: OWASP, PCI-DSS, SOC2, ISO27001, GDPR, HIPAA\")\n sys.exit(1)\n\n report = generate_compliance_report(sys.argv[1], sys.argv[2])\n print(json.dumps(report, indent=2))\n```\n\n### Usage\n\n```bash\n# Generate PCI-DSS specific report\n./compliance_report.py gitleaks-findings.json PCI-DSS > pci-dss-report.json\n\n# Generate SOC2 specific report\n./compliance_report.py gitleaks-findings.json SOC2 > soc2-report.json\n```\n\n### Compliance Dashboard Metrics\n\nTrack these KPIs for compliance reporting:\n\n```yaml\nmetrics:\n - name: \"Secret Detection Coverage\"\n description: \"Percentage of repositories with secret scanning enabled\"\n target: 100%\n\n - name: \"Mean Time to Remediation (MTTR)\"\n description: \"Average time from detection to credential rotation\"\n target: \u003c 4 hours\n\n - name: \"False Positive Rate\"\n description: \"Percentage of findings classified as false positives\"\n target: \u003c 10%\n\n - name: \"Pre-commit Hook Adoption\"\n description: \"Percentage of developers with hooks installed\"\n target: > 95%\n\n - name: \"Scan Frequency\"\n description: \"Scans per repository per month\"\n target: > 30 (daily)\n```\n\n## Audit Preparation Checklist\n\n- [ ] Configure Gitleaks across all in-scope repositories\n- [ ] Implement CI/CD secret scanning gates\n- [ ] Deploy pre-commit hooks to developer workstations\n- [ ] Establish remediation procedures and SLAs\n- [ ] Create audit trail (scan logs, remediation tickets)\n- [ ] Generate compliance-specific reports\n- [ ] Document control design and operating effectiveness\n- [ ] Prepare evidence package for auditors\n- [ ] Train team on secret management policies\n- [ ] Schedule regular compliance reviews\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":16108,"content_sha256":"44c6a7ae5adfd7f61576584062f3d14121b9fa36a26e1f5ce4005a4278639394"},{"filename":"references/detection_rules.md","content":"# Gitleaks Detection Rules Reference\n\nComprehensive reference of built-in Gitleaks detection rules with CWE mappings and remediation guidance.\n\n## Table of Contents\n\n- [Cloud Provider Credentials](#cloud-provider-credentials)\n- [Version Control Systems](#version-control-systems)\n- [API Keys and Tokens](#api-keys-and-tokens)\n- [Database Credentials](#database-credentials)\n- [Private Keys](#private-keys)\n- [Generic Patterns](#generic-patterns)\n\n## Cloud Provider Credentials\n\n### AWS Access Key ID\n- **Rule ID**: `aws-access-token`\n- **Pattern**: `AKIA[0-9A-Z]{16}`\n- **CWE**: CWE-798 (Use of Hard-coded Credentials)\n- **Severity**: HIGH\n- **Description**: AWS Access Key ID for programmatic access\n- **Remediation**: Rotate via AWS IAM console, use AWS Secrets Manager or IAM roles\n\n### AWS Secret Access Key\n- **Rule ID**: `aws-secret-key`\n- **Pattern**: `(?i)aws(.{0,20})?[\\'\\\"][0-9a-zA-Z\\/+]{40}[\\'\\\"]`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL\n- **Description**: AWS Secret Access Key paired with Access Key ID\n- **Remediation**: Immediate rotation required, review CloudTrail logs for unauthorized access\n\n### GCP API Key\n- **Rule ID**: `gcp-api-key`\n- **Pattern**: `AIza[0-9A-Za-z\\\\-_]{35}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Google Cloud Platform API key\n- **Remediation**: Delete and regenerate in GCP Console, review API usage logs\n\n### GCP Service Account\n- **Rule ID**: `gcp-service-account`\n- **Pattern**: `\\\"type\\\": \\\"service_account\\\"`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL\n- **Description**: GCP service account JSON key file\n- **Remediation**: Delete service account key, use Workload Identity where possible\n\n### Azure Storage Account Key\n- **Rule ID**: `azure-storage-key`\n- **Pattern**: `(?i)azure.*[\\'\\\"][0-9a-zA-Z\\/+]{88}[\\'\\\"]`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL\n- **Description**: Azure Storage Account access key\n- **Remediation**: Regenerate keys in Azure Portal, use Azure Key Vault\n\n### Digital Ocean Token\n- **Rule ID**: `digitalocean-token`\n- **Pattern**: `dop_v1_[a-f0-9]{64}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Digital Ocean personal access token\n- **Remediation**: Revoke token in Digital Ocean console, create new token\n\n## Version Control Systems\n\n### GitHub Personal Access Token\n- **Rule ID**: `github-pat`\n- **Pattern**: `ghp_[0-9a-zA-Z]{36}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: GitHub personal access token (classic)\n- **Remediation**: Revoke in GitHub Settings > Developer settings, review audit log\n\n### GitHub OAuth Token\n- **Rule ID**: `github-oauth`\n- **Pattern**: `gho_[0-9a-zA-Z]{36}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: GitHub OAuth access token\n- **Remediation**: Revoke OAuth app authorization, regenerate token\n\n### GitHub Fine-Grained Token\n- **Rule ID**: `github-fine-grained-pat`\n- **Pattern**: `github_pat_[0-9a-zA-Z]{22}_[0-9a-zA-Z]{59}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: GitHub fine-grained personal access token\n- **Remediation**: Revoke in GitHub Settings, review resource access scope\n\n### GitLab Personal Access Token\n- **Rule ID**: `gitlab-pat`\n- **Pattern**: `glpat-[0-9a-zA-Z\\\\-_]{20}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: GitLab personal access token\n- **Remediation**: Revoke in GitLab User Settings > Access Tokens\n\n### Bitbucket App Password\n- **Rule ID**: `bitbucket-app-password`\n- **Pattern**: `(?i)bitbucket.*[\\'\\\"][0-9a-zA-Z]{16}[\\'\\\"]`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Bitbucket app-specific password\n- **Remediation**: Revoke in Bitbucket Personal Settings > App passwords\n\n## API Keys and Tokens\n\n### Stripe API Key\n- **Rule ID**: `stripe-api-key`\n- **Pattern**: `(?i)(sk|pk)_(test|live)_[0-9a-zA-Z]{24,}`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL (live), HIGH (test)\n- **Description**: Stripe API secret or publishable key\n- **Remediation**: Roll keys in Stripe Dashboard, review payment transactions\n\n### Twilio API Key\n- **Rule ID**: `twilio-api-key`\n- **Pattern**: `SK[0-9a-fA-F]{32}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Twilio API key\n- **Remediation**: Delete key in Twilio Console, create new key\n\n### SendGrid API Key\n- **Rule ID**: `sendgrid-api-key`\n- **Pattern**: `SG\\\\.[0-9A-Za-z\\\\-_]{22}\\\\.[0-9A-Za-z\\\\-_]{43}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: SendGrid API key\n- **Remediation**: Delete in SendGrid Settings > API Keys, update applications\n\n### Slack Token\n- **Rule ID**: `slack-token`\n- **Pattern**: `xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Slack bot, app, or user token\n- **Remediation**: Regenerate in Slack App Settings, rotate token\n\n### Slack Webhook\n- **Rule ID**: `slack-webhook`\n- **Pattern**: `https://hooks\\\\.slack\\\\.com/services/T[a-zA-Z0-9_]+/B[a-zA-Z0-9_]+/[a-zA-Z0-9_]+`\n- **CWE**: CWE-798\n- **Severity**: MEDIUM\n- **Description**: Slack incoming webhook URL\n- **Remediation**: Regenerate webhook in Slack App Settings\n\n### npm Token\n- **Rule ID**: `npm-access-token`\n- **Pattern**: `npm_[0-9a-zA-Z]{36}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: npm access token\n- **Remediation**: Revoke in npm Account Settings, check package publish history\n\n### PyPI Token\n- **Rule ID**: `pypi-upload-token`\n- **Pattern**: `pypi-AgEIcHlwaS5vcmc[0-9A-Za-z\\\\-_]{50,}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: PyPI upload token\n- **Remediation**: Delete token in PyPI Account Settings, verify package uploads\n\n## Database Credentials\n\n### PostgreSQL Connection String\n- **Rule ID**: `postgres-connection-string`\n- **Pattern**: `postgres(ql)?://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+/[a-zA-Z0-9_-]+`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL\n- **Description**: PostgreSQL database connection string with embedded credentials\n- **Remediation**: Change database password, use connection string from environment variables\n\n### MySQL Connection String\n- **Rule ID**: `mysql-connection-string`\n- **Pattern**: `mysql://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+/[a-zA-Z0-9_-]+`\n- **CWE**: CWE-259\n- **Severity**: CRITICAL\n- **Description**: MySQL database connection string with embedded credentials\n- **Remediation**: Rotate database password immediately, review access logs\n\n### MongoDB Connection String\n- **Rule ID**: `mongodb-connection-string`\n- **Pattern**: `mongodb(\\+srv)?://[a-zA-Z0-9]+:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+`\n- **CWE**: CWE-798\n- **Severity**: CRITICAL\n- **Description**: MongoDB connection string with credentials\n- **Remediation**: Change MongoDB user password, enable IP whitelisting\n\n### Redis URL\n- **Rule ID**: `redis-url`\n- **Pattern**: `redis://:[a-zA-Z0-9]+@[a-zA-Z0-9.-]+:[0-9]+`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: Redis connection URL with password\n- **Remediation**: Change Redis password via CONFIG SET, use ACLs\n\n## Private Keys\n\n### RSA Private Key\n- **Rule ID**: `rsa-private-key`\n- **Pattern**: `-----BEGIN RSA PRIVATE KEY-----`\n- **CWE**: CWE-321 (Use of Hard-coded Cryptographic Key)\n- **Severity**: CRITICAL\n- **Description**: RSA private key in PEM format\n- **Remediation**: Generate new key pair, revoke associated certificates, audit access\n\n### SSH Private Key\n- **Rule ID**: `ssh-private-key`\n- **Pattern**: `-----BEGIN (EC|DSA|OPENSSH) PRIVATE KEY-----`\n- **CWE**: CWE-321\n- **Severity**: CRITICAL\n- **Description**: SSH private key\n- **Remediation**: Remove from authorized_keys on all servers, generate new key\n\n### PGP Private Key\n- **Rule ID**: `pgp-private-key`\n- **Pattern**: `-----BEGIN PGP PRIVATE KEY BLOCK-----`\n- **CWE**: CWE-321\n- **Severity**: CRITICAL\n- **Description**: PGP/GPG private key\n- **Remediation**: Revoke key on keyservers, generate new key pair\n\n### JWT Token\n- **Rule ID**: `jwt`\n- **Pattern**: `eyJ[A-Za-z0-9_-]{10,}\\\\.[A-Za-z0-9_-]{10,}\\\\.[A-Za-z0-9_-]{10,}`\n- **CWE**: CWE-798\n- **Severity**: HIGH\n- **Description**: JSON Web Token (may contain sensitive claims)\n- **Remediation**: Invalidate token, check token expiration, rotate signing secret\n\n## Generic Patterns\n\n### Generic API Key\n- **Rule ID**: `generic-api-key`\n- **Pattern**: `(?i)(api_key|apikey|api-key)[\\s]*[=:][\\s]*[\\'\\\"]?[a-zA-Z0-9]{32,}[\\'\\\"]?`\n- **CWE**: CWE-798\n- **Severity**: MEDIUM\n- **Description**: Generic API key pattern\n- **Remediation**: Rotate credential based on service documentation\n\n### Generic Secret\n- **Rule ID**: `generic-secret`\n- **Pattern**: `(?i)(secret|password|passwd|pwd)[\\s]*[=:][\\s]*[\\'\\\"]?[a-zA-Z0-9!@#$%^&*]{16,}[\\'\\\"]?`\n- **CWE**: CWE-259\n- **Severity**: MEDIUM\n- **Description**: Generic secret or password pattern\n- **Remediation**: Move to environment variable or secret management system\n\n### High Entropy String\n- **Rule ID**: `high-entropy`\n- **Pattern**: `[a-zA-Z0-9]{32,}`\n- **Entropy**: 4.5+\n- **CWE**: CWE-798\n- **Severity**: LOW (requires validation)\n- **Description**: High-entropy string that may be a credential\n- **Remediation**: Validate if actual secret, rotate if necessary\n\n## Usage in Configuration\n\nAdd these rule IDs to your `.gitleaks.toml` allowlist if needed:\n\n```toml\n[allowlist]\ndescription = \"Allow specific rules in test files\"\npaths = ['''test/''']\nrules = [\"generic-api-key\", \"generic-secret\"]\n```\n\n## CWE Reference\n\n- **CWE-798**: Use of Hard-coded Credentials\n- **CWE-259**: Use of Hard-coded Password\n- **CWE-321**: Use of Hard-coded Cryptographic Key\n- **CWE-522**: Insufficiently Protected Credentials\n- **CWE-257**: Storing Passwords in a Recoverable Format\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9534,"content_sha256":"3de621fe8a6cba60607ffdf4fbf874ed2031af9a90fba81e1aa36d138eea5161"},{"filename":"references/EXAMPLE.md","content":"# Reference Document Template\n\nThis file contains detailed reference material that Claude should load only when needed.\n\n## Table of Contents\n\n- [Section 1](#section-1)\n- [Section 2](#section-2)\n- [Security Standards](#security-standards)\n\n## Section 1\n\nDetailed information, schemas, or examples that are too large for SKILL.md.\n\n## Section 2\n\nAdditional reference material.\n\n## Security Standards\n\n### OWASP Top 10\n\nReference relevant OWASP categories:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- etc.\n\n### CWE Mappings\n\nMap to relevant Common Weakness Enumeration categories:\n- CWE-79: Cross-site Scripting\n- CWE-89: SQL Injection\n- etc.\n\n### MITRE ATT&CK\n\nReference relevant tactics and techniques if applicable:\n- TA0001: Initial Access\n- T1190: Exploit Public-Facing Application\n- etc.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":809,"content_sha256":"4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05"},{"filename":"references/false_positives.md","content":"# False Positives Management\n\nStrategies for managing false positives in Gitleaks secret detection.\n\n## Table of Contents\n\n- [Understanding False Positives](#understanding-false-positives)\n- [Allowlist Strategies](#allowlist-strategies)\n- [Common False Positive Patterns](#common-false-positive-patterns)\n- [Configuration Examples](#configuration-examples)\n- [Best Practices](#best-practices)\n\n## Understanding False Positives\n\nFalse positives occur when legitimate code patterns match secret detection rules.\n\n### Categories of False Positives\n\n1. **Example/Placeholder Values**: Documentation and examples using fake credentials\n2. **Test Fixtures**: Test data with credential-like patterns\n3. **Non-Secret Constants**: Configuration values that match patterns but aren't sensitive\n4. **Generated Code**: Auto-generated code with high-entropy strings\n5. **Comments and Documentation**: Explanatory text matching patterns\n\n### Impact Assessment\n\nBefore allowlisting, verify it's truly a false positive:\n\n```bash\n# Extract the flagged value\necho \"api_key_here\" | base64 # Check if valid encoding\ncurl -H \"Authorization: Bearer \u003ctoken>\" https://api.service.com/test # Test if active\n\n# Check git history for when added\ngit log -p --all -S \"flagged_value\"\n\n# Review context around detection\ngit show \u003ccommit-sha>:\u003cfile-path>\n```\n\n## Allowlist Strategies\n\n### 1. Path-Based Allowlisting\n\nExclude entire directories or file patterns:\n\n```toml\n[allowlist]\ndescription = \"Exclude test and documentation files\"\npaths = [\n '''test/.*''', # All test directories\n '''tests/.*''', # Alternative test directory name\n '''.*/fixtures/.*''', # Test fixtures anywhere\n '''examples/.*''', # Example code\n '''docs/.*''', # Documentation\n '''.*\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Markdown files\n '''.*\\.rst

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # ReStructuredText files\n '''.*_test\\.go

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Go test files\n '''.*\\.test\\.js

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # JavaScript test files\n '''.*\\.spec\\.ts

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # TypeScript spec files\n]\n```\n\n### 2. Stopword Allowlisting\n\nFilter out known placeholder values:\n\n```toml\n[allowlist]\ndescription = \"Common placeholder values\"\nstopwords = [\n \"example\",\n \"placeholder\",\n \"your_api_key_here\",\n \"your_secret_here\",\n \"REPLACEME\",\n \"CHANGEME\",\n \"xxxxxx\",\n \"000000\",\n \"123456\",\n \"abcdef\",\n \"sample\",\n \"dummy\",\n \"fake\",\n \"test_key\",\n \"mock_token\",\n]\n```\n\n### 3. Commit-Based Allowlisting\n\nAllowlist specific commits after manual verification:\n\n```toml\n[allowlist]\ndescription = \"Verified false positives\"\ncommits = [\n \"a1b2c3d4e5f6\", # Initial test fixtures - verified 2024-01-15\n \"f6e5d4c3b2a1\", # Documentation examples - verified 2024-01-16\n]\n```\n\nAdd comment explaining why each commit is allowlisted.\n\n### 4. Regex Allowlisting\n\nAllowlist specific patterns:\n\n```toml\n[allowlist]\ndescription = \"Pattern-based allowlist\"\nregexes = [\n '''example_api_key_[0-9]+''', # Example keys with numeric suffix\n '''key\\s*=\\s*[\"']EXAMPLE[\"']''', # Explicitly marked examples\n '''(?i)test_?password_?[0-9]*''', # Test passwords\n '''(?i)dummy.*secret''', # Dummy secrets\n]\n```\n\n### 5. Rule-Specific Allowlisting\n\nCreate exceptions for specific rules only:\n\n```toml\n[[rules]]\nid = \"generic-api-key\"\ndescription = \"Generic API Key\"\nregex = '''(?i)api_key\\s*=\\s*[\"']([a-zA-Z0-9]{32})[\"']'''\n\n[rules.allowlist]\ndescription = \"Allow generic API key pattern in specific contexts\"\npaths = ['''config/defaults\\.yaml''']\nregexes = ['''api_key\\s*=\\s*[\"']example''']\n```\n\n### 6. Global vs Rule Allowlists\n\nGlobal allowlists override rule-specific ones:\n\n```toml\n# Global allowlist - highest precedence\n[allowlist]\ndescription = \"Organization-wide exceptions\"\npaths = ['''vendor/''', '''node_modules/''']\n\n# Rule-specific allowlist\n[[rules]]\nid = \"custom-secret\"\n[rules.allowlist]\ndescription = \"Exceptions only for this rule\"\npaths = ['''config/template\\.yml''']\n```\n\n## Common False Positive Patterns\n\n### 1. Documentation Examples\n\n**Problem**: README and documentation contain example credentials.\n\n**Solution**:\n```toml\n[allowlist]\npaths = [\n '''README\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''CONTRIBUTING\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''docs/.*\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''.*\\.example

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # .env.example files\n '''.*\\.template

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Template files\n '''.*\\.sample

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Sample configurations\n]\n\nstopwords = [\n \"example.com\",\n \"[email protected]\",\n \"YOUR_API_KEY\",\n]\n```\n\n### 2. Test Fixtures\n\n**Problem**: Test data contains credential-like strings for testing credential handling.\n\n**Solution**:\n```toml\n[allowlist]\npaths = [\n '''test/fixtures/.*''',\n '''spec/fixtures/.*''',\n '''.*/testdata/.*''', # Go convention\n '''.*/mocks/.*''',\n '''cypress/fixtures/.*''', # Cypress test data\n]\n\n# Or use inline comments in code\n# password = \"test_password_123\" # gitleaks:allow\n```\n\n### 3. Generated Code\n\n**Problem**: Code generators produce high-entropy identifiers.\n\n**Solution**:\n```toml\n[allowlist]\ndescription = \"Generated code\"\npaths = [\n '''.*\\.pb\\.go

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Protocol buffer generated code\n '''.*_generated\\..*''', # Generated file marker\n '''node_modules/.*''', # Dependencies\n '''vendor/.*''', # Vendored dependencies\n '''dist/.*''', # Build output\n '''build/.*''',\n]\n```\n\n### 4. Configuration Templates\n\n**Problem**: Config templates with placeholder values match patterns.\n\n**Solution**:\n```toml\n[allowlist]\npaths = [\n '''config/.*\\.template''',\n '''templates/.*''',\n '''.*\\.tpl

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''.*\\.tmpl

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n]\n\nstopwords = [\n \"REPLACE_WITH_YOUR\",\n \"CONFIGURE_ME\",\n \"SET_THIS_VALUE\",\n]\n```\n\n### 5. Base64 Encoded Strings\n\n**Problem**: Non-secret base64 data flagged due to high entropy.\n\n**Solution**:\n```toml\n# Increase entropy threshold to reduce false positives\n[[rules]]\nid = \"high-entropy-base64\"\nregex = '''[a-zA-Z0-9+/]{40,}={0,2}'''\nentropy = 5.5 # Increase from default 4.5\n```\n\nOr allowlist specific patterns:\n```toml\n[allowlist]\nregexes = [\n '''data:image/[^;]+;base64,''', # Base64 encoded images\n '''-----BEGIN CERTIFICATE-----''', # Public certificates (not private keys)\n]\n```\n\n### 6. Public Keys and Certificates\n\n**Problem**: Public keys detected (which are not secrets).\n\n**Solution**:\n```toml\n[allowlist]\nregexes = [\n '''-----BEGIN PUBLIC KEY-----''',\n '''-----BEGIN CERTIFICATE-----''',\n '''-----BEGIN X509 CERTIFICATE-----''',\n]\n\n# But DO NOT allowlist:\n# -----BEGIN PRIVATE KEY-----\n# -----BEGIN RSA PRIVATE KEY-----\n```\n\n### 7. UUIDs and Identifiers\n\n**Problem**: UUIDs match high-entropy patterns.\n\n**Solution**:\n```toml\n[allowlist]\nregexes = [\n '''[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}''', # UUID\n '''[0-9a-f]{24}''', # MongoDB ObjectId\n]\n```\n\nOr adjust entropy detection:\n```toml\n[[rules]]\nid = \"generic-high-entropy\"\nentropy = 6.0 # Only flag very high entropy\n```\n\n## Configuration Examples\n\n### Minimal Configuration\n\nStart with broad allowlists, refine over time:\n\n```toml\ntitle = \"Minimal Gitleaks Configuration\"\n\n[extend]\nuseDefault = true # Use all built-in rules\n\n[allowlist]\ndescription = \"Broad allowlist for initial rollout\"\npaths = [\n '''test/.*''',\n '''.*\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''vendor/.*''',\n '''node_modules/.*''',\n]\n\nstopwords = [\n \"example\",\n \"test\",\n \"mock\",\n \"dummy\",\n]\n```\n\n### Strict Configuration\n\nMinimize false positives with targeted allowlists:\n\n```toml\ntitle = \"Strict Gitleaks Configuration\"\n\n[extend]\nuseDefault = true\n\n[allowlist]\ndescription = \"Minimal allowlist - verify all exceptions\"\n\n# Only allow specific known false positives\npaths = [\n '''docs/api-examples\\.md''', # API documentation with examples\n '''test/fixtures/auth\\.json''', # Authentication test fixtures\n]\n\n# Specific known placeholder values\nstopwords = [\n \"YOUR_API_KEY_HERE\",\n \"sk_test_example_key_123456789\",\n]\n\n# Manually verified commits\ncommits = [\n \"abc123def456\", # Test fixtures added - verified 2024-01-15 by [email protected]\n]\n```\n\n### Balanced Configuration\n\nBalance detection sensitivity with operational overhead:\n\n```toml\ntitle = \"Balanced Gitleaks Configuration\"\n\n[extend]\nuseDefault = true\n\n[allowlist]\ndescription = \"Balanced allowlist\"\n\n# Common non-secret paths\npaths = [\n '''test/fixtures/.*''',\n '''spec/fixtures/.*''',\n '''.*\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'',\n '''docs/.*''',\n '''examples/.*''',\n '''vendor/.*''',\n '''node_modules/.*''',\n]\n\n# Common placeholders\nstopwords = [\n \"example\",\n \"placeholder\",\n \"your_key_here\",\n \"replace_me\",\n \"changeme\",\n \"test\",\n \"dummy\",\n \"mock\",\n]\n\n# Public non-secrets\nregexes = [\n '''-----BEGIN CERTIFICATE-----''',\n '''-----BEGIN PUBLIC KEY-----''',\n '''data:image/[^;]+;base64,''',\n]\n```\n\n## Best Practices\n\n### 1. Document Allowlist Decisions\n\nAlways add comments explaining why patterns are allowlisted:\n\n```toml\n[allowlist]\ndescription = \"Verified false positives - reviewed 2024-01-15\"\n\n# Test fixtures created during initial test suite development\n# Contains only example credentials for testing credential validation\npaths = ['''test/fixtures/credentials\\.json''']\n\n# Documentation examples using clearly fake values\n# All examples prefixed with \"example_\" or \"test_\"\nstopwords = [\"example_\", \"test_\"]\n```\n\n### 2. Regular Allowlist Review\n\nSchedule periodic reviews:\n\n```bash\n#!/bin/bash\n# review-allowlist.sh\n\necho \"Gitleaks Allowlist Review\"\necho \"=========================\"\necho \"\"\n\n# Show allowlist paths\necho \"Allowlisted paths:\"\ngrep -A 10 \"^\\[allowlist\\]\" .gitleaks.toml | grep \"paths = \"\n\n# Show allowlisted commits\necho \"\"\necho \"Allowlisted commits:\"\ngrep -A 10 \"^\\[allowlist\\]\" .gitleaks.toml | grep \"commits = \"\n\n# Check if commits still exist\n# (May have been removed in history rewrite)\ngit rev-parse --verify abc123def456 2>/dev/null || echo \"WARNING: Commit abc123def456 not found\"\n```\n\n### 3. Use Inline Annotations Sparingly\n\nFor one-off false positives, use inline comments:\n\n```python\n# This is a test password for unit tests only\n# gitleaks:allow\nTEST_PASSWORD = \"test_password_123\"\n```\n\n**Warning**: Overuse of inline annotations indicates poorly tuned configuration.\n\n### 4. Version Control Your Configuration\n\nTrack changes to `.gitleaks.toml`:\n\n```bash\ngit log -p .gitleaks.toml\n\n# See who allowlisted what and when\ngit blame .gitleaks.toml\n```\n\n### 5. Test Allowlist Changes\n\nBefore committing allowlist changes:\n\n```bash\n# Test configuration\ngitleaks detect --config .gitleaks.toml -v\n\n# Verify specific file is now allowed\ngitleaks detect --config .gitleaks.toml --source test/fixtures/credentials.json\n\n# Verify secret is still caught in production code\necho 'api_key = \"sk_live_actual_key\"' > /tmp/test_detection.py\ngitleaks detect --config .gitleaks.toml --source /tmp/test_detection.py --no-git\n```\n\n### 6. Separate Allowlists by Environment\n\nUse different configurations for different contexts:\n\n```bash\n# Strict config for production code\ngitleaks detect --config .gitleaks.strict.toml --source src/\n\n# Lenient config for test code\ngitleaks detect --config .gitleaks.lenient.toml --source test/\n```\n\n### 7. Monitor False Positive Rate\n\nTrack metrics over time:\n\n```bash\n# Total findings\nTOTAL=$(gitleaks detect --report-format json 2>/dev/null | jq '. | length')\n\n# Run with allowlist\nAFTER_FILTER=$(gitleaks detect --config .gitleaks.toml --report-format json 2>/dev/null | jq '. | length')\n\n# Calculate reduction\necho \"False positive reduction: $(($TOTAL - $AFTER_FILTER)) / $TOTAL\"\n```\n\n**Target**: \u003c 10% false positive rate for good developer experience.\n\n### 8. Security Review for New Allowlists\n\nRequire security team approval for:\n- New allowlisted paths in `src/` or production code\n- New allowlisted commits (verify manually first)\n- Changes to rule-specific allowlists\n- New stopwords that could mask real secrets\n\n### 9. Avoid Overly Broad Patterns\n\n**Bad** (too broad):\n```toml\n[allowlist]\npaths = ['''.*'''] # Disables all detection!\nstopwords = [\"key\", \"secret\"] # Matches too many real secrets\n```\n\n**Good** (specific):\n```toml\n[allowlist]\npaths = ['''test/unit/.*\\.test\\.js

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

''] # Specific test directory\nstopwords = [\"example_key\", \"test_secret\"] # Specific placeholders\n```\n\n### 10. Escape Special Characters\n\nWhen using regex patterns, escape properly:\n\n```toml\n[allowlist]\nregexes = [\n '''api\\.example\\.com''', # Literal dot\n '''config\\[\\'key\\'\\]''', # Literal brackets and quotes\n]\n```\n\n## Troubleshooting False Positives\n\n### Issue: Can't Identify Source of False Positive\n\n```bash\n# Run with verbose output\ngitleaks detect -v | grep \"RuleID\"\n\n# Get detailed finding information\ngitleaks detect --report-format json | jq '.[] | {file: .File, line: .StartLine, rule: .RuleID}'\n\n# View context around detection\ngitleaks detect --report-format json | jq -r '.[0] | .File, .StartLine' | xargs -I {} sh -c 'sed -n \"{}-5,{}+5p\" {}'\n```\n\n### Issue: Allowlist Not Working\n\n```bash\n# Verify config is loaded\ngitleaks detect --config .gitleaks.toml -v 2>&1 | grep \"config\"\n\n# Check regex syntax\necho \"test_string\" | grep -E 'your_regex_pattern'\n\n# Test path matching\necho \"test/fixtures/file.json\" | grep -E 'test/fixtures/.*'\n```\n\n### Issue: Too Many False Positives\n\n1. **Export findings**: `gitleaks detect --report-format json > findings.json`\n2. **Analyze patterns**: `jq -r '.[].File' findings.json | sort | uniq -c | sort -rn`\n3. **Group by rule**: `jq -r '.[].RuleID' findings.json | sort | uniq -c | sort -rn`\n4. **Create targeted allowlists** based on analysis\n\n## False Positive vs Real Secret\n\nWhen unsure, err on the side of caution:\n\n| Indicator | False Positive | Real Secret |\n|-----------|----------------|-------------|\n| Location | Test/docs/examples | Production code |\n| Pattern | \"example\", \"test\", \"mock\" | No such indicators |\n| Entropy | Low/medium | High |\n| Format | Incomplete/truncated | Complete/valid |\n| Context | Educational comments | Functional code |\n| Git history | Added in test commits | Added furtively |\n\n**When in doubt**: Treat as real secret and investigate.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13938,"content_sha256":"137e374fc8ffc95cdb401281bf205f0dfb58a8e8893e8d71b4c32afceabcc72d"},{"filename":"references/remediation_guide.md","content":"# Secret Remediation Guide\n\nComprehensive procedures for remediating exposed secrets detected by Gitleaks.\n\n## Table of Contents\n\n- [Immediate Response](#immediate-response)\n- [Remediation Workflow](#remediation-workflow)\n- [Git History Cleanup](#git-history-cleanup)\n- [Cloud Provider Specific](#cloud-provider-specific)\n- [Database Credentials](#database-credentials)\n- [API Keys and Tokens](#api-keys-and-tokens)\n- [Post-Remediation](#post-remediation)\n\n## Immediate Response\n\nWhen secrets are detected, follow this priority order:\n\n### 1. Assess Exposure (0-15 minutes)\n\n**Questions to answer immediately:**\n- Is the repository public or private?\n- Has the commit been pushed to remote?\n- How long has the secret been exposed?\n- What systems does this credential access?\n\n**Actions:**\n```bash\n# Check if commit is pushed\ngit log origin/main..HEAD # If output, not yet pushed\n\n# Check repository visibility\ngh repo view --json visibility\n\n# Check commit age\ngit log -1 --format=\"%ar\" \u003ccommit-sha>\n```\n\n### 2. Rotate Credentials (0-30 minutes)\n\n**CRITICAL**: Rotate the exposed credential immediately, regardless of exposure duration.\n\nPriority order:\n1. **Production credentials** - Immediate rotation\n2. **Payment/financial systems** - Immediate rotation\n3. **Customer data access** - Immediate rotation\n4. **Development/test credentials** - Rotate within 24 hours\n\n### 3. Review Access Logs (30-60 minutes)\n\nCheck for unauthorized access:\n- Cloud provider audit logs (CloudTrail, Cloud Audit Logs, Activity Log)\n- Application logs showing authentication attempts\n- Database connection logs\n- API usage logs\n\n### 4. Remove from Code (0-24 hours)\n\nRemove secret from current code and optionally from git history.\n\n## Remediation Workflow\n\n### Step 1: Rotate the Credential\n\n**Before removing from code**, rotate the credential to prevent race conditions.\n\n#### Cloud Providers\n\n**AWS**:\n```bash\n# Deactivate compromised key\naws iam update-access-key \\\n --access-key-id AKIA... \\\n --status Inactive \\\n --user-name username\n\n# Create new key\naws iam create-access-key --user-name username\n\n# Delete old key after updating applications\naws iam delete-access-key \\\n --access-key-id AKIA... \\\n --user-name username\n```\n\n**GCP**:\n```bash\n# Delete service account key\ngcloud iam service-accounts keys delete KEY_ID \\\n --iam-account=SERVICE_ACCOUNT_EMAIL\n\n# Create new key\ngcloud iam service-accounts keys create new-key.json \\\n --iam-account=SERVICE_ACCOUNT_EMAIL\n```\n\n**Azure**:\n```bash\n# Regenerate storage account key\naz storage account keys renew \\\n --account-name ACCOUNT_NAME \\\n --key primary\n\n# List keys to verify\naz storage account keys list \\\n --account-name ACCOUNT_NAME\n```\n\n#### API Tokens\n\n**GitHub**:\n1. Navigate to Settings > Developer settings > Personal access tokens\n2. Find the compromised token (check \"Last used\" column)\n3. Click \"Delete\"\n4. Generate new token with minimal required scopes\n\n**Stripe**:\n1. Log into Stripe Dashboard\n2. Navigate to Developers > API keys\n3. Click \"Roll\" on the compromised key\n4. Update all applications with new key\n\n**Generic API Key**:\n1. Access provider's console/dashboard\n2. Locate API key management\n3. Revoke/delete compromised key\n4. Generate new key\n5. Update applications\n6. Test connectivity\n\n### Step 2: Remove from Current Code\n\nReplace hardcoded secrets with environment variables or secret management:\n\n**Before** (insecure):\n```python\nAPI_KEY = \"sk_live_51ABC123...\"\ndb_password = \"MyP@ssw0rd123\"\n```\n\n**After** (secure):\n```python\nimport os\n\nAPI_KEY = os.environ.get(\"STRIPE_API_KEY\")\nif not API_KEY:\n raise ValueError(\"STRIPE_API_KEY environment variable not set\")\n\ndb_password = os.environ.get(\"DB_PASSWORD\")\n```\n\n**Using secret management**:\n```python\nfrom azure.keyvault.secrets import SecretClient\nfrom azure.identity import DefaultAzureCredential\n\ncredential = DefaultAzureCredential()\nclient = SecretClient(vault_url=\"https://myvault.vault.azure.net/\", credential=credential)\n\ndb_password = client.get_secret(\"database-password\").value\n```\n\n### Step 3: Commit the Fix\n\n```bash\n# Add changes\ngit add .\n\n# Commit with clear message\ngit commit -m \"refactor: Move API credentials to environment variables\n\n- Replace hardcoded Stripe API key with environment variable\n- Replace database password with AWS Secrets Manager reference\n- Add validation for required environment variables\n\nAddresses: Secret exposure detected by Gitleaks scan\"\n\n# Push\ngit push origin main\n```\n\n## Git History Cleanup\n\nIf secrets are in pushed commits, consider removing from git history.\n\n### Decision Matrix\n\n| Scenario | Action | Reason |\n|----------|--------|--------|\n| Public repo, secret exposed | **Mandatory** history rewrite | Secret is public knowledge |\n| Private repo, \u003c 24 hours, \u003c 5 collaborators | **Recommended** history rewrite | Minimal disruption |\n| Private repo, > 1 week, > 10 collaborators | **Optional** - Rotate only | High coordination cost |\n| Production repo with CI/CD | **Coordinate carefully** | May break automation |\n\n### Method 1: git-filter-repo (Recommended)\n\nInstall:\n```bash\npip install git-filter-repo\n```\n\nRemove specific file from all history:\n```bash\n# Backup first\ngit clone --mirror \u003crepo-url> backup-repo.git\n\n# Remove file\ngit filter-repo --path config/secrets.yaml --invert-paths\n\n# Force push\ngit push origin --force --all\n```\n\nRemove secrets matching pattern:\n```bash\n# Use callback for complex filtering\ngit filter-repo --replace-text \u003c(echo 'regex:sk_live_[a-zA-Z0-9]{24}==>REDACTED')\n```\n\n### Method 2: BFG Repo-Cleaner\n\nDownload:\n```bash\n# macOS\nbrew install bfg\n\n# Or download JAR from https://rtyley.github.io/bfg-repo-cleaner/\n```\n\nRemove specific file:\n```bash\n# Clone mirror\ngit clone --mirror \u003crepo-url> repo-mirror.git\ncd repo-mirror.git\n\n# Remove file\nbfg --delete-files secrets.env\n\n# Clean up\ngit reflog expire --expire=now --all\ngit gc --prune=now --aggressive\n\n# Force push\ngit push\n```\n\nRemove secrets by pattern:\n```bash\n# Create replacements.txt\necho \"PASSWORD1==>***REMOVED***\" > replacements.txt\necho \"sk_live_51ABC==>***REMOVED***\" >> replacements.txt\n\n# Run BFG\nbfg --replace-text replacements.txt repo-mirror.git\n```\n\n### Method 3: Interactive Rebase (Small Changes)\n\nFor recent commits not yet widely distributed:\n\n```bash\n# Rebase last N commits\ngit rebase -i HEAD~5\n\n# In editor, mark commits to 'edit'\n# When stopped at each commit:\ngit rm config/secrets.yaml\ngit commit --amend --no-edit\ngit rebase --continue\n\n# Force push\ngit push --force-with-lease\n```\n\n### Post-Rewrite Coordination\n\nAfter rewriting history:\n\n1. **Notify team immediately**:\n```text\nURGENT: Git history rewritten to remove exposed credentials.\n\nAction required for all developers:\n1. Commit/stash any local changes\n2. Run: git fetch origin && git reset --hard origin/main\n3. Delete and re-clone if issues persist\n\nContact security team with questions.\n```\n\n2. **Update CI/CD**:\n - Invalidate old caches\n - May need to reconfigure webhooks\n - Update any hardcoded commit references\n\n3. **Update branch protection**:\n - May need to temporarily disable\n - Re-enable after force push completes\n\n## Cloud Provider Specific\n\n### AWS\n\n**Check for unauthorized access**:\n```bash\n# List recent API calls for access key\naws cloudtrail lookup-events \\\n --lookup-attributes AttributeKey=Username,AttributeValue=compromised-user \\\n --max-results 50 \\\n --start-time $(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%S)\n```\n\n**Revoke all sessions**:\n```bash\n# Attach policy to deny all actions\naws iam put-user-policy \\\n --user-name compromised-user \\\n --policy-name DenyAll \\\n --policy-document '{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Deny\",\"Action\":\"*\",\"Resource\":\"*\"}]}'\n```\n\n### GCP\n\n**Check audit logs**:\n```bash\ngcloud logging read \"protoPayload.authenticationInfo.principalEmail=SERVICE_ACCOUNT_EMAIL\" \\\n --limit 100 \\\n --format json\n```\n\n**Disable service account**:\n```bash\ngcloud iam service-accounts disable SERVICE_ACCOUNT_EMAIL\n```\n\n### Azure\n\n**Review activity logs**:\n```bash\naz monitor activity-log list \\\n --start-time 2024-01-01T00:00:00Z \\\n --resource-id /subscriptions/SUBSCRIPTION_ID\n```\n\n**Revoke access**:\n```bash\n# Regenerate keys\naz storage account keys renew \\\n --account-name STORAGE_ACCOUNT \\\n --key primary\n```\n\n## Database Credentials\n\n### PostgreSQL\n\n```sql\n-- Change password\nALTER USER app_user WITH PASSWORD 'new_secure_password';\n\n-- View recent connections\nSELECT datname, usename, client_addr, backend_start\nFROM pg_stat_activity\nWHERE usename = 'app_user'\nORDER BY backend_start DESC;\n\n-- Kill active connections (if suspicious)\nSELECT pg_terminate_backend(pid)\nFROM pg_stat_activity\nWHERE usename = 'app_user' AND client_addr != 'trusted_ip';\n```\n\n### MySQL\n\n```sql\n-- Change password\nALTER USER 'app_user'@'%' IDENTIFIED BY 'new_secure_password';\nFLUSH PRIVILEGES;\n\n-- View recent connections\nSELECT * FROM information_schema.PROCESSLIST\nWHERE USER = 'app_user';\n\n-- Kill connections\nKILL CONNECTION process_id;\n```\n\n### MongoDB\n\n```javascript\n// Change password\nuse admin\ndb.changeUserPassword(\"app_user\", \"new_secure_password\")\n\n// View recent operations\ndb.currentOp({ \"active\": true })\n\n// Kill operation\ndb.killOp(opid)\n```\n\n## API Keys and Tokens\n\n### GitHub\n\n**Audit unauthorized access**:\n```bash\n# List recent events for token\ngh api /users/{username}/events/public | jq '.[] | {type, repo: .repo.name, created_at}'\n```\n\n**Revoke all tokens** (if compromised account):\n1. Settings > Developer settings > Personal access tokens\n2. Select all tokens\n3. Click \"Delete\"\n\n### Slack\n\n**Check workspace audit logs**:\n1. Go to workspace settings (admin required)\n2. Navigate to Logs > Audit Logs\n3. Filter by token usage\n\n**Regenerate token**:\n1. Go to api.slack.com/apps\n2. Select your app\n3. Navigate to OAuth & Permissions\n4. Click \"Regenerate\" on token\n\n## Post-Remediation\n\n### 1. Implement Prevention\n\n**Pre-commit hooks**:\n```bash\n# Install Gitleaks pre-commit hook\ncd /path/to/repo\ncat \u003c\u003c 'EOF' > .git/hooks/pre-commit\n#!/bin/sh\ngitleaks protect --verbose --redact --staged\nEOF\nchmod +x .git/hooks/pre-commit\n```\n\n**CI/CD checks**:\n```yaml\n# .github/workflows/secrets-scan.yml\nname: Secret Scanning\non: [push, pull_request]\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - uses: gitleaks/gitleaks-action@v2\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n### 2. Update Secret Management\n\nMigrate to proper secret management:\n\n**Environment variables** (minimal):\n```bash\n# .env (never commit!)\nDATABASE_URL=postgresql://user:pass@host:5432/db\nAPI_KEY=sk_live_...\n\n# .gitignore\n.env\n.env.local\n```\n\n**Secret management services**:\n- AWS: Secrets Manager, Systems Manager Parameter Store\n- GCP: Secret Manager\n- Azure: Key Vault\n- HashiCorp: Vault\n- Kubernetes: Secrets\n\n### 3. Document Incident\n\nCreate incident report including:\n- **Timeline**: When secret was committed, detected, remediated\n- **Exposure**: Duration, repository visibility, access scope\n- **Impact**: Systems accessed, data at risk, unauthorized activity\n- **Response**: Rotation completed, logs reviewed, history cleaned\n- **Prevention**: Controls implemented to prevent recurrence\n\n### 4. Team Training\n\nConduct training on:\n- Using environment variables and secret management\n- Pre-commit hooks and local scanning\n- Recognizing secrets in code review\n- Incident response procedures\n\n### 5. Compliance Notifications\n\nIf required by regulations:\n- **GDPR**: Notify supervisory authority within 72 hours if personal data at risk\n- **PCI-DSS**: Notify card brands and processor if payment data affected\n- **SOC2**: Document in compliance report, may trigger audit\n- **HIPAA**: Notify covered entities if PHI exposed\n\n## Prevention Checklist\n\n- [ ] Credential rotated and old credential deactivated\n- [ ] Access logs reviewed for unauthorized activity\n- [ ] Secret removed from current code\n- [ ] Git history cleaned (if applicable)\n- [ ] Team notified of credential change\n- [ ] Applications updated with new credential\n- [ ] Pre-commit hooks installed\n- [ ] CI/CD secret scanning enabled\n- [ ] Secret management solution implemented\n- [ ] Incident documented\n- [ ] Compliance notifications sent (if required)\n- [ ] Team training scheduled\n\n## Emergency Contacts\n\nMaintain contact list for rapid response:\n- **Security Team**: [email protected]\n- **DevOps On-Call**: [email protected]\n- **Cloud Provider Support**: Account-specific\n- **Compliance Officer**: [email protected]\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12533,"content_sha256":"a674e53e0c92863fa9194ccdaae2441ddb829b5171aa920746d8adc9ce71e812"},{"filename":"skill-report.json","content":"{\n \"schema_version\": \"2.0\",\n \"meta\": {\n \"generated_at\": \"2026-01-16T16:18:59.443Z\",\n \"slug\": \"agentsecops-secrets-gitleaks\",\n \"source_url\": \"https://github.com/AgentSecOps/SecOpsAgentKit/tree/main/skills/devsecops/secrets-gitleaks\",\n \"source_ref\": \"main\",\n \"model\": \"claude\",\n \"analysis_version\": \"3.0.0\",\n \"source_type\": \"community\",\n \"content_hash\": \"be2136657bae58526d7a93eaaba982cfd4e5c65e065b086c0312b5b6446c3d5e\",\n \"tree_hash\": \"52ec67c8e180ab461cfb648cf045fb121152ff572cda98dd2afce07a9589fa66\"\n },\n \"skill\": {\n \"name\": \"secrets-gitleaks\",\n \"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.\\n\",\n \"summary\": \"Hardcoded secret detection and prevention in git repositories and codebases using Gitleaks. Identifi...\",\n \"icon\": \"🔐\",\n \"version\": \"0.1.0\",\n \"author\": \"AgentSecOps\",\n \"license\": \"MIT\",\n \"category\": \"devsecops\",\n \"tags\": [\n \"secrets\",\n \"gitleaks\",\n \"secret-scanning\",\n \"devsecops\",\n \"ci-cd\",\n \"credentials\",\n \"api-keys\",\n \"compliance\"\n ],\n \"supported_tools\": [\n \"claude\",\n \"codex\",\n \"claude-code\"\n ],\n \"risk_factors\": [\n \"external_commands\",\n \"network\",\n \"filesystem\",\n \"env_access\"\n ]\n },\n \"security_audit\": {\n \"risk_level\": \"low\",\n \"is_blocked\": false,\n \"safe_to_publish\": true,\n \"summary\": \"This is a legitimate defensive security tool for detecting hardcoded secrets. All 572 static findings are FALSE POSITIVES triggered by documentation examples, configuration placeholders, and CI/CD templates. No malicious patterns exist. The skill provides guidance for integrating Gitleaks, an established open-source secret scanning tool.\",\n \"risk_factor_evidence\": [\n {\n \"factor\": \"external_commands\",\n \"evidence\": [\n {\n \"file\": \"SKILL.md\",\n \"line_start\": 36,\n \"line_end\": 48\n }\n ]\n },\n {\n \"factor\": \"network\",\n \"evidence\": [\n {\n \"file\": \"assets/github-action.yml\",\n \"line_start\": 56,\n \"line_end\": 61\n }\n ]\n },\n {\n \"factor\": \"filesystem\",\n \"evidence\": [\n {\n \"file\": \"assets/github-action.yml\",\n \"line_start\": 97,\n \"line_end\": 99\n }\n ]\n },\n {\n \"factor\": \"env_access\",\n \"evidence\": [\n {\n \"file\": \"assets/github-action.yml\",\n \"line_start\": 47,\n \"line_end\": 48\n }\n ]\n }\n ],\n \"critical_findings\": [],\n \"high_findings\": [],\n \"medium_findings\": [],\n \"low_findings\": [],\n \"dangerous_patterns\": [],\n \"files_scanned\": 13,\n \"total_lines\": 3610,\n \"audit_model\": \"claude\",\n \"audited_at\": \"2026-01-16T16:18:59.443Z\"\n },\n \"content\": {\n \"user_title\": \"Detect hardcoded secrets with Gitleaks\",\n \"value_statement\": \"Hardcoded secrets in code lead to data breaches and unauthorized access. This skill integrates Gitleaks for automated secret detection in repositories, CI/CD pipelines, and pre-commit hooks.\",\n \"seo_keywords\": [\n \"gitleaks\",\n \"secret detection\",\n \"hardcoded secrets\",\n \"credential scanning\",\n \"CI/CD security\",\n \"pre-commit hooks\",\n \"Claude\",\n \"Codex\",\n \"Claude Code\",\n \"DevSecOps\"\n ],\n \"actual_capabilities\": [\n \"Scan repositories for passwords, API keys, tokens, and credentials\",\n \"Generate JSON, SARIF, and human-readable scan reports\",\n \"Configure pre-commit hooks to prevent secret commits\",\n \"Integrate secret scanning into GitHub Actions and GitLab CI\",\n \"Create baselines for incremental secret detection\",\n \"Map findings to compliance frameworks (PCI-DSS, SOC2, GDPR)\"\n ],\n \"limitations\": [\n \"Cannot remediate secrets already pushed to public repositories\",\n \"May require tuning to reduce false positives in test code\",\n \"Requires Gitleaks binary to be installed or available via Docker\",\n \"Cannot detect encrypted or dynamically generated secrets\"\n ],\n \"use_cases\": [\n {\n \"target_user\": \"Security Engineers\",\n \"title\": \"Automated Secret Scanning\",\n \"description\": \"Set up continuous secret scanning in CI/CD pipelines with automated reporting\"\n },\n {\n \"target_user\": \"DevOps Teams\",\n \"title\": \"Pre-commit Protection\",\n \"description\": \"Install pre-commit hooks to prevent developers from accidentally committing secrets\"\n },\n {\n \"target_user\": \"Compliance Teams\",\n \"title\": \"Audit Trail Generation\",\n \"description\": \"Generate compliance reports mapping findings to PCI-DSS, SOC2, and GDPR requirements\"\n }\n ],\n \"prompt_templates\": [\n {\n \"title\": \"Quick Scan\",\n \"scenario\": \"Run a simple repository scan\",\n \"prompt\": \"Scan this repository for hardcoded secrets using Gitleaks and report all findings with file locations and rule types.\"\n },\n {\n \"title\": \"CI/CD Integration\",\n \"scenario\": \"Set up GitHub Actions workflow\",\n \"prompt\": \"Create a GitHub Actions workflow file that runs Gitleaks secret scanning on every push and pull request, with SARIF output for the Security tab.\"\n },\n {\n \"title\": \"False Positive Tuning\",\n \"scenario\": \"Reduce false positives\",\n \"prompt\": \"Help me configure Gitleaks allowlists to reduce false positives from test fixtures and documentation examples.\"\n },\n {\n \"title\": \"Compliance Report\",\n \"scenario\": \"Generate audit documentation\",\n \"prompt\": \"Generate a compliance report from Gitleaks findings showing how detected secrets map to PCI-DSS and SOC2 controls.\"\n }\n ],\n \"output_examples\": [\n {\n \"input\": \"Scan this repository for hardcoded secrets\",\n \"output\": [\n \"Found 3 potential secrets:\",\n \" - File: config/database.py:42 - Hardcoded database password (HIGH)\",\n \" - File: src/api/client.go:15 - AWS Access Key ID (CRITICAL)\",\n \" - File: tests/fixtures/auth.json:8 - Stripe test key (MEDIUM)\",\n \"\",\n \"Recommendation: Rotate exposed credentials immediately and migrate to environment variables.\"\n ]\n },\n {\n \"input\": \"Set up pre-commit hooks for secret detection\",\n \"output\": [\n \"Pre-commit hook configuration created:\",\n \" - Hook installed at .git/hooks/pre-commit\",\n \" - Gitleaks protect mode enabled with --redact flag\",\n \" - Staged changes will be scanned before commit\",\n \" - Invalid commits will be blocked with error details\"\n ]\n },\n {\n \"input\": \"Create GitHub Actions workflow for secret scanning\",\n \"output\": [\n \"GitHub Actions workflow configured:\",\n \" - Triggers on push to main/develop/release branches\",\n \" - Triggers on pull requests to main/develop\",\n \" - Runs gitleaks-action@v2 with GITHUB_TOKEN\",\n \" - Generates JSON and SARIF reports\",\n \" - Uploads findings to GitHub Security tab\"\n ]\n }\n ],\n \"best_practices\": [\n \"Always use the --redact flag when sharing scan outputs to prevent accidental secret exposure\",\n \"Install pre-commit hooks on developer workstations before any code is committed\",\n \"Create a baseline file for legacy repositories to focus on new secret exposure only\"\n ],\n \"anti_patterns\": [\n \"Skipping secret scanning in CI/CD to avoid blocking builds\",\n \"Allowlisting entire directories without reviewing individual false positives\",\n \"Sharing unredacted Gitleaks reports in public channels or tickets\"\n ],\n \"faq\": [\n {\n \"question\": \"Does Gitleaks work with private repositories?\",\n \"answer\": \"Yes, Gitleaks scans local git history and works with private repositories when run locally or in CI/CD with repository access.\"\n },\n {\n \"question\": \"How do I reduce false positives from test code?\",\n \"answer\": \"Add test directories to the allowlist in your .gitleaks.toml configuration, or use stopwords for placeholder patterns.\"\n },\n {\n \"question\": \"Can I integrate Gitleaks with Jenkins?\",\n \"answer\": \"Yes, run Gitleaks via Docker or install the binary in your Jenkins pipeline stages using the standard sh step.\"\n },\n {\n \"question\": \"Are scan reports safe to share?\",\n \"answer\": \"Only share reports with --redact flag enabled. Unredacted reports contain actual secret values and should be treated as confidential.\"\n },\n {\n \"question\": \"What is the difference between detect and protect commands?\",\n \"answer\": \"gitleaks detect scans repository history, while gitleaks protect checks staged changes before commit.\"\n },\n {\n \"question\": \"How does Gitleaks compare to other secret scanners?\",\n \"answer\": \"Gitleaks provides regex patterns, entropy analysis, and git history scanning. It is open source with active maintenance and broad CI/CD integration.\"\n }\n ]\n },\n \"file_structure\": [\n {\n \"name\": \"assets\",\n \"type\": \"dir\",\n \"path\": \"assets\",\n \"children\": [\n {\n \"name\": \"config-balanced.toml\",\n \"type\": \"file\",\n \"path\": \"assets/config-balanced.toml\",\n \"lines\": 82\n },\n {\n \"name\": \"config-custom.toml\",\n \"type\": \"file\",\n \"path\": \"assets/config-custom.toml\",\n \"lines\": 179\n },\n {\n \"name\": \"config-strict.toml\",\n \"type\": \"file\",\n \"path\": \"assets/config-strict.toml\",\n \"lines\": 49\n },\n {\n \"name\": \"github-action.yml\",\n \"type\": \"file\",\n \"path\": \"assets/github-action.yml\",\n \"lines\": 182\n },\n {\n \"name\": \"gitlab-ci.yml\",\n \"type\": \"file\",\n \"path\": \"assets/gitlab-ci.yml\",\n \"lines\": 258\n },\n {\n \"name\": \"precommit-config.yaml\",\n \"type\": \"file\",\n \"path\": \"assets/precommit-config.yaml\",\n \"lines\": 71\n }\n ]\n },\n {\n \"name\": \"references\",\n \"type\": \"dir\",\n \"path\": \"references\",\n \"children\": [\n {\n \"name\": \"compliance_mapping.md\",\n \"type\": \"file\",\n \"path\": \"references/compliance_mapping.md\",\n \"lines\": 539\n },\n {\n \"name\": \"detection_rules.md\",\n \"type\": \"file\",\n \"path\": \"references/detection_rules.md\",\n \"lines\": 277\n },\n {\n \"name\": \"EXAMPLE.md\",\n \"type\": \"file\",\n \"path\": \"references/EXAMPLE.md\",\n \"lines\": 41\n },\n {\n \"name\": \"false_positives.md\",\n \"type\": \"file\",\n \"path\": \"references/false_positives.md\",\n \"lines\": 599\n },\n {\n \"name\": \"remediation_guide.md\",\n \"type\": \"file\",\n \"path\": \"references/remediation_guide.md\",\n \"lines\": 531\n }\n ]\n },\n {\n \"name\": \"SKILL.md\",\n \"type\": \"file\",\n \"path\": \"SKILL.md\",\n \"lines\": 503\n }\n ]\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":11842,"content_sha256":"e8e94cd3edee74829a83b7170fb59623dff1924caf231ad6e5bc3918f77f7faa"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Secrets Detection with Gitleaks","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"paragraph","content":[{"text":"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.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Start","type":"text"}]},{"type":"paragraph","content":[{"text":"Scan current repository for secrets:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Install gitleaks\nbrew install gitleaks # macOS\n# or: docker pull zricethezav/gitleaks:latest\n\n# Scan current git repository\ngitleaks detect -v\n\n# Scan specific directory\ngitleaks detect --source /path/to/code -v\n\n# Generate report\ngitleaks detect --report-path gitleaks-report.json --report-format json","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Workflows","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1. Repository Scanning","type":"text"}]},{"type":"paragraph","content":[{"text":"Scan existing repositories to identify exposed secrets:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Full repository scan with verbose output\ngitleaks detect -v --source /path/to/repo\n\n# Scan with custom configuration\ngitleaks detect --config .gitleaks.toml -v\n\n# Generate JSON report for further analysis\ngitleaks detect --report-path findings.json --report-format json\n\n# Generate SARIF report for GitHub/GitLab integration\ngitleaks detect --report-path findings.sarif --report-format sarif","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use","type":"text","marks":[{"type":"strong"}]},{"text":": Initial security audit, compliance checks, incident response.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"2. Pre-Commit Hook Protection","type":"text"}]},{"type":"paragraph","content":[{"text":"Prevent secrets from being committed in the first place:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Install pre-commit hook (run in repository root)\ncat \u003c\u003c 'EOF' > .git/hooks/pre-commit\n#!/bin/sh\ngitleaks protect --verbose --redact --staged\nEOF\n\nchmod +x .git/hooks/pre-commit","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the bundled script for automated hook installation:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"./scripts/install_precommit.sh","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use","type":"text","marks":[{"type":"strong"}]},{"text":": Developer workstation setup, team onboarding, mandatory security controls.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"3. CI/CD Pipeline Integration","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"GitHub Actions","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: gitleaks\non: [push, pull_request]\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - uses: gitleaks/gitleaks-action@v2\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"GitLab CI","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"gitleaks:\n image: zricethezav/gitleaks:latest\n stage: test\n script:\n - gitleaks detect --report-path gitleaks.json --report-format json --verbose\n artifacts:\n paths:\n - gitleaks.json\n when: always\n allow_failure: false","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use","type":"text","marks":[{"type":"strong"}]},{"text":": Automated security gates, pull request checks, release validation.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"4. Baseline and Incremental Scanning","type":"text"}]},{"type":"paragraph","content":[{"text":"Establish security baseline and track only new secrets:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Create initial baseline\ngitleaks detect --report-path baseline.json --report-format json\n\n# Subsequent scans detect only new secrets\ngitleaks detect --baseline-path baseline.json --report-path new-findings.json -v","type":"text"}]},{"type":"paragraph","content":[{"text":"When to use","type":"text","marks":[{"type":"strong"}]},{"text":": Legacy codebase remediation, phased rollout, compliance tracking.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"5. Configuration Customization","type":"text"}]},{"type":"paragraph","content":[{"text":"Create custom ","type":"text"},{"text":".gitleaks.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" configuration:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"title = \"Custom Gitleaks Configuration\"\n\n[extend]\n# Extend default config with custom rules\nuseDefault = true\n\n[[rules]]\nid = \"custom-api-key\"\ndescription = \"Custom API Key Pattern\"\nregex = '''(?i)(custom_api_key|custom_secret)[\\s]*[=:][\\s]*['\"][a-zA-Z0-9]{32,}['\"]'''\ntags = [\"api-key\", \"custom\"]\n\n[allowlist]\ndescription = \"Global allowlist\"\npaths = [\n '''\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'', # Ignore markdown files\n '''test/fixtures/''', # Ignore test fixtures\n]\nstopwords = [\n '''EXAMPLE''', # Ignore example keys\n '''PLACEHOLDER''',\n]","type":"text"}]},{"type":"paragraph","content":[{"text":"Use bundled configuration templates in ","type":"text"},{"text":"assets/","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assets/config-strict.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Strict detection (low false negatives)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assets/config-balanced.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Balanced detection (recommended)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assets/config-custom.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Template for custom rules","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When to use","type":"text","marks":[{"type":"strong"}]},{"text":": Reducing false positives, adding proprietary secret patterns, organizational standards.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Security Considerations","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Sensitive Data Handling","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Secret Redaction","type":"text","marks":[{"type":"strong"}]},{"text":": Always use ","type":"text"},{"text":"--redact","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag in logs and reports to prevent accidental secret exposure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report Security","type":"text","marks":[{"type":"strong"}]},{"text":": Gitleaks reports contain detected secrets - treat as confidential, encrypt at rest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Git History","type":"text","marks":[{"type":"strong"}]},{"text":": Detected secrets in git history require complete removal using tools like ","type":"text"},{"text":"git filter-repo","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"BFG Repo-Cleaner","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Credential Rotation","type":"text","marks":[{"type":"strong"}]},{"text":": All exposed secrets must be rotated immediately, even if removed from code","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Access Control","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI/CD Permissions","type":"text","marks":[{"type":"strong"}]},{"text":": Gitleaks scans require read access to repository content and git history","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Report Access","type":"text","marks":[{"type":"strong"}]},{"text":": Restrict access to scan reports containing sensitive findings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Baseline Files","type":"text","marks":[{"type":"strong"}]},{"text":": Baseline JSON files contain secret metadata - protect with same controls as findings","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Audit Logging","type":"text"}]},{"type":"paragraph","content":[{"text":"Log the following for compliance and incident response:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scan execution timestamps and scope (repository, branch, commit range)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Number and types of secrets detected","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Remediation actions taken (credential rotation, commit history cleanup)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"False positive classifications and allowlist updates","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Compliance Requirements","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PCI-DSS 3.2.1","type":"text","marks":[{"type":"strong"}]},{"text":": Requirement 6.5.3 - Prevent hardcoded credentials in payment applications","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"SOC2","type":"text","marks":[{"type":"strong"}]},{"text":": CC6.1 - Logical access controls prevent unauthorized credential exposure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GDPR","type":"text","marks":[{"type":"strong"}]},{"text":": Article 32 - Appropriate security measures for processing personal data credentials","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CWE-798","type":"text","marks":[{"type":"strong"}]},{"text":": Use of Hard-coded Credentials","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CWE-259","type":"text","marks":[{"type":"strong"}]},{"text":": Use of Hard-coded Password","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"OWASP A07:2021","type":"text","marks":[{"type":"strong"}]},{"text":": Identification and Authentication Failures","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Bundled Resources","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scripts (","type":"text"},{"text":"scripts/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"install_precommit.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Automated pre-commit hook installation with configuration prompts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scan_and_report.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Comprehensive scanning with multiple output formats and severity classification","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"baseline_manager.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Baseline creation, comparison, and incremental scan management","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"References (","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"detection_rules.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Comprehensive list of built-in Gitleaks detection rules with CWE mappings","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"remediation_guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Step-by-step secret remediation procedures including git history cleanup","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"false_positives.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Common false positive patterns and allowlist configuration strategies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"compliance_mapping.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Detailed mapping to PCI-DSS, SOC2, GDPR, and OWASP requirements","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Assets (","type":"text"},{"text":"assets/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"config-strict.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - High-sensitivity configuration (maximum detection)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"config-balanced.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Production-ready balanced configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"config-custom.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Template with inline documentation for custom rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"precommit-config.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Pre-commit framework configuration","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"github-action.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Complete GitHub Actions workflow template","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"gitlab-ci.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":" - Complete GitLab CI pipeline template","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Patterns","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 1: Initial Repository Audit","type":"text"}]},{"type":"paragraph","content":[{"text":"First-time secret scanning for security assessment:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 1. Clone repository with full history\ngit clone --mirror https://github.com/org/repo.git audit-repo\ncd audit-repo\n\n# 2. Run comprehensive scan\ngitleaks detect --report-path audit-report.json --report-format json -v\n\n# 3. Generate human-readable report\n./scripts/scan_and_report.py --input audit-report.json --format markdown --output audit-report.md\n\n# 4. Review findings and classify false positives\n# Edit .gitleaks.toml to add allowlist entries\n\n# 5. Create baseline for future scans\ncp audit-report.json baseline.json","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 2: Developer Workstation Setup","type":"text"}]},{"type":"paragraph","content":[{"text":"Protect developers from accidental secret commits:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 1. Install gitleaks locally\nbrew install gitleaks # macOS\n# or use package manager for your OS\n\n# 2. Install pre-commit hook\n./scripts/install_precommit.sh\n\n# 3. Test hook with dummy commit\necho \"api_key = 'EXAMPLE_KEY_12345'\" > test.txt\ngit add test.txt\ngit commit -m \"test\" # Should be blocked by gitleaks\n\n# 4. Clean up test\ngit reset HEAD~1\nrm test.txt","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 3: CI/CD Pipeline with Baseline","type":"text"}]},{"type":"paragraph","content":[{"text":"Progressive secret detection in continuous integration:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# In CI pipeline script:\n\n# 1. Check if baseline exists\nif [ -f \".gitleaks-baseline.json\" ]; then\n # Incremental scan - only new secrets\n gitleaks detect \\\n --baseline-path .gitleaks-baseline.json \\\n --report-path new-findings.json \\\n --report-format json \\\n --exit-code 1 # Fail on new secrets\nelse\n # Initial scan - create baseline\n gitleaks detect \\\n --report-path .gitleaks-baseline.json \\\n --report-format json \\\n --exit-code 0 # Don't fail on first scan\nfi\n\n# 2. Generate SARIF for GitHub Security tab\nif [ -f \"new-findings.json\" ] && [ -s \"new-findings.json\" ]; then\n gitleaks detect \\\n --baseline-path .gitleaks-baseline.json \\\n --report-path results.sarif \\\n --report-format sarif\nfi","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pattern 4: Custom Rule Development","type":"text"}]},{"type":"paragraph","content":[{"text":"Add organization-specific secret patterns:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"# Add to .gitleaks.toml\n\n[[rules]]\nid = \"acme-corp-api-key\"\ndescription = \"ACME Corp Internal API Key\"\nregex = '''(?i)acme[_-]?api[_-]?key[\\s]*[=:][\\s]*['\"]?([a-f0-9]{40})['\"]?'''\nsecretGroup = 1\ntags = [\"api-key\", \"acme-internal\"]\n\n[[rules]]\nid = \"acme-corp-database-password\"\ndescription = \"ACME Corp Database Password Format\"\nregex = '''(?i)(db_pass|database_password)[\\s]*[=:][\\s]*['\"]([A-Z][a-z0-9@#$%]{15,})['\"]'''\nsecretGroup = 2\ntags = [\"password\", \"database\", \"acme-internal\"]\n\n# Test custom rules\n# gitleaks detect --config .gitleaks.toml -v","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Integration Points","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CI/CD Integration","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions","type":"text","marks":[{"type":"strong"}]},{"text":": Use ","type":"text"},{"text":"gitleaks/gitleaks-action@v2","type":"text","marks":[{"type":"code_inline"}]},{"text":" for native integration with Security tab","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitLab CI","type":"text","marks":[{"type":"strong"}]},{"text":": Docker-based scanning with artifact retention for audit trails","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Jenkins","type":"text","marks":[{"type":"strong"}]},{"text":": Execute via Docker or installed binary in pipeline stages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CircleCI","type":"text","marks":[{"type":"strong"}]},{"text":": Docker executor with orb support","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Azure Pipelines","type":"text","marks":[{"type":"strong"}]},{"text":": Task-based integration with results publishing","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Security Tools Ecosystem","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"SIEM Integration","type":"text","marks":[{"type":"strong"}]},{"text":": Export JSON findings to Splunk, ELK, or Datadog for centralized monitoring","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vulnerability Management","type":"text","marks":[{"type":"strong"}]},{"text":": Import SARIF reports into Snyk, SonarQube, or Checkmarx","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Secret Management","type":"text","marks":[{"type":"strong"}]},{"text":": Integrate findings with HashiCorp Vault or AWS Secrets Manager rotation workflows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ticketing Systems","type":"text","marks":[{"type":"strong"}]},{"text":": Automated Jira/ServiceNow ticket creation for remediation tracking","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"SDLC Integration","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Design Phase","type":"text","marks":[{"type":"strong"}]},{"text":": Include secret detection requirements in security architecture reviews","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Development","type":"text","marks":[{"type":"strong"}]},{"text":": Pre-commit hooks provide immediate feedback to developers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code Review","type":"text","marks":[{"type":"strong"}]},{"text":": PR/MR checks prevent secrets from reaching main branches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Testing","type":"text","marks":[{"type":"strong"}]},{"text":": Scan test environments and infrastructure-as-code","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deployment","type":"text","marks":[{"type":"strong"}]},{"text":": Final validation gate before production release","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Operations","type":"text","marks":[{"type":"strong"}]},{"text":": Periodic scanning of deployed configurations and logs","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Too Many False Positives","type":"text"}]},{"type":"paragraph","content":[{"text":"Symptoms","type":"text","marks":[{"type":"strong"}]},{"text":": Legitimate code patterns flagged as secrets (test fixtures, examples, placeholders)","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review findings to identify patterns: ","type":"text"},{"text":"grep -i \"example\\|test\\|placeholder\" gitleaks-report.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add to allowlist in ","type":"text"},{"text":".gitleaks.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[allowlist]\npaths = ['''test/''', '''examples/''', '''\\.md

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

'']\nstopwords = [\"EXAMPLE\", \"PLACEHOLDER\", \"YOUR_API_KEY_HERE\"]","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use commit allowlists for specific false positives:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[allowlist]\ncommits = [\"commit-sha-here\"]","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consult ","type":"text"},{"text":"references/false_positives.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for common patterns","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Performance Issues on Large Repositories","type":"text"}]},{"type":"paragraph","content":[{"text":"Symptoms","type":"text","marks":[{"type":"strong"}]},{"text":": Scans taking excessive time (>10 minutes), high memory usage","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"--log-opts","type":"text","marks":[{"type":"code_inline"}]},{"text":" to limit git history: ","type":"text"},{"text":"gitleaks detect --log-opts=\"--since=2024-01-01\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scan specific branches: ","type":"text"},{"text":"gitleaks detect --log-opts=\"origin/main\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use baseline approach to scan only recent changes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consider shallow clone for initial scans: ","type":"text"},{"text":"git clone --depth=1000","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parallelize scans across multiple branches or subdirectories","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Pre-commit Hook Blocking Valid Commits","type":"text"}]},{"type":"paragraph","content":[{"text":"Symptoms","type":"text","marks":[{"type":"strong"}]},{"text":": Developers unable to commit code with legitimate patterns","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add inline comment to bypass hook: ","type":"text"},{"text":"# gitleaks:allow","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update ","type":"text"},{"text":".gitleaks.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":" allowlist for the specific pattern","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"--redact","type":"text","marks":[{"type":"code_inline"}]},{"text":" to safely review findings: ","type":"text"},{"text":"gitleaks protect --staged --redact","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Temporary bypass (use with caution): ","type":"text"},{"text":"git commit --no-verify","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review with security team if pattern is genuinely needed","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Secrets Found in Git History","type":"text"}]},{"type":"paragraph","content":[{"text":"Symptoms","type":"text","marks":[{"type":"strong"}]},{"text":": Secrets detected in old commits, already removed from current code","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rotate compromised credentials immediately (highest priority)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For public repositories, consider full history rewrite using:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"git filter-repo","type":"text","marks":[{"type":"code_inline"}]},{"text":" (recommended): ","type":"text"},{"text":"git filter-repo --path-glob '*.env' --invert-paths","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BFG Repo-Cleaner: ","type":"text"},{"text":"bfg --delete-files credentials.json","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Force-push cleaned history: ","type":"text"},{"text":"git push --force","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Notify all contributors to rebase/re-clone","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/remediation_guide.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for detailed procedures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document incident in security audit log","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Issue: Custom Secret Patterns Not Detected","type":"text"}]},{"type":"paragraph","content":[{"text":"Symptoms","type":"text","marks":[{"type":"strong"}]},{"text":": Organization-specific secrets not caught by default rules","type":"text"}]},{"type":"paragraph","content":[{"text":"Solution","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Develop regex pattern: Test at regex101.com with sample secrets","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add custom rule to ","type":"text"},{"text":".gitleaks.toml","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[[rules]]\nid = \"custom-secret-id\"\ndescription = \"Description\"\nregex = '''your-pattern-here'''\nsecretGroup = 1 # Capture group containing actual secret","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test pattern: ","type":"text"},{"text":"gitleaks detect --config .gitleaks.toml -v --no-git","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Consider entropy threshold if pattern is ambiguous:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[[rules.Entropies]]\nMin = \"3.5\"\nMax = \"7.0\"\nGroup = \"1\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate with known true positives and negatives","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Advanced Configuration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Entropy-Based Detection","type":"text"}]},{"type":"paragraph","content":[{"text":"For secrets without clear patterns, use Shannon entropy analysis:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[[rules]]\nid = \"high-entropy-strings\"\ndescription = \"High entropy strings that may be secrets\"\nregex = '''[a-zA-Z0-9]{32,}'''\nentropy = 4.5 # Shannon entropy threshold\nsecretGroup = 0","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Composite Rules (v8.28.0+)","type":"text"}]},{"type":"paragraph","content":[{"text":"Detect secrets spanning multiple lines or requiring context:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"[[rules]]\nid = \"multi-line-secret\"\ndescription = \"API key with usage context\"\nregex = '''api_key[\\s]*='''\n\n[[rules.composite]]\npattern = '''initialize_client'''\nlocation = \"line\" # Must be within same line proximity\ndistance = 5 # Within 5 lines","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Global vs Rule-Specific Allowlists","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"toml"},"content":[{"text":"# Global allowlist (highest precedence)\n[allowlist]\ndescription = \"Organization-wide exceptions\"\npaths = ['''vendor/''', '''node_modules/''']\n\n# Rule-specific allowlist\n[[rules]]\nid = \"generic-api-key\"\n[rules.allowlist]\ndescription = \"Exceptions only for this rule\"\nregexes = ['''key\\s*=\\s*EXAMPLE''']","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"References","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Gitleaks Official Documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/gitleaks/gitleaks","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"OWASP A07:2021 - Identification and Authentication Failures","type":"text","marks":[{"type":"link","attrs":{"href":"https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CWE-798: Use of Hard-coded Credentials","type":"text","marks":[{"type":"link","attrs":{"href":"https://cwe.mitre.org/data/definitions/798.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CWE-259: Use of Hard-coded Password","type":"text","marks":[{"type":"link","attrs":{"href":"https://cwe.mitre.org/data/definitions/259.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CWE-321: Use of Hard-coded Cryptographic Key","type":"text","marks":[{"type":"link","attrs":{"href":"https://cwe.mitre.org/data/definitions/321.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"PCI-DSS Requirements","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.pcisecuritystandards.org/","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"SOC2 Security Criteria","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.aicpa.org/interestareas/frc/assuranceadvisoryservices/aicpasoc2report.html","title":null}}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"secrets-gitleaks","tags":["secrets","gitleaks","secret-scanning","devsecops","ci-cd","credentials","api-keys","compliance"],"author":"@skillopedia","source":{"stars":336,"repo_name":"marketplace","origin_url":"https://github.com/aiskillstore/marketplace/blob/HEAD/skills/agentsecops/secrets-gitleaks/SKILL.md","repo_owner":"aiskillstore","body_sha256":"098894263f8ed961fcfe9f9ad4d3e5d82b7f268a551f2115bc41cd49c8575cb2","cluster_key":"01d94c5b1d8558260ff6ff5dc8ec39d4e8f0c6dc374b1b5436c8e7a422bb7912","clean_bundle":{"format":"clean-skill-bundle-v1","source":"aiskillstore/marketplace/skills/agentsecops/secrets-gitleaks/SKILL.md","attachments":[{"id":"ccc7f140-ed58-525e-bf70-203c85c14c79","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ccc7f140-ed58-525e-bf70-203c85c14c79/attachment.toml","path":"assets/config-balanced.toml","size":1659,"sha256":"2393b2b0e7e85c92eb8a5ac5b3649ad3de8500b53c606d322fe1e57eb794930d","contentType":"text/plain; charset=utf-8"},{"id":"67f3da43-95aa-54bb-bf5a-f77842926496","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/67f3da43-95aa-54bb-bf5a-f77842926496/attachment.toml","path":"assets/config-custom.toml","size":5930,"sha256":"044b70c4ad746c17b843b2f850064935103c56edcc2fbdd33cb5e7671439db6c","contentType":"text/plain; charset=utf-8"},{"id":"8733a7fe-ae53-5c41-b830-27b1ccef9230","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/8733a7fe-ae53-5c41-b830-27b1ccef9230/attachment.toml","path":"assets/config-strict.toml","size":1213,"sha256":"a90e31fb17e16612006e3ea81edc1db354c78f4e06341f61b0ad48e7a3405758","contentType":"text/plain; charset=utf-8"},{"id":"6c052dbb-98d2-5f56-bb41-05d749b95486","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6c052dbb-98d2-5f56-bb41-05d749b95486/attachment.yml","path":"assets/github-action.yml","size":5960,"sha256":"cdf3ffb6245b1bd7e7bb677dff7894d75968cf4013c05de001505ec0496873a5","contentType":"application/yaml; charset=utf-8"},{"id":"6115ffe2-baf7-552f-9f60-ee1fc3350a7c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6115ffe2-baf7-552f-9f60-ee1fc3350a7c/attachment.yml","path":"assets/gitlab-ci.yml","size":6881,"sha256":"7168ecb3a89abf16eae9ac7085da3c3c145fb722d9a2995b245e2cd7e1bb1d38","contentType":"application/yaml; charset=utf-8"},{"id":"79813715-0071-56f0-9e37-343102c6a380","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/79813715-0071-56f0-9e37-343102c6a380/attachment.yaml","path":"assets/precommit-config.yaml","size":2048,"sha256":"b80493323fdb8db8c8d581307884e7633fbf31ae3c6ef7f7428928c5e3b6a254","contentType":"application/yaml; charset=utf-8"},{"id":"927e2cfa-e00a-50dd-b7c9-907bdededfcc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/927e2cfa-e00a-50dd-b7c9-907bdededfcc/attachment.md","path":"references/EXAMPLE.md","size":809,"sha256":"4d40f728ee4dce695b400d6e51100129880dc4397eb6b03ebc2bbd5250dd9e05","contentType":"text/markdown; charset=utf-8"},{"id":"794f0249-8645-5f3f-b8a8-d7b8db53352e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/794f0249-8645-5f3f-b8a8-d7b8db53352e/attachment.md","path":"references/compliance_mapping.md","size":16108,"sha256":"44c6a7ae5adfd7f61576584062f3d14121b9fa36a26e1f5ce4005a4278639394","contentType":"text/markdown; charset=utf-8"},{"id":"d97f58bd-70e6-53b3-b53d-3a2eb7a2e8b7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d97f58bd-70e6-53b3-b53d-3a2eb7a2e8b7/attachment.md","path":"references/detection_rules.md","size":9534,"sha256":"3de621fe8a6cba60607ffdf4fbf874ed2031af9a90fba81e1aa36d138eea5161","contentType":"text/markdown; charset=utf-8"},{"id":"98e85de1-a7c9-5233-91bf-5331b3c5b34d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/98e85de1-a7c9-5233-91bf-5331b3c5b34d/attachment.md","path":"references/false_positives.md","size":13938,"sha256":"137e374fc8ffc95cdb401281bf205f0dfb58a8e8893e8d71b4c32afceabcc72d","contentType":"text/markdown; charset=utf-8"},{"id":"7d75c287-c7ff-544c-ad97-aeb402cda712","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7d75c287-c7ff-544c-ad97-aeb402cda712/attachment.md","path":"references/remediation_guide.md","size":12533,"sha256":"a674e53e0c92863fa9194ccdaae2441ddb829b5171aa920746d8adc9ce71e812","contentType":"text/markdown; charset=utf-8"},{"id":"cc9d7f77-d39c-5bdd-9acb-bfc26b9652da","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/cc9d7f77-d39c-5bdd-9acb-bfc26b9652da/attachment.json","path":"skill-report.json","size":11842,"sha256":"e8e94cd3edee74829a83b7170fb59623dff1924caf231ad6e5bc3918f77f7faa","contentType":"application/json; charset=utf-8"}],"bundle_sha256":"6ae08871503843b965240ace8df65759eb1852f8f3efb2597d5d0801d654091c","attachment_count":12,"text_attachments":12,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/agentsecops/secrets-gitleaks/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"security","category_label":"Security"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"security","frameworks":["OWASP","CWE","PCI-DSS","SOC2","GDPR"],"import_tag":"clean-skills-v1","maintainer":"SirAppSec","references":["https://github.com/gitleaks/gitleaks","https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/","https://cwe.mitre.org/data/definitions/798.html"],"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.\n","dependencies":{"tools":["gitleaks","git"]}}},"renderedAt":1782987395367}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.