Connected Mode

Coming Soon

The BouncerFox platform is currently in development. Connected mode features (config pull, upload, verdicts) are built into the CLI but not yet active. The CLI runs in offline mode until the platform launches.

Connected mode will link the CLI to the BouncerFox platform for org-level governance: centralized rule config, custom rules, finding history, enforcement policies, and cross-repo analytics.

How It Works

Connected mode activates automatically when BOUNCERFOX_API_KEY is set (via environment variable or bouncerfox auth). In connected mode the CLI:

1. Pulls org-level rule config from the platform (cached locally with ETag validation), including custom rules with full match configs.
2. Compiles and executes platform custom rules alongside built-in rules.
3. Warns if the platform's rules_version differs from the CLI's built-in version.
4. Uploads findings to the platform (including PR number and skill metadata).
5. Uses the platform's verdict for the exit code.

Authentication

# Set via environment variable (recommended for CI)
export BOUNCERFOX_API_KEY=bf_xxx

# Or use the auth command (saves key locally for repeated use)
bouncerfox auth

The environment variable takes precedence over the stored credential. The bouncerfox auth command opens a browser to the platform dashboard, then prompts you to paste your API key (input is hidden). The key is saved to ~/.config/bouncerfox/credentials.

Verdicts

In connected mode, the platform returns one of four verdicts:

Verdict	Meaning	Exit Code
pass	No findings	0
informational	Org has no enforcement configured	0
warn	Findings below enforcement threshold	0
fail	Findings match enforcement rules	1

GitHub Integration

In connected mode, the platform owns the GitHub Check Run lifecycle. The CLI does not post Check Runs or PR comments. This allows the platform to update Check Runs when findings are acknowledged. The --github-comment flag is ignored. No GITHUB_TOKEN is needed.

# CI setup for connected mode
steps:
  - uses: actions/checkout@v4
  - uses: bouncerfox/cli@v0
    env:
      BOUNCERFOX_API_KEY: ${{ secrets.BOUNCERFOX_API_KEY }}

Config Caching

Platform config is cached locally with ETag-based validation. In CI (GITHUB_ACTIONS or CI env var detected), the cache is always skipped to ensure fresh config.

To force a fresh pull locally:

bouncerfox scan . --no-cache

To clear the cache entirely:

bouncerfox config refresh

Offline Behavior

If the platform is unreachable during upload, the CLI falls back based on the --offline-behavior flag:

Value	Behavior
fail-closed	Exit 2 (scanner error). Default in CI.
warn	Fall back to local exit logic. Default locally.

Special platform responses:

• 409 (superseded): A newer commit exists for this PR. The CLI warns and falls back to local exit logic.
• 402 (payment required): Subscription lapsed. The CLI warns and falls back to local exit logic.

Privacy

What gets sent: rule IDs, severities, file paths, line numbers, fingerprints, scan metadata (duration, file count, profile).

Never sent: file contents, code snippets, matched secret values, environment variables.

Use --dry-run-upload to preview the exact payload before it is sent:

bouncerfox scan . --dry-run-upload

Use --strip-paths to send filenames only (no directory paths):

bouncerfox scan . --strip-paths

Use --anonymous to strip all identifying info (no target, commit, or branch info):

bouncerfox scan . --anonymous

Environment Variables

Variable	Description
BOUNCERFOX_API_KEY	Platform API key. Required for connected mode.
BOUNCERFOX_PLATFORM_URL	Platform API base URL (default: https://api.bouncerfox.dev)