# 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
# =============================================================================