cosmos-vulnerability-scanner

Cosmos 脆弱性スキャナー

目的

Cosmos SDK モジュールと CosmWasm コントラクトをスキャンし、チェーンの停止、コンセンサス障害、または資金の損失につながる脆弱性を検出します。脆弱性カテゴリごとに特化したスキャンエージェントを並列で起動し、各エージェントは検出結果をメインスキルに返します。メインスキルはそれらを個別の Markdown ファイルとして出力ディレクトリに書き込みます。

出力ディレクトリ：デフォルトは .bughunt_cosmos/ です。ユーザーのプロンプトで別のディレクトリが指定された場合は、そちらを使用してください。

使用する場面

• Cosmos SDK モジュール（カスタム x/ モジュール）の監査
• CosmWasm スマートコントラクトのレビュー
• Cosmos チェーンのローンチ前セキュリティ評価
• チェーン停止インシデントの調査

使用しない場面

• Cosmos SDK を使用しない、純粋な Solidity/EVM の監査 — Solidity 専用ツールを使用してください
• CometBFT コンセンサスエンジン内部 — これは SDK モジュールを対象としており、コンセンサスレイヤー自体は対象外です
• ブロックチェーンのコンテキストを伴わない、一般的な Go コードレビュー
• コンセンサス上重要ではない Cosmos SDK アプリケーションロジック（例：CLI コマンド、REST エンドポイント）
• カスタム SDK モジュールのないチェーンにおける CosmWasm コントラクトのみの監査 — CosmWasm のチェックリスト項目のみを使用してください

重要な原則

1. コンセンサスパスが最重要です — チェーンの停止や資金損失につながるバグは、コンセンサス上重要な実行パス（BeginBlock、EndBlock、FinalizeBlock、msg_server ハンドラー、AnteHandler）上にある場合にのみ問題となります。報告する前に、検出事項がコンセンサスから到達可能であることを必ず確認してください。
2. 状態の不一致 = チェーン停止です — バリデーター間で異なる状態ルートが計算されるような非決定性があると、チェーンは停止します。すべてのバリデーターに同時に影響するため、これは最も重大な脆弱性クラスです。
3. バージョンを確認してください — Cosmos SDK ではメジャーバージョン間で破壊的変更があります（v0.47 では GetSigners が削除され、v0.50 では ABCI 2.0 が追加され、v0.53 では ValidateBasic が非推奨になりました）。パターンを適用する前に、必ず go.mod のバージョンを確認してください。
4. 誤検知は監査時間の無駄につながります — CLI コマンド内の map の反復処理はコンセンサスバグではありません。クエリハンドラーでのパニックによってチェーンが停止することもありません。問題を指摘する前に、実行コンテキストを確認してください。
5. バグはモジュール間の相互作用に潜んでいます — 最も重大な検出事項（IBC の再入可能性、EVM/Cosmos の状態不一致、authz の権限昇格）は、単一のモジュール内のバグではなく、モジュール間の相互作用に関わるものです。

スキャンのワークフロー

フェーズ 1：調査（同期）

入力：ユーザーが指定する対象コードベースのパスです。コードベースには Go ソース（例：x/ モジュール、go.mod）または cosmwasm_std を使用する Rust コントラクトが含まれます。

DISCOVERY.md の全内容をプロンプトとして使用し、同期サブエージェント（Agent ツール）を実行します。エージェントは次の作業を行う必要があります。

1. Discovery ワークフローに従って対象コードベースを調査する
2. CLAUDE.md の全内容（技術インベントリと脅威モデル）を応答に含める
3. 以下のフィールドを正確に含む、構造化された要約を返す

