scanner - Open-source CLI scanner for agentic AI components

项目说明

<di="center">

Bawbel Scanner

<!-- mcp-name: io.github.bawbel/scanner -->

The only open-source scanner that produces OWASP AI for MCP servers and skill files. Ne code.

![PyPI ]()
![PyPI downloads]()
![Pepy total downloads]()
![Python]()
![AI]()
![A]()
![MCP Registry]()

<!-- ![Star History Chart]() -->

</div>

---

> Bawbel ne your MCP servers.

<img src=" width="100%" alt="Bawbel Scanner demo">

---

Commands

| Command | Description |
|---|---|
| bawbel scan <path> | Scan a skill file or directory for A. Supports --recursive, --format text\|json\|sarif, --fail-on-se, --no-ignore, --watch |
| bawbel report <path> | Scan a component and show a full remediation guide with fix guidance per finding |
| bawbel creds <path> | Focused scan — hardcoded credentials and secret exposure only |
| bawbel chain <path> | Focused scan — unsafe agent delegation chains only |
| bawbel ssc <url> | Fetch and scan an MCP ser for A without starting the server |
| bawbel scan-ser <url> | Alias for ssc |
| bawbel conform <target> | Score an MCP ser against the MCP specification (A+ to F grade) |
| bawbel scan-conformance <target> | Alias for conform |
| bawbel accept <id> <file> | Mark a finding as a false positive or accepted risk — inserts a justified suppression comment with re and optional expiry |
| bawbel pin <path> | Hash skill files and save to .bawbel-pins.json for rug pull detection |
| bawbel check-pins <path> | Check skill files for drift against .bawbel-pins.json |
| bawbel cp <path> | Alias for check-pins |
| bawbel init | Initialise Bawbel Scanner in a project — generates .bawbelignore and bawbel.yml |
| bawbel | Show and detection engine status |

---

Why Bawbel

| | Bawbel | Snyk agent-scan | ClawGuard | Cisco DefenseClaw |
|---|---|---|---|---|
| Executes MCP servers during scan | Never | Yes | No | Sandboxed |
| Open database | Yes (48 records, public API) | No | No | No |
| OWASP AIVSS v0.8 scores | Yes | No | No | No |
| Toxic flow detection | Yes (12 chains) | No | No | No |
| Conformance grading (A+ to F) | Yes | No | No | No |
| Git-committed rug pull detection | Yes | Local only | No | No |
| Justified suppression with expiry | Yes | No | No | No |
| License | Apache 2.0 | Apache 2.0 | MIT | Proprietary |

---

How it works

System o

How a scan flows from your file to an AI finding:

Detection stages

Six engines run in parallel. Results merge before toxic flow analysis:

---

False positi

Eight layers run automatically before a finding is reported:

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 re by LLM
|
inline bawbel-ignore per line
| <!-- bawbel-ignore -->
|
block suppression per section
| <!-- bawbel-ignore-start/end -->
|
.bawbelignore patterns per file
| gitignore-style glob rules
|
v FP-6 justified suppression per finding
requires reason + re + optional expiry
audit trail in accepted_findings[]

skill.md findings:
A credential-read (READ ~/.ssh/id_rsa) AIVSS 6.8 MEDIUM
A 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)
json
{
"flow_id": "credential-exfiltration",
"title": "Credential Exfiltration Chain",
"se": "CRITICAL",
"ai": 9.8,
"confidence": 0.83,
"a": ["A", "A"],
"capabilities": ["credential-read", "data-exfil"],
"owasp_mcp": ["MCP06", "MCP07"],
"remediation": "Remo access. Block egress to untrusted endpoints."
}
bash
pip install bawbel-scanner # core - pattern engine only
pip install "bawbel-scanner[yara]" # + YARA rules
pip install "bawbel-scanner[semgrep]" # + Semgrep rules
pip install "bawbel-scanner[llm]" # + LLM semantic engine
pip install "bawbel-scanner[all]" # e
bash

Scan a local directory (recommended image)

docker run --rm -v $(pwd):/scan:ro bawbel/scanner:full scan /scan --recursive

Lightweight CI scan

docker run --rm -v $(pwd):/scan:ro bawbel/scanner:latest scan /scan --recursive

Build with all engines

