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

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

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

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

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

• 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 as its prompt. The agent must:

• Follow the Discovery workflow to explore the target codebase

• Return the full CLAUDE.md content (the technical inventory and threat model) in its response

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

Exit: All scanning agents returned. Each reported on every pattern in their reference file.

Phase 3: Write Findings

After all scanning agents return, write finding files to the output directory (default .bughunt_cosmos/ ):

• Parse each agent's response for FINDING_FILE: blocks

• For each finding, Write the content to {OUTPUT_DIR}/{filename} using the filename from FINDING_FILE:

• Create the output directory first if it doesn't exist

Phase 4: Verify Completeness

After writing all findings, verify every pattern was assessed:

• Collect the summary lines (§NUM entries) returned by each agent

• Check pattern counts against expected totals:

• core-scanner : 8 patterns (§1-9, excluding §8 legacy-only)

• state-scanner : 13 patterns (§11-23)

• advanced-scanner : 4 patterns (§24-27)

• evm-scanner (if spawned): 10 patterns (§1-10)

• ibc-scanner (if spawned): 16 patterns (§1-16)

• cosmwasm-scanner (if spawned): 3 patterns (§1-3)

• If any pattern is missing from a summary, flag it and re-prompt that agent

• List all finding files written to the output directory with a Glob for *.md

Exit: All patterns accounted for. Finding files listed for the user.

Success Criteria

• Discovery CLAUDE.md written with complete technical inventory and threat model

• All scanning agents completed and reported on every pattern in their reference file

• Pattern counts verified against expected totals (no patterns skipped)

• All findings written to output directory as individual markdown files

• Each finding file includes: severity, location, vulnerable code, attack scenario, recommendation

Resources

• Discovery & CLAUDE.md: DISCOVERY.md

• Core patterns (§1-9): VULNERABILITY_PATTERNS.md

• State & module patterns (§11-23): STATE_VULNERABILITY_PATTERNS.md

• Advanced patterns (§24-27): ADVANCED_VULNERABILITY_PATTERNS.md

• IBC vulnerabilities: IBC_VULNERABILITY_PATTERNS.md

• CosmWasm vulnerabilities: COSMWASM_VULNERABILITY_PATTERNS.md

• EVM vulnerabilities: EVM_VULNERABILITY_PATTERNS.md

• Building Secure Contracts: building-secure-contracts/not-so-smart-contracts/cosmos/

• Cosmos SDK Docs: https://docs.cosmos.network/

• CodeQL for Cosmos SDK: https://github.com/crypto-com/cosmos-sdk-codeql