PLATFORM: pure-cosmos | evm | wasm        (pick one; if multiple, comma-separated)
IBC_ENABLED: true | false
SDK_VERSION: <version from go.mod>
IBC_GO_VERSION: <version from go.mod, or "n/a">
CUSTOM_MODULES: <comma-separated list of x/* modules>

サブエージェントの応答後、メインスキルであるあなたが CLAUDE.md を対象リポジトリのルートに書き込みます。そのパスと調査で得た値を保存してください。これらはフェーズ 2 で使用します。

終了条件：メインスキルによって CLAUDE.md が書き込まれていること。PLATFORM、IBC_ENABLED、SDK_VERSION、IBC_GO_VERSION、CUSTOM_MODULES が取得されていること。

フェーズ 2：並列脆弱性スキャン

最大限の並列性を確保するため、1 つのメッセージでスキャンエージェントを起動します。以下のエージェントプロンプトテンプレートを使用し、各エージェントに参照ファイルを指定してください。サブエージェントに必要なのは読み取りアクセス（Grep、Glob、Read）のみです。結果は応答で返され、メインスキルがファイルを書き込みます。

次の 3 つのエージェントは必ず起動してください：

エージェント名	参照ファイル	対象範囲
core-scanner	VULNERABILITY_PATTERNS.md	§1-9：非決定性、ABCI、署名者、検証、ハンドラー、Ante セキュリティ
state-scanner	STATE_VULNERABILITY_PATTERNS.md	§11-23：記録処理、銀行、ページネーション、イベント、トランザクションの再実行、ガバナンス、算術、エンコーディング、非推奨モジュール
advanced-scanner	ADVANCED_VULNERABILITY_PATTERNS.md	§24-27：ストレージキー、コンセンサス検証、サーキットブレーカー、暗号技術

条件に応じて起動してください（同じ並列メッセージ内で）：

エージェント名	条件	参照ファイル
evm-scanner	PLATFORM に evm が含まれる	EVM_VULNERABILITY_PATTERNS.md
ibc-scanner	IBC_ENABLED が true	IBC_VULNERABILITY_PATTERNS.md
cosmwasm-scanner	PLATFORM に wasm が含まれる	COSMWASM_VULNERABILITY_PATTERNS.md

エージェントプロンプトテンプレート

各エージェントのプロンプトを作成する際、{REFERENCE_FILE_PATH} を参照ファイルのフルパス（{baseDir}/resources/ 配下）に置き換え、{CLAUDE_MD_PATH} をフェーズ 1 で作成した CLAUDE.md のパスに置き換えてください：

Perform a very thorough security scan of a Cosmos SDK codebase for specific vulnerability patterns.

CONTEXT:
Read {CLAUDE_MD_PATH} for codebase context (SDK version, modules, threat model, key files).

PATTERNS:
Read {REFERENCE_FILE_PATH} — it contains numbered vulnerability patterns. For EACH pattern:
1. Read the detection patterns and "What to Check" items
2. Use Grep and Glob to search the target codebase for each pattern
3. When a match is found, Read surrounding code to verify it's on a consensus-critical path (BeginBlock, EndBlock, FinalizeBlock, msg_server handlers, AnteHandler)
4. Classify severity per the guidelines below

RULES:
- Consensus path only: Only flag code reachable from consensus-critical execution. CLI/query/test code is NOT a finding.
- Check SDK version in go.mod before applying patterns (v0.47 removed GetSigners, v0.50 added ABCI 2.0, v0.53 deprecated ValidateBasic).
- Always use the Grep tool for searches, not bash grep. The reference file contains search patterns — use them directly with the Grep tool.
- Ignore cross-references to other resource files (e.g., links to IBC or COSMWASM patterns). Those patterns are covered by other scanning agents.
- Reject these rationalizations:
  - "ValidateBasic catches this" — deprecated and facultative since SDK v0.53
  - "Behind governance, so safe" — governance proposals can be malicious
  - "IBC counterparty is trusted" — any chain can open a channel
  - "Panic can't happen, input is validated" — trace the full call chain
  - "Rounding error is only a few tokens" — compounds over time, can be looped
  - "EVM precompile handles rollback" — many have incomplete rollback

SEVERITY:
- Critical (fund loss): signer mismatch, broken bookkeeping, AnteHandler bypass, bank keeper misuse, IBC token inflation, EVM/Cosmos desync, Merkle proof forgery, arithmetic overflow
- High (chain halt): non-determinism, ABCI panics, slow ABCI, non-deterministic IBC acks, consensus gaps, CacheContext event leak
- Medium (DoS): unbounded pagination, tx replay, missing validation, governance spam, rate limiting, circuit breaker bypass, storage key collisions
- Low (logic): rounding errors, stub handlers, event override, module ordering

OUTPUT — RETURN FORMAT:
Do NOT write any files. Return ALL findings and the summary in your response.

For each pattern, return one of:
  §NUM PATTERN_NAME: Not applicable — [one-line reason]
  §NUM PATTERN_NAME: FINDING (followed by the finding block below)

For each finding, include the full content using this template:

FINDING_FILE: {SEVERITY}-s{SECTION_NUM}-{kebab-description}.md
## [SEVERITY] Title
**Location**: `file:line`
**Description**: What the bug is and why it matters
**Vulnerable Code**: [snippet]
**Attack Scenario**: [numbered steps]
**Recommendation**: How to fix
**References**: [links to relevant advisories or building-secure-contracts]

You MUST report on ALL patterns in the reference file — do not skip any.

終了条件：すべてのスキャンエージェントが応答し、各エージェントが参照ファイル内のすべてのパターンについて報告していること。

フェーズ 3：検出結果の書き込み

すべてのスキャンエージェントから応答があった後、出力ディレクトリ（デフォルトは .bughunt_cosmos/）に検出結果ファイルを書き込みます：

1. 各エージェントの応答から FINDING_FILE: ブロックを解析します
2. 各検出結果について、FINDING_FILE: に記載されたファイル名を使って、内容を {OUTPUT_DIR}/{filename} に書き込みます
3. 出力ディレクトリが存在しない場合は、先に作成します

フェーズ 4：完全性の検証

すべての検出結果を書き込んだ後、すべてのパターンが評価されていることを確認します：

1. 各エージェントから返された要約行（§NUM エントリー）を集めます
2. パターン数を想定数と照合します：
   • core-scanner：8 パターン（§1-9、§8 のレガシー専用項目を除く）
   • state-scanner：13 パターン（§11-23）
   • advanced-scanner：4 パターン（§24-27）
   • evm-scanner（起動した場合）：10 パターン（§1-10）
   • ibc-scanner（起動した場合）：16 パターン（§1-16）
   • cosmwasm-scanner（起動した場合）：3 パターン（§1-3）
3. 要約に含まれていないパターンがあれば、それを示して該当エージェントに再度プロンプトを送ります
4. *.md に対する Glob を実行し、出力ディレクトリに書き込まれた検出結果ファイルをすべて一覧表示します

終了条件：すべてのパターンが確認されていること。検出結果ファイルがユーザー向けに一覧表示されていること。

---

成功基準

• 技術的なインベントリと脅威モデルを網羅した Discovery CLAUDE.md が作成されている
• すべてのスキャンエージェントが完了し、参照ファイル内のすべてのパターンについて報告している
• パターン数が想定数と照合されている（パターンの見落としがない）
• すべての検出結果が個別の Markdown ファイルとして出力ディレクトリに書き込まれている
• 各検出結果ファイルに、重大度、場所、脆弱なコード、攻撃シナリオ、推奨事項が含まれている

リソース

• 探索とCLAUDE.md: DISCOVERY.md
• コアパターン（§1-9）: VULNERABILITY_PATTERNS.md
• 状態とモジュールのパターン（§11-23）: STATE_VULNERABILITY_PATTERNS.md
• 高度なパターン（§24-27）: ADVANCED_VULNERABILITY_PATTERNS.md
• IBCの脆弱性: IBC_VULNERABILITY_PATTERNS.md
• CosmWasmの脆弱性: COSMWASM_VULNERABILITY_PATTERNS.md
• EVMの脆弱性: EVM_VULNERABILITY_PATTERNS.md
• 安全なコントラクトの構築: building-secure-contracts/not-so-smart-contracts/cosmos/
• Cosmos SDKドキュメント: https://docs.cosmos.network/
• Cosmos SDK向けCodeQL: https://github.com/crypto-com/cosmos-sdk-codeql