Configuration

BouncerFox works with zero configuration out of the box. To customize behavior, create a .bouncerfox.yml file in your project root. You can generate one by running:

bouncerfox init

This creates a default .bouncerfox.yml with sensible settings you can adjust.

Config File Locations

BouncerFox reads configuration from two locations:

• Project config. .bouncerfox.yml in the project root (applies to that project only).
• Global config. ~/.config/bouncerfox/config.yml (applies to all projects).

Project config takes precedence over global config. See Config Merging Priority for the full resolution order.

Override the global config directory with the BOUNCERFOX_CONFIG_DIR environment variable. When --config is provided, only that file is used (global config is skipped).

Default Config Structure

# .bouncerfox.yml

profile: "recommended"  # or "all_rules"

severity_floor: warn    # info, warn, high, critical

ignore:
  - "vendor/**"
  - "**/*.generated.md"

rules:
  SEC_001:
    enabled: true
    severity: critical
    params:
      url_allowlist:
        - "https://api.example.com"
  QA_001:
    enabled: false

Profiles

Profiles control which rules are enabled by default.

Profile	Description
recommended	(default) Disables informational rules: QA_001, QA_003, QA_006, QA_008, SEC_006, CFG_006, CFG_009
all_rules	Enables every rule

Set the profile in your config file:

profile: "recommended"

Severity Floor

The severity_floor setting filters out findings below a given severity level. Valid values, from lowest to highest:

• info
• warn
• high
• critical

severity_floor: warn  # hides info-level findings

Note that critical floor rules (SEC_001, SEC_003, SEC_004) cannot be downgraded below high, regardless of configuration. These rules also ignore file_types overrides.

Per-Rule Overrides

Each rule can be individually configured:

rules:
  SEC_002:
    enabled: true
    severity: warn                  # override severity
    file_types: [skill_md, claude_md]  # narrow which file types to check
    params:
      url_allowlist:
        - "https://api.example.com"
  SEC_018:
    params:
      hex_threshold_credential: 3.0
      base64_threshold_freetext: 4.5
  QA_001:
    enabled: false                  # disable entirely

Ignore Patterns

Use gitignore-style globs to skip files or directories:

ignore:
  - "vendor/**"
  - "**/*.generated.md"
  - "plugins/marketplaces/**"

Config Merging

When both global and project configs exist, they are merged:

• Scalars (profile, severity_floor): project wins if set, otherwise global.
• Lists (ignore): combined from both (additive, deduplicated).
• Rules: deep-merged per rule ID. Project overrides specific fields, unset fields inherit from global.
• Rule params: replaced wholesale. Project params for a rule replace global params entirely.

Example. Global config sets org-wide defaults:

# ~/.config/bouncerfox/config.yml
ignore:
  - "plugins/marketplaces/**"
rules:
  SEC_002:
    params:
      url_allowlist:
        - "https://internal.corp.com"

Project config adds project-specific settings:

# .bouncerfox.yml
profile: recommended
severity_floor: warn
ignore:
  - "vendor/**"
rules:
  SEC_002:
    severity: warn

Merged result: both ignore patterns apply. SEC_002 gets warn severity from project and url_allowlist from global.

Config Merging Priority

When the same setting is defined in multiple places, the following precedence applies (highest to lowest):

1. CLI flags. Always win.
2. Platform config (connected mode). Overrides all local config when BOUNCERFOX_API_KEY is set. See Connected Mode.
3. Project config. .bouncerfox.yml in the project root.
4. Global config. ~/.config/bouncerfox/config.yml.

CLI Flags

CLI flags take the highest priority and override all config file values.

Flag	Description
--severity, -s (critical|high|warn|info)	Severity floor
--config, -c PATH	Path to config file
--max-findings N	Cap total findings (0 = unlimited)
--format, -f (table|json|sarif)	Output format
--group-by (file|rule|severity)	Group findings
--verbose, -v	Show code frames with context
--no-color	Disable colored output

Examples:

# Only show high and critical findings
bouncerfox scan . --severity high

# Output as SARIF for GitHub Security tab
bouncerfox scan . --format sarif

# Use a specific config file
bouncerfox scan . --config ./custom-config.yml

# Limit to 10 findings
bouncerfox scan . --max-findings 10

# Verbose output with code context
bouncerfox scan . --verbose

Environment Variables

Variable	Description
BOUNCERFOX_API_KEY	Platform API key. Enables connected mode (config pull, upload, verdict).
BOUNCERFOX_PLATFORM_URL	Platform API base URL (default: https://api.bouncerfox.dev)
BOUNCERFOX_CONFIG_DIR	Config directory override (default: ~/.config/bouncerfox)
BOUNCERFOX_TARGET	Override scan target identity
GITHUB_TOKEN	Required for --github-comment
NO_COLOR	Disable colors (any value)