Chain Vulnerability Scanner

---
name: chain-vulnerability-scanner
description: 'Use when a supported Algorand, Cairo, Cosmos SDK, Solana, Substrate, or TON codebase needs chain-specific vulnerability scanning. Returns reachability-backed findings routed to the matching ecosystem reference. Not for generic non-chain security review — route that to security-review.'
---

# Chain vulnerability scanner

A single read-only scan operation that classifies a blockchain codebase by ecosystem, loads only that ecosystem's detector catalog, and emits severity-ranked findings tied to reachable code paths. Six ecosystems are supported; each owns one flat reference file under `references/` that holds its detectors, applicability gates, tool requirements, severity distinctions, and ecosystem caveats. This file holds the shared routing, authority, procedure, cross-cutting rules, failure behavior, and output contract.

## Ecosystem routing

| Ecosystem | Source indicators | Reference file |
|---|---|---|
| Algorand | `.teal` files; `.py` importing PyTeal or Algorand SDK (`from pyteal import *`, `from algosdk import *`, `Txn`, `Gtxn`, `Global`, `InnerTxnBuilder`, `OnComplete`, `@router.method`, `@Subroutine`); `approval_program.py`/`clear_program.py`, `contract.teal`/`signature.teal`, Beaker references. | `references/algorand.md` |
| Cairo / Starknet | `.cairo` files; `Scarb.toml`; contract markers `#[contract]`, `#[storage]`, `#[external(v0)]`, `#[l1_handler]`, `#[constructor]`, `felt252`, `ContractAddress`, `get_caller_address()`, `send_message_to_l1_syscall`. Optional L1 bridge Solidity contracts for cross-layer patterns. | `references/cairo.md` |
| Cosmos SDK | Go source with Cosmos SDK `x/` modules and `go.mod`; `ibc-go`; Ethermint/EVM precompiles (`evmutil`/`feemarket`); Rust contracts using `cosmwasm_std`. | `references/cosmos-sdk.md` |
| Solana | Solana or Anchor Rust (`.rs`) program files. | `references/solana.md` |
| Substrate | Substrate FRAME pallet Rust source tree or file within a runtime. | `references/substrate.md` |
| TON | FunC or Tact source (function definitions, message handlers, `recv_internal`, `recv_external`, `op::` constants, `@interface` annotations). | `references/ton.md` |

If the codebase matches none of the indicators above, stop and report that no supported chain surface applies. Do not run any catalog. Route generic non-chain security review to `security-review` instead: chain-vulnerability-scanner loads ecosystem-specific detector catalogs for six supported blockchain ecosystems; security-review runs STRIDE and OWASP on any codebase. The split is: supported chain ecosystem → chain-vulnerability-scanner; any other codebase → security-review.

## Contract

| Field | Bound contract |
|---|---|
| Trigger | A supported Algorand, Cairo, Cosmos SDK, Solana, Substrate, or TON codebase needs a chain-specific vulnerability sweep. |
| Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. Tealer and Caracal, when already installed, run only as read-only analyzers on local source. Never install missing tools — installation is a state-changing action outside read-only authority. |
| Side effect | Severity-ranked, reachability-backed findings emitted as chat output only, each with location, evidence, impact, remediation, and validation status. |
| Done | Every applicable detector in every selected ecosystem reference is checked, and each confirmed finding carries code evidence, a reachable attack path, and remediation. |

## Inputs

- Target codebase path (required): a path containing source for one or more supported ecosystems.
- Ecosystem scope (derived): the scanner classifies every supported ecosystem present under the target path. The user MAY name a detector subset for Algorand, Cairo, Cosmos SDK, Solana, or Substrate; those ecosystems default to all detectors when omitted.
- TON category scope (required for TON): a non-empty list of categories from `references/ton.md`, or `"all"`.
- Optional severity floor (TON): if omitted, all findings are returned.
- Optional auxiliary source (Cairo): L1 bridge Solidity contracts, needed to evaluate L1-L2 patterns.
- Optional analyzers already installed: Tealer for Algorand and Caracal for Cairo. Record their absence as a coverage gap; never install them during this read-only skill.

## Shared procedure

Run these steps in order. Each ecosystem reference may attach ecosystem-specific sub-steps, detectors, and gates to steps 3, 4, and 6; this file holds only the shared spine.

1. **Classify ecosystems and applicability.** Search the supplied path for the source indicators in the routing table. Select every supported ecosystem present and name its reference file. If multiple top-level ecosystems coexist, scan each as one branch of the same invocation. A Cosmos branch uses its own discovery step to enumerate EVM, CosmWasm, and IBC sub-catalogs. If no supported surface matches, stop and report an empty-target result. **Done when:** every detected ecosystem and reference is recorded, or an empty-target result is reported.

