cosmos-vulnerability-scanner

Cosmos 漏洞扫描器

用途

扫描 Cosmos SDK 模块和 CosmWasm 合约，查找可能导致链停止、共识失败或资金损失的漏洞。启动多个并行扫描 Agent，每个 Agent 专门检查一类漏洞，并将发现结果返回给主技能；主技能随后将其分别写入输出目录中的 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 命令中的映射遍历不是共识漏洞。查询处理程序中的 panic 不会导致链停止。标记问题前，务必确认执行上下文。
5. 漏洞往往隐藏在跨模块交互中——最严重的问题（IBC 重入、EVM/Cosmos 状态不同步、authz 权限提升）涉及模块间交互，而非单个模块内部的漏洞。

扫描工作流

阶段 1：发现（同步）

入口：用户提供目标代码库路径。代码库包含 Go 源代码（例如 x/ 模块、go.mod）或使用 cosmwasm_std 的 Rust 合约。

使用 DISCOVERY.md 的完整内容作为提示词，运行一个同步子 Agent（Agent 工具）。该 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>

子 Agent 返回后，由你（主技能）将 CLAUDE.md 写入目标仓库根目录。保存其路径和发现阶段获取的值——这些信息将用于阶段 2。

退出条件：CLAUDE.md 已由主技能写入。已记录 PLATFORM、IBC_ENABLED、SDK_VERSION、IBC_GO_VERSION 和 CUSTOM_MODULES。

阶段 2：并行漏洞扫描

在一条消息中启动扫描 Agent，以最大限度地并行处理。使用下方的 Agent 提示词模板，并为每个 Agent 填入参考文件。子 Agent 只需读取权限（Grep、Glob、Read）——它们会在回复中返回发现结果，由主技能写入文件。

始终启动以下 3 个 Agent：

Agent 名称	参考文件	范围
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：存储键、共识验证、断路器、密码学

按条件启动（在同一条并行消息中）：

Agent 名称	条件	参考文件
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

Agent 提示词模板

通过将 {REFERENCE_FILE_PATH} 替换为参考文件的完整路径（位于 {baseDir}/resources/ 下），并将 {CLAUDE_MD_PATH} 替换为阶段 1 中写入的 CLAUDE.md 路径，来构建每个 Agent 的提示词：

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.

退出条件：所有扫描 Agent 均已返回。每个 Agent 都报告了其参考文件中的所有模式。

阶段 3：写入发现结果

所有扫描 Agent 返回后，将发现结果文件写入输出目录（默认为 .bughunt_cosmos/）：

1. 从每个 Agent 的回复中解析 FINDING_FILE: 代码块
2. 对于每条发现结果，使用 FINDING_FILE: 中的文件名，将内容写入 {OUTPUT_DIR}/{filename}
3. 如果输出目录不存在，先创建该目录

阶段 4：验证完整性

写入所有发现结果后，验证每种模式均已评估：

1. 收集每个 Agent 返回的摘要行（§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. 如果摘要中缺少任何模式，标记该模式并重新提示相应 Agent
4. 使用 Glob 查找 *.md，列出写入输出目录的所有发现结果文件

退出条件：所有模式均已核对。已向用户列出发现结果文件。

---

成功标准

• 已编写发现阶段的 CLAUDE.md，包含完整的技术清单和威胁模型
• 所有扫描 Agent 均已完成，并报告了其参考文件中的每种模式
• 已根据预期总数验证模式数量（未跳过任何模式）
• 所有发现结果均已作为独立的 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