Overview

Astra secret scan utilizes gitleaks binary at it's core for secret detection. There is a possibility to give customized configuration for gitleaks. Custom configuration can be made utilized for scenarios like:

1. Whitelisting certain files from scanning

2. Whitelisting secret patterns

3. Adding custom detection rules

Guideline

One should be aware of following set of guidelines while opting for custom configurations:

1. We use an extended config model (via [extend] or useDefault = true) so that your custom config.toml does not override the built-in Gitleaks defaults. This ensures future updates to default rules still apply.

2. Your custom config should merge with the defaults, not discard them.

3. Whitelists (“allowlist”) and ignore rules should be carefully scoped—not too broad—so you don’t accidentally skip real leaks.

4. Always validate your config.toml with gitleaks detect --config path/to/config.toml --verbose to confirm it behaves as expected.

Core Sections of the Custom Config

A typical extended config.toml will include:

• [extend] (or useDefault = true) to inherit defaults

• [allowlist] (global allowlist)

• [[rules]] entries for custom or overridden detection rules

• Within each [[rules]], optional rules.allowlist blocks to locally suppress false positives

Below is a full example of custom config.toml, with detailed inline comments.

# Title of this custom ruleset
title = "Company Extended Gitleaks Configuration"

# Extend the default (built-in) Gitleaks configuration
[extend]
# Option A: useDefault = true ( newer versions support this )  
useDefault = true
# Option B: Or specify path to the default config (if customizable in your setup)
# path = "/gitleaks.toml"

# -----------------------------
# 1. Global allowlist (whitelist files and secret patterns)
# -----------------------------
[allowlist]
description = "Global allowlist: skip scanning these files or patterns"

# Whitelist file paths or directories via regexes
# These files will not be scanned (or secrets in them ignored)
paths = [
  # Example: do not scan `.env.local` files
  '''.*\.env\.local$''',
  # Example: skip test fixture files
  '''^tests/fixtures/.*$''',
  # Example: skip README or markdown docs
  '''^docs/.*\.md$'''
]

# Whitelist specific secret patterns (regex) globally
regexes = [
  # Example: allow a known placeholder API key (fake) used in docs
  '''FAKE_API_KEY_1234567890''',
  # Example: allow known rotated secrets (old ones)
  '''OLD_SECRET_[A-F0-9]{16}'''
]

# Optionally, target whether these regexes match entire secret or substring
# Default behavior is `match` for full match; you can override:
regexTarget = "match"  # or "line"

# -----------------------------
# 2. Custom rules: define new detection patterns
# -----------------------------

# Example: a rule to catch "SuperSecret" tokens in your app
[[rules]]
id = "company_super_secret"
description = "Company-specific SuperSecret token"
# Regex must be a TOML literal; wrap in triple single quotes
regex = '''(?i)supersecret_[A-Za-z0-9]{24}'''
# Optionally, specify which capture group yields the secret
secretGroup = 1
tags = ["company", "secret", "custom"]

# Local allowlist within this rule (to suppress false positives)
[rules.allowlist]
description = "Allow dummy token in tests"
regexes = [
  '''supersecret_dummytoken123456'''
]
# You can also allow by path:
paths = [
  '''tests/.*''',
  '''docs/.*'''
]

# Example: override or extend an existing rule (like generic API key)
[[rules]]
id = "generic_api_key"
description = "Extended generic API key detection"
# If using extend/default, this is a supplement (not override) unless rule id matches
regex = '''(?i)(api[_-]?key|token)[=:][A-Za-z0-9\-_]{16,64}'''
secretGroup = 0
tags = ["key", "generic"]

# You can also put a allowlist inside this override
[rules.allowlist]
description = "Allow placeholder in config"
regexes = [
  '''TOKEN_PLACEHOLDER'''
]

# -----------------------------
# 3. Whitelist 3 specific files from scanning (repeat for clarity)
# (these would be redundant if already whitelisted above)
# -----------------------------
# You can also combine in `paths` above, but we repeat here for clarity:
[allowlist]
paths += [
  '''config/secrets.yaml''',
  '''scripts/setup_env.sh''',
  '''.gitleaks.ignore'''
]

Explanation of the Key Sections & Why

[extend] / useDefault = true

• This instructs Gitleaks to merge your custom config with the default built-in rules, rather than replace them entirely.

• If you omit this, your config would override all defaults, meaning many built-in secret patterns would be lost.

[allowlist] (global)

• A global allowlist suppresses detection in entire files or patterns you trust (e.g. test fixtures, docs).

• Use paths to skip files/folders.

• Use regexes to skip known false-positive secret strings.

• regexTarget controls how regex matching is applied (match = full secret, line = substring).

[[rules]]

• Each block is a rule to detect a secret pattern (via its regex).

• id must be unique.

• secretGroup indicates which capture group holds the secret.

• tags help classify the secret (e.g. "key", "token").

• A nested [rules.allowlist] can suppress false positives only for that rule, using paths or regexes.

Whitelisting specific files

• Using paths under global allowlist is the standard way to exclude entire files from scanning.

• You can repeat in local rule allowlists if you only block them for a specific rule.

How do I create a custom config and make Astra Secret Scanner to consume the config?

1. Create a .toml file (e.g. .astra-secret-rules.toml) in your repository root.

2. Define your organization-specific regex rules, allowlists, and secret detectors.

3. Set the environment variable ASTRA_SECRET_SCAN_CONFIG_PATH to the relative path of this file inside your repo.

Example:

export ASTRA_SECRET_SCAN_CONFIG_PATH=".astra-secret-rules.toml"

This ensures your team can enforce policies specific to your environment (e.g., custom API key formats, internal token patterns).