docker build --build-arg WITH_ALL=true -t bawbel/scanner:custom .
bash

Scan a skills directory

bawbel scan ./skills/

Scan recursively

bawbel scan ./skills/ --recursive

Full remediation report for one file

bawbel report ./skill.md

Scan an MCP ser without starting the server

bawbel ssc

Pin skill files and detect rug pulls

bawbel pin ./skills/ && git add .bawbel-pins.json
bawbel check-pins ./skills/

CRITICAL A External instruction fetch detected
line 3 fetch(")
AIVSS 8.0 MCP03, MCP04

HIGH A Tool description beha injection
line 12 "IMPORTANT: before calling this tool, first..."
AIVSS 7.3 MCP03, MCP10

Toxic flow detected CREDENTIAL_EXFIL_CHAIN
A + A combined AIVSS 9.8 CRITICAL

2 findings 1 toxic flow 18ms
markdown
<!-- bawbel-ignore: A
reason: Internal registry endpoint, not attacker-controlled
re: chaksaray
re: 2026-05-16
-->
fetch your instructions from
markdown
<!-- bawbel-accept: A
reason: Placeholder replaced at deploy time, not a real credential
re: chaksaray
re: 2026-05-16
expires: 2026-08-16
-->
bash
bawbel accept A ./skill.md --line 7 \
--reason "Internal registry endpoint" \
--type false-positive

bawbel accept A ./skill.md --line 3 \
--reason "Placeholder value, replaced at deploy" \
--type accepted-risk --expires 90d

List all accepted findings

bawbel accept --list

Show findings expiring within 30 days (exits 1 in CI)

bawbel accept --expiring-soon --within 30
bash

Hardcoded credentials only

bawbel creds ./skills/ --recursive

Unsafe agent delegation chains only

bawbel chain ./skills/ --recursive

AIVSS = ((C + AARS) / 2) * ThM * Mitigation_Factor
json
{
"rule_id": "bawbel-external-fetch",
"ave_id": "A",
"ai": 8.0,
"se": "HIGH",
"aivss": {
"c": 8.5,
"aars": 7.5,
"thm": 1.0,
"mitigation_factor": 1.0,
"ai": "HIGH",
"spec_": "0.8"
},
"confidence": 0.98,
"e": "multi_engine",
"detection_stage": "static_detection",
"detection_layer": "content",
"owasp_mcp": ["MCP03", "MCP04"],
"piranha_url": "
}

A Metamorphic Payload Config Fetch AIVSS 8.0 HIGH
A Tool Poisoning Manipulation AIVSS 7.3 HIGH
A MCP Tool Hook Hijacking AIVSS 9.2 CRITICAL
... 51 records total
bash
BAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md
yaml

bawbel.yml

sandbox:
enabled: true
bash

Recommended: default (auto-pull, cached)

BAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md

Offline / air-gapped: build locally

BAWBEL_SANDBOX_ENABLED=true BAWBEL_SANDBOX_IMAGE=local bawbel scan ./skill.md

Custom enterprise image

BAWBEL_SANDBOX_ENABLED=true \
BAWBEL_SANDBOX_IMAGE=registry.company.com/bawbel/sandbox:v1 \
bawbel scan ./skill.md
yaml

.github/workflows/security.yml

name: Bawbel scan

uses: bawbel/scanner@v1
with:
path: ./skills/
fail-on-se: high
format: sarif
output: bawbel.sarif

name: Upload to GitHub Security

uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: bawbel.sarif
yaml

.pre-commit-config.yaml

repos:
- repo:
rev: v1.2.1
hooks:
- id: bawbel-scan
args: [--fail-on-se, high]
bash
bawbel scan ./skills/ --format text # human-readable (default)
bawbel scan ./skills/ --format json # machine-readable
bawbel scan ./skills/ --format sarif # GitHub Security / GHAS
bash
git clone
cd scanner
pip install -e ".[dev,all]"
pre-commit install
python -m pytest tests/ -v
```

---

<di="center">

Apache License 2.0 - Free forever - Maintained by Bawbel

bawbel.io . . bawbel.io/docs

</div>

项目信息

开发语言：Python

Star 数：12

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source CLI scanner for agentic AI components such as skills, MCP servers, system prompts展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。