2. **Load only selected references.** For each detected ecosystem branch, read its single named reference before scanning that branch. Do not load references for ecosystems absent from the target. Each selected reference supplies the detector list, applicability/version gates, tool commands, severity definitions, rationalization rejections, and ecosystem caveats that govern the branch. **Done when:** every selected reference is loaded and its applicability gates (e.g., Cosmos version gate, Cairo L1-bridge presence, TON scope validation) have been evaluated.

3. **Inventory trust/state/value boundaries.** Enumerate the codebase's transaction-field usage, trust boundaries, state-mutation sites, value-transfer paths, and external entry points, using the reference's detector list as the lens. Record the file list and contract/module inventory. **Done when:** the boundary inventory is recorded or an empty-target result is reported.

4. **Run source and ecosystem tools.** Invoke Tealer for Algorand `.teal` targets and Caracal for Cairo targets when already installed; capture detector output. If a tool is absent or errors, record the gap in coverage notes and proceed with the manual detector sweep from the selected reference. A tool failure never invalidates manual findings. **Done when:** tool output is captured for each applicable target or its absence/error is recorded.

5. **Confirm semantic reachability.** For every candidate finding, trace from an external entry point (ecosystem-specific: Algorand approval/smart-signature paths; Cairo `#[external(v0)]`, `#[l1_handler]`, `#[constructor]`; Cosmos consensus-critical paths `BeginBlock`/`EndBlock`/`FinalizeBlock`/`msg_server`/`AnteHandler`; Solana instruction entrypoints; Substrate dispatchables; TON message handlers) to the vulnerable statement. A match reachable only from CLI, query, or test code is not a finding — record it as not-applicable with the reason "not consensus-critical" (Cosmos) or the ecosystem's equivalent. Exclude findings that cannot be reached by any caller; mark ambiguous cases as unconfirmed observations, never promoted to confirmed findings. **Done when:** every candidate finding is traced to a reachable entry point or excluded.

6. **Apply severity rules.** Assign severity per the reference's definitions. Each ecosystem owns its own severity ladder and category-to-severity mapping; use the reference's, not a generic one. Where the reference lists rationalization rejections (Cosmos) or caveats (Cairo L1 bridge), apply them verbatim. **Done when:** every finding has a severity tag drawn from the reference.

7. **Emit normalized findings.** Rank findings by severity (Critical first, then High, then Medium, then Low, then Informational where the ecosystem defines it). For each confirmed finding emit the shared finding fields below plus any extra ecosystem fields the reference requires. Append coverage notes listing detectors checked, detectors not applicable, tool availability, and any unassessed detectors with their blocker. **Done when:** findings are ranked with evidence and remediation, plus coverage notes, and the done predicate is auditable.

## Shared finding fields

Every confirmed finding carries all of these:

- ecosystem: one of `algorand`, `cairo`, `cosmos-sdk`, `solana`, `substrate`, `ton`.
- component/path and line: file and line range (`file:line-range`), plus module/function/call-path where the ecosystem reference requires it (Substrate `module::function (lines N–M)`; Cosmos `file:line`; Solana affected files and line ranges).
- detector/category: the named detector or pattern category from the reference (e.g., Algorand "Rekeying", Solana "a. Missing signer checks", TON category letter + name).
- severity: from the reference's severity ladder.
- confidence: `confirmed`, `unconfirmed`, or `not-applicable` (for coverage notes).
- reachability: the traced entry point to vulnerable statement path, or `not-reachable` (excluded).
- evidence: verbatim vulnerable code excerpt, quoted from source.
- impact: attack scenario, numbered exploit steps, fund-loss or chain-halt description per the reference.
- remediation: concrete fix with corrected code; never "review manually" (TON refuses this; all ecosystems require a specific code change or architectural correction).
- validation status: `validated`, `unvalidated`, `partial`, or `error`, reflecting whether the finding was confirmed by tool plus manual review, manual only, or could not be fully checked.

Extra ecosystem fields retained from the source:

- Algorand: contract type (stateful application vs smart signature), transaction-field validation matrix status, Tealer availability.
- Cairo: Cairo version (1.0+ vs legacy 0), L1-bridge-contracts-present flag, Caracal availability.
- Cosmos: discovery inventory (`PLATFORM`, `IBC_ENABLED`, `SDK_VERSION`, `IBC_GO_VERSION`, `CUSTOM_MODULES`), applicable catalog list.
- Solana: vulnerability type letter (a–o), failure-mode group.
- Substrate: pattern family, call-path evidence (`module::function (lines N–M)`), completeness statement against the five families.
- TON: scope (category list), severity floor, date.

