Skip to main content

What is BouncerFox?

BouncerFox is an open-source Go CLI that scans AI agent configuration files for security vulnerabilities, quality issues, and compliance violations. All scanning runs offline. Code never leaves your machine.

As teams adopt AI agents (Claude Code, Cursor, Copilot, Gemini, custom agents), the configuration files that control them become a new attack surface that existing security tools ignore. BouncerFox fills that gap with deterministic, rule-based scanning that integrates into your CI/CD pipeline as a PR merge gate.

Why It Matters​

AI agent config files are a new attack surface that SAST, SCA, and secret scanners do not cover. Real attacks are already happening:

  • Rules File Backdoor (Pillar Security, March 2025) -- .cursorrules and similar instruction files can be poisoned with hidden directives that cause AI agents to generate vulnerable code. The attack uses invisible Unicode characters to hide instructions from human reviewers while LLMs still process them. BouncerFox detects the invisible character vector with SEC_004.
  • MCP supply chain attacks -- security researchers filed over 30 CVEs targeting MCP servers in early 2026, including CVE-2025-6514 (CVSS 9.6, remote code execution in mcp-remote, 437K+ downloads). Unpinned MCP packages in .mcp.json let compromised versions install silently. BouncerFox flags unpinned packages with SEC_014 and plain HTTP endpoints with SEC_016.
  • Agent config as executable surface -- configuration files like .claude/settings*.json control which shell commands agents can run, which hooks execute automatically, and which MCP servers connect. Check Point Research demonstrated RCE and API token exfiltration through Claude Code project files (CVE-2025-59536). BouncerFox checks for unrestricted Bash, shell injection in hooks, and credential exfiltration patterns.

BouncerFox does not detect all forms of prompt injection or malicious instructions. It catches specific, deterministic patterns -- hardcoded secrets, invisible characters, dangerous commands, supply chain misconfigurations -- with no AI in the scanning loop. See the full rules reference for what is covered.

What It Scans​

BouncerFox recognizes 15 file types across the major AI-agent ecosystems:

File TypePath / Pattern
Skill definitionsSKILL.md (YAML frontmatter)
Claude context filesCLAUDE.md
Local Claude context filesCLAUDE.local.md
Agent definitions.claude/agents/*.md
Claude settings.claude/settings*.json (permissions, hooks, MCP)
Modular rules.claude/rules/**/*.md (optional paths frontmatter)
MCP server config.mcp.json
LSP server config.lsp.json
Plugin hookshooks/hooks.json
Plugin manifests.claude-plugin/plugin.json
Cursor AI instructions.cursorrules
Windsurf AI instructions.windsurfrules
GitHub Copilot instructions.github/copilot-instructions.md
Legacy command definitions.claude/commands/*.md
Gemini agent definitionsAGENTS.md

What It Detects​

BouncerFox ships with 35 built-in rules across four categories:

CategoryID PrefixRulesExamples
SecuritySEC16Secrets, destructive commands, reverse shells, credential exfiltration, external URLs, invisible unicode, data URIs, high-entropy strings
QualityQA10Missing descriptions, empty bodies, invalid names, oversized files
ConfigCFG8Unrestricted Bash, wildcard permissions, shell injection in hooks, hook review, broad permission flags
Prompt SafetyPS1Hidden HTML comments containing instructions

Every finding includes a severity level: info, warn, high, or critical.

How It Works​

Developer pushes PR
  -> GitHub Action runs BouncerFox
  -> Findings reported with severity (info / warn / high / critical)
  -> PR blocked if findings exist above threshold

BouncerFox is deterministic. No AI in the scanning loop. Every finding is traceable to a specific rule, line number, and file.

Next Steps​