cosmos-vulnerability-scanner

# Cosmos Vulnerability Scanner

## Purpose

Scan Cosmos SDK modules and CosmWasm contracts for vulnerabilities that cause chain halts, consensus failures, or fund loss. Spawns parallel scanning agents — each specializing in a vulnerability category — that return findings to the main skill, which then writes them as individual markdown files to an output directory.

**Output directory**: defaults to `.bughunt_cosmos/`. If the user specifies a different directory in their prompt, use that instead.

## When to Use

- Auditing Cosmos SDK modules (custom `x/` modules)
- Reviewing CosmWasm smart contracts
- Pre-launch security assessment of Cosmos chains
- Investigating chain halt incidents

## When NOT to Use

- Pure Solidity/EVM audits without Cosmos SDK — use Solidity-specific tools
- CometBFT consensus engine internals — this covers SDK modules, not the consensus layer itself
- General Go code review with no blockchain context
- Cosmos SDK application logic that is not consensus-critical (e.g., CLI commands, REST endpoints)
- CosmWasm contract-only audits on chains without custom SDK modules — use the CosmWasm checklist items alone

## Essential Principles

1. **Consensus path is king** — A bug only matters for chain halt/fund loss if it's on the consensus-critical execution path (BeginBlock, EndBlock, FinalizeBlock, msg_server handlers, AnteHandler). Always verify a finding is reachable from consensus before reporting it.
2. **State divergence = chain halt** — Any non-determinism that causes validators to compute different state roots will halt the chain. This is the highest-severity class because it affects all validators simultaneously.
3. **Check the version** — Cosmos SDK has breaking changes across major versions (v0.47 removed GetSigners, v0.50 added ABCI 2.0, v0.53 deprecated ValidateBasic). Always check `go.mod` versions before applying patterns.
4. **False positives waste audit time** — A map iteration in a CLI command is not a consensus bug. A panic in a query handler does not halt the chain. Verify the execution context before flagging.
5. **Cross-module interactions are where bugs hide** — The most severe findings (IBC reentrancy, EVM/Cosmos state desync, authz escalation) involve interactions between modules, not bugs within a single module.

## Scanning Workflow

### Phase 1: Discovery (synchronous)

**Entry**: Target codebase path provided by user. Codebase contains Go source (e.g., `x/` modules, `go.mod`) or Rust contracts with `cosmwasm_std`.

Run a **synchronous subagent** (Agent tool) with the full contents of [DISCOVERY.md](resources/DISCOVERY.md) as its prompt. The agent must:

1. Follow the Discovery workflow to explore the target codebase
2. Return the full CLAUDE.md content (the technical inventory and threat model) in its response
3. Return a structured summary with exactly these fields:

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

After the subagent returns, **you** (the main skill) Write the CLAUDE.md to the target repo root. Save its path and the discovery values — these feed into Phase 2.

**Exit**: CLAUDE.md written by main skill. PLATFORM, IBC_ENABLED, SDK_VERSION, IBC_GO_VERSION, and CUSTOM_MODULES captured.

### Phase 2: Parallel Vulnerability Scan

Spawn scanning agents **in a single message** for maximum parallelism. Use the Agent Prompt Template below, filling in the reference file for each agent. Subagents only need read access (Grep, Glob, Read) — they return findings in their response and the main skill writes the files.

**Always spawn these 3 agents:**

| Agent Name | Reference File | Scope |
|------------|---------------|-------|
| `core-scanner` | `VULNERABILITY_PATTERNS.md` | §1-9: non-determinism, ABCI, signers, validation, handlers, ante security |
| `state-scanner` | `STATE_VULNERABILITY_PATTERNS.md` | §11-23: bookkeeping, bank, pagination, events, tx replay, governance, arithmetic, encoding, deprecated modules |
| `advanced-scanner` | `ADVANCED_VULNERABILITY_PATTERNS.md` | §24-27: storage keys, consensus validation, circuit breaker, crypto |

**Spawn conditionally (in the same parallel message):**

| Agent Name | Condition | Reference File |
|------------|-----------|---------------|
| `evm-scanner` | PLATFORM includes `evm` | `EVM_VULNERABILITY_PATTERNS.md` |
| `ibc-scanner` | IBC_ENABLED is `true` | `IBC_VULNERABILITY_PATTERNS.md` |
| `cosmwasm-scanner` | PLATFORM includes `wasm` | `COSMWASM_VULNERABILITY_PATTERNS.md` |

#### Agent Prompt Template

Construct each agent's prompt by replacing `{REFERENCE_FILE_PATH}` with the full path to the reference file (under `{baseDir}/resources/`) and `{CLAUDE_MD_PATH}` with the path to the CLAUDE.md written in Phase 1:

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