## Cross-cutting rules

- One coherent scan, not six modes. One invocation may contain one or more detected ecosystem branches. Each branch loads only its own reference and returns findings through the same shared contract. Cosmos EVM, CosmWasm, and IBC surfaces remain sub-catalogs of the Cosmos branch.
- Record missing tools; fail closed on missing version evidence. If an optional analyzer is absent, record the gap and continue with manual detectors; never install it. If version evidence required by an applicability gate is missing (e.g., Cosmos SDK version undetectable, Cairo version ambiguous), report the affected detectors as blocked rather than guessing.
- Never fabricate findings. Record a finding only when vulnerable code is located with a concrete file and line reference and traced to a reachable entry point. Ambiguous code is an unconfirmed observation, not a finding.
- Never swallow errors. A read or search failure is reported as the blocker for the affected detector; it is never silently treated as "no findings."
- Partial-result rule. Findings are emitted incrementally as confirmed. The report is complete only when every applicable detector has been checked against every applicable target. Never report done while a target file or detector remains unexamined. Explicitly list every unassessed detector with its blocker.
- Non-mutation rule. No file is created, edited, moved, or deleted. No git, build, install, deploy, or remote action is performed. Recovery from any failure is to report the failure and continue or stop; never to mutate state to work around it.
- Rationalization rejection (Cosmos, applied where the reference states). The six Cosmos rationalizations ("`ValidateBasic` catches this", "behind governance, so safe", "IBC counterparty is trusted", "panic can't happen, input is validated", "rounding error is only a few tokens", "EVM precompile handles rollback") are dismissed as reasons a match is safe. Other ecosystems' references state their own caveats (e.g., Cairo L1-bridge-contracts-absent marks L1-L2 patterns incomplete, not clean).

## Failure behavior

| Failure class | Behavior |
|---|---|
| No supported ecosystem surface | Stop. Report the path was searched and no supported chain source indicators were found. Do not fabricate findings. |
| Ecosystem tool not installed | Continue with the manual detector sweep from the reference. Record the tool absence in coverage notes. Do not attempt installation. |
| Ecosystem tool execution error | Capture the error message, include it in coverage notes, and proceed with the manual sweep. A tool failure does not invalidate manual findings. |
| Missing version evidence for an applicability gate | Report the affected detectors/catalogs as blocked with the missing evidence. Do not guess a version. |
| Missing auxiliary source (Cairo L1 bridge) | Report which patterns could not be fully evaluated and mark them incomplete, not clean. |
| Detector not applicable | Record the detector as checked-but-not-applicable in coverage notes rather than omitting it, so the done predicate is auditable. |
| Ambiguous code (cannot confirm vulnerable or safe) | Record as an unconfirmed observation with the code location and the specific check that could not be resolved. Do not promote it to a confirmed finding. |
| Match not on a consensus/reachable path | Not a finding. Record as not-applicable with the reason (e.g., "not consensus-critical" for Cosmos CLI/query/test code). |
| Scan error (crash, OOM, tool failure halting the run) | Stop. Return `"Scan failed: [exact error class]. No findings are returned."` (TON rule, applied ecosystem-wide for halting errors). |
| No findings | Return the empty-result statement with ecosystem, scope, and date. This is not a failure. |
| Partial result (source size limit or mid-scan halt) | Return assessed detectors and explicitly list every unassessed detector with its blocker. Include the scope-overrun warning where applicable (TON). Never claim the done predicate holds while a detector remains unchecked. |

## Output

A chat-output report with the following structure:

- Header: ecosystems, project path, files scanned, contract/module types identified, tool availability, and ecosystem discovery inventory where defined (Cosmos).
- Findings: one entry per confirmed vulnerability, ranked Critical > High > Medium > Low > Informational (where the ecosystem defines the rung). Each entry carries the shared finding fields above plus any extra ecosystem fields.
- Coverage notes: for each detector in the loaded reference, state `checked` / `not-applicable` / `unconfirmed` / `blocked`, and note tool availability and any execution errors. For Cosmos, include a completeness check listing every applicable catalog with its pattern count, confirming none were skipped.

The done predicate holds when every applicable detector in every selected reference is checked and each confirmed finding carries code evidence, a reachable attack path, and remediation.