These files are the new attack surface and nobody is scanning them.

The Problem​

Think about what lives in a typical CLAUDE.md:

• Instructions that shape agent behavior
• References to API endpoints and internal systems
• Tool access permissions and filesystem paths
• Implicit trust boundaries that are never validated

Now consider .mcp.json. It defines which MCP servers an agent connects to, what tools they expose, and what permissions they have. A single mcp__* wildcard in allowedTools gives an agent unrestricted access to all tools on a server.

Traditional security scanners (SAST, SCA, secret detection) weren't built for this. They scan code, not agent instructions. They check dependencies, not MCP server trust chains. They don't understand that a Markdown file can be a security-critical configuration.

Introducing BouncerFox​

BouncerFox is an open-source Go CLI that deterministically scans AI agent config files for security and governance issues. All scanning runs offline. Code never leaves your machine.

bouncerfox scan .

It runs 35 built-in detection rules across four categories:

• Security (SEC). Hardcoded secrets, destructive commands, reverse shells, credential exfiltration, external URLs, invisible unicode, high-entropy strings.
• Quality (QA). Missing descriptions, empty skill bodies, invalid names, oversized files.
• Config (CFG). Unrestricted Bash in allowedTools, wildcard MCP permissions, shell injection in hooks, broad permission flags.
• Prompt Safety (PS). Hidden HTML comments containing instructions.

Every finding is deterministic, traceable to a specific rule and line number, and tagged with a severity level (info, warn, high, critical).

Why Deterministic First?​

AI-powered scanning is on the roadmap, but the core scanner is intentionally rule-based. Here's why:

1. Auditability. Every finding maps to a rule ID. You can explain why a PR was blocked.
2. Speed. Scans complete in milliseconds, not seconds. No API calls, no tokens burned.
3. Reliability. No false positives from model hallucination. A rule either matches or it doesn't.
4. CI/CD fit. Deterministic scanners slot into merge gates without flakiness.

Semantic scanning (using embeddings to detect subtler risks) will augment this foundation, not replace it.

Use It as a PR Merge Gate​

BouncerFox is built to run in CI/CD. Add it as a GitHub Action and block PRs that introduce risky agent configurations:

name: BouncerFox Scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bouncerfox/cli@v0
        with:
          path: .
          format: sarif
          severity: warn

Custom Rules​

Define project-specific detection rules in .bouncerfox.yml without writing Go code. The custom rule compiler supports 19 match primitives including pattern matching, field checks, size limits, and logic combinators. All patterns use RE2 regex. See the custom rules guide.

What's Next​

BouncerFox is open source and actively developed. Here's what's coming:

• BouncerFox Platform. Org-level governance with centralized rule config, finding history, enforcement policies, and cross-repo analytics. The CLI already has connected mode built in. Set BOUNCERFOX_API_KEY when the platform launches and it activates automatically.
• Semantic AI scanning. Embedding-based detection for subtle misconfigurations that rules can't catch.

Star the repo, try it on your project, and let us know what you find.

Get started in 2 minutes | GitHub repo