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