Bawbel Scanner

Bawbel Scanner

Static security scanner for MCP servers and agent skill files, with an OWASP AIVSS score on every finding. Never starts your MCP servers, and runs no scanned content unless you enable the optional Docker sandbox.

---

Bawbel never executes your MCP servers.

pip install "bawbel-scanner[all]"

bawbel scan ./skills/ # scan skill files bawbel ssc https://server # scan MCP server without starting it

---

Commands

---

Why Bawbel

? means not verifiable from each project's public README at the time of writing (2026-09-12). Sources for every other cell are listed in the PR description.

---

How it works

System overview

How a scan flows from your file to an AIVSS-scored finding:

  your file

| v [ Pre-processing ] code fence stripping negation context detection | v [ Stage 0: Magika ] ML content-type verification gates the text engines below if content type is dangerous | v [ Detection engines ] (run in parallel) 1a Pattern 40 regex rules, stdlib only, always on 1b YARA 39 binary/behavioral rules 1c Semgrep 41 structural rules 2 LLM semantic analysis via LiteLLM 3 Sandbox Docker behavioral sandbox | v [ Deduplication ] merge by (ave_id, line) pattern > yara > semgrep > llm > sandbox priority | v [ Toxic flow analysis ] map findings to capability tags check all pairs against 12 chain definitions | v [ ScanResult ] findings[] active findings, sorted by severity suppressed_findings[] accepted_findings[] new in v1.2.0 toxic_flows[] risk_score max(findings, toxic_flows) aivss_score OWASP AIVSS v0.8

Detection stages

Six engines run across the pipeline. Results merge before toxic flow analysis:

  Stage 0    Magika engine

ML-based content-type verification, gates the engines below pip install "bawbel-scanner[all]"

Stage 1a Pattern engine 40 regex rules, no deps, < 5ms always active

Stage 1b YARA engine 39 rules, multi-condition matching pip install "bawbel-scanner[yara]"

Stage 1c Semgrep engine 41 structural rules, multi-line context pip install "bawbel-scanner[semgrep]"

Stage 2 LLM engine semantic analysis, catches synonym attacks pip install "bawbel-scanner[llm]" + API key

Stage 3 Sandbox engine dynamic behavioral analysis in Docker BAWBEL_SANDBOX_ENABLED=true

+-----------+ All ----> | dedup | ----> findings[] results | sort | sorted by severity +-----------+ | v toxic flow analysis

---

False positive reduction

Eight layers run automatically before a finding is reported:

  file content

| v FP-1 code fence stripping ~60% reduction | content inside ` blanked before scan | v FP-2 negation context ~15% reduction | "Bad example:", "Never do this:" suppresses | v FP-3 confidence scoring ~10% reduction | docs/ examples/ paths reduce confidence | v FP-4 LLM meta-analyzer ~7% reduction | medium-confidence findings reviewed by LLM | v FP-5a inline bawbel-ignore per line | | v FP-5b block suppression per section | | v FP-5c .bawbelignore patterns per file | gitignore-style glob rules | v FP-6 justified suppression per finding requires reason + reviewer + optional expiry audit trail in accepted_findings[]

Every active finding carries a confidence field (0.0–1.0) that starts from the AVE-class baseline and is adjusted by FP-2 through FP-4 before appearing in output. confidence_band() maps it to "high" / "medium" / "low" for human display. See Evidence Lifecycle for the full pipeline.

See Suppression Guide for full details.

---

Toxic flow detection

A single fetch() call is a finding. A fetch() that retrieves credentials and then sends them to an external endpoint is an attack chain, and the two findings together are far more dangerous than either alone.

Bawbel detects these compound sequences as toxic flows. After deduplication, every finding is mapped to a capability tag. Bawbel then checks all pairs against 12 built-in chain definitions and raises a ToxicFlow when a dangerous combination is found.

Other scanners detect compound attacks too. NVIDIA SkillSpector, for example, ships a source-to-sink taint tracker (TT1-TT5) over its own AST, including a credential exfiltration chain. Bawbel's approach differs in what it operates on and what it emits: chains are composed from AVE capability tags rather than traced through an AST, so a flow is detected across natural-language instructions and configuration, not only executable code. Each flow carries a stable flow_id, its own AIVSS score, and the AVE IDs of its contributing findings.

  skill.md findings:

AVE-2026-00003 credential-read (READ ~/.ssh/id_rsa) AIVSS 6.8 MEDIUM AVE-2026-00026 data-exfil (POST to external endpoint) AIVSS 6.8 MEDIUM │ │ └───── chain ────┘ │ ▼ ToxicFlow: credential-exfiltration AIVSS 9.8 CRITICAL confidence: 0.83 (min of contributing baselines)

The toxic flow AIVSS (9.8) is higher than either individual finding (6.8), because the chain represents a complete, end-to-end exploit, not just a capability.

12 built-in chains:

Toxic flow in JSON output:

{

"flow_id": "credential-exfiltration", "title": "Credential Exfiltration Chain", "severity": "CRITICAL", "aivss_score": 9.8, "confidence": 0.83, "ave_ids": ["AVE-2026-00003", "AVE-2026-00026"], "capabilities": ["credential-read", "data-exfil"], "owasp_mcp": ["MCP06", "MCP07"], "remediation": "Remove credential access. Block egress to untrusted endpoints." }

confidence is min(baseline confidence) across the contributing fi