Introduction

Astra's secret scanning feature utilizes the gitleaks binary at its core to identify sensitive information within your repositories.There is a possibility to give customized configuration for gitleaks. You can customize this process to whitelist specific files, ignore known secret patterns (false positives), or add unique detection rules tailored to your organization's internal token formats.

Prerequisites

• Access to the root directory of your repository to add configuration files.

• Ability to define environment variables within your CI/CD tool (e.g., GitHub Actions, GitLab CI).

• The ASTRA_SCAN_TYPE must be set to secret_scanning in your pipeline configuration.

Instructions

1. Create the Custom Configuration File

Create a new file in your repository root, typically named .astra-secret-rules.toml. Use a text editor to define the rules using TOML syntax, ensuring that regex patterns are wrapped in triple single quotes (''').

2. Define the Configuration Model

At the top of your file, you must instruct the scanner to merge your custom settings with the built-in defaults. Omitting this section will override all defaults, causing the scanner to lose the hundreds of standard secret patterns already built in.

• Include [extend] and set useDefault = true to merge your custom config with the built-in rules.

• Alternatively, you can specify a direct path to the default config file using path = "/gitleaks.toml" instead of useDefault = true.

[extend]# Option A: use built-in defaults (recommended)useDefault = true# Option B: specify path to the default config# path = "/gitleaks.toml"

3. Configure Allowlists (Whitelisting)

You can prevent the scanner from flagging specific files or patterns that you trust.

• Global Allowlist: Use the [allowlist] section to skip entire directories (like tests/fixtures/) or specific file types (like .md documentation) using regex paths.

• Pattern Allowlist: Use regexes within the allowlist to ignore specific strings, such as placeholder API keys used in documentation.

• regexTarget: Controls how regex matching is applied. Use "match" for full secret matching or "line" for substring matching. Defaults to "match".

• Appending Paths: Use paths += syntax to add more files to the allowlist in a separate block without overwriting previously defined paths.

[allowlist]description = "Global allowlist: skip scanning these files or patterns"paths = [  '''.*\.env\.local$''',  '''^tests/fixtures/.*$''',  '''^docs/.*\.md$''']regexes = [  '''FAKE_API_KEY_1234567890''',  '''OLD_SECRET_[A-F0-9]{16}''']regexTarget = "match"  # or "line"# Append additional paths in a separate block if neededpaths += [  '''config/secrets.yaml''',  '''scripts/setup_env.sh''',  '''.gitleaks.ignore''']

Note: Be careful not to make allowlist regexes too broad, as this could lead to the scanner accidentally skipping real credential leaks.

4. Add Custom Detection Rules

To catch internal secrets or unique identifiers, add [[rules]] blocks.

• Assign a unique id and a description for each rule.

• Define the regex to match your secret and optionally specify a secretGroup to pinpoint the sensitive string within the match.

• Use tags to classify the secret (e.g., ["company", "secret", "custom"]).

• You can add a local [rules.allowlist] inside a rule to suppress specific false positives that only apply to that single rule.

[[rules]]id = "company_super_secret"description = "Company-specific SuperSecret token"regex = '''(?i)supersecret_[A-Za-z0-9]{24}'''secretGroup = 1tags = ["company", "secret", "custom"][rules.allowlist]description = "Allow dummy token in tests"regexes = [  '''supersecret_dummytoken123456''']paths = [  '''tests/.*''',  '''docs/.*''']

Note on Rule IDs: If you use the same id as a built-in rule, your custom rule will act as a supplement rather than a replacement unless specifically configured otherwise.

5. Link the Configuration to Astra

To make the scanner consume your custom rules, you must set an environment variable in your CI/CD pipeline.

• Set ASTRA_SECRET_SCAN_CONFIG_PATH to the relative path of your file.

• Example: export ASTRA_SECRET_SCAN_CONFIG_PATH=".astra-secret-rules.toml"

Full Example Configuration

Here is a complete .astra-secret-rules.toml file combining all the sections above:

# 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'''
]

Expected Outcome

During the next pipeline run, Astra will execute the secret scan using your combined configuration. The scanner will now ignore the files you have whitelisted and report any custom secrets found directly to your Astra Dashboard.

Best Practices & Troubleshooting

• Validation: Before pushing your changes, validate your configuration file locally by running gitleaks detect --config path/to/config.toml --verbose.

• Scoping: Be careful not to make allowlist regexes too broad, as this could lead to the scanner accidentally skipping real credential leaks.

• Rule IDs: If you use the same ID as a built-in rule, your custom rule will act as a supplement rather than an override unless specifically configured otherwise.

• Missing Results: If custom rules aren't triggering, verify that the ASTRA_SECRET_SCAN_CONFIG_PATH variable is correctly pointing to the file and that the file is included in the CI build context.