Integration Hazard Research

Injectable Skill: Integration Hazard Research

Protocol Type Trigger: NAMED_EXTERNAL_PROTOCOL — detected when recon identifies imports or interface calls to a named external protocol (Uniswap, Aave, Balancer, Compound, Curve, Chainlink, Lido, MakerDAO, etc.) that is NOT a standard library (OpenZeppelin, solmate, solady) and NOT the protocol under audit itself. Inject Into: depth-external agent Language: All chains (EVM primary; Solana/Aptos/Sui when integrating with named on-chain protocols) Finding prefix: [IHR-N] Added in: v1.1.5

Orchestrator Decomposition Guide

This skill adds a research phase (Section 0) before depth-external's existing code analysis. All sections map to depth-external's domain. The orchestrator includes this skill in the depth-external agent's prompt when NAMED_EXTERNAL_PROTOCOL is flagged.

When decomposing into investigation questions:

• Section 0 (research): produces a hazard catalog that informs all of depth-external's existing Sections 1-4
• Section 1 (third-party race): extends depth-external Section 1 (side effects)
• Section 2 (state TOCTOU): extends depth-external Section 4 (governance/parameter change)

When This Skill Activates

Recon Agent 3 detects named external protocol imports during TASK 6 pattern scanning. Indicators:

• Named protocol interfaces: IUniswapV2Router, IUniswapV3Pool, IBalancerVault, IPool, IAToken, ICToken, ILendingPool, ICurvePool, IChainlinkAggregator, IStETH
• Named protocol library imports: @uniswap/, @aave/, @balancer-labs/, @chainlink/, @openzeppelin/ (only when calling protocol-specific functions, not generic utilities)
• Solana: CPI targets to known program IDs (Jupiter, Marinade, Raydium, Orca, Drift)
• Sui: external package calls to known protocols (Cetus, DeepBook, Suilend, NAVI)
• Aptos: external module calls to known protocols (Thala, Echelon, Liquidswap, PancakeSwap)
• Soroban: cross-contract calls to known protocols (SoroSwap, Blend Protocol, Phoenix DEX, Aqua Network, OrbitCDP)

The flag records which protocols were detected: NAMED_EXTERNAL_PROTOCOL: [Uniswap V3, Chainlink]

Processing Protocol (MANDATORY)

For each section below, execute in order:

1. ENUMERATE targets: List every entity the section applies to (external protocols, hazard catalog entries, race condition candidates, TOCTOU pairs) as a numbered list before analysis begins.
2. PROCESS exhaustively: Analyze each numbered entity. Mark each "DONE" or "N/A (reason)" before moving to the next.
3. COVERAGE GATE: Count enumerated vs processed. If any entity lacks a marker, process it before proceeding to the next section.

0. Target Protocol Hazard Research

For EACH named external protocol detected by recon:

0a. Read the Recon-Baked External Dependency Research Ledger (PRIMARY — MANDATORY)

DO NOT call mcp__unified-vuln-db__search_solodit_live or any tavily/web-search MCP tool for dependency research. They are unavailable in depth-phase subagent contexts — the driver launches depth workers with --disallowedTools mcp__* and an empty MCP server config to prevent cold-start hangs. Any Solodit/Tavily MCP call in this phase will silently fail or hang; do not attempt it.

Read {SCRATCHPAD}/external_dependency_research.md instead. This is the recon-baked research ledger: recon runs as a phase-LLM with live WebSearch/WebFetch/tavily_search access and already researched every detected external dependency's real interface/semantics (deployed source, ABI/arity, monotonicity, gas/error behavior) before depth ever runs. For each target protocol/dependency, find its row: Dependency | Integration Surface (file:line) | Assumed Behavior (as coded) | Real Behavior (researched) | Source (URL + fetch date) | Conformance MATCH/MISMATCH/CHECK | Fetch Status OK/FETCH_FAILED:reason. Use the ledger's Real Behavior / Conformance columns as your hazard-catalog input for Section 0c below instead of live search results.

0b. Escalate Uncovered Surfaces — Do Not Guess (MANDATORY)

For an integration surface in your target that is NOT covered by any ledger row (a dependency the ledger missed, or a row with Fetch Status: FETCH_FAILED), do NOT guess the real behavior and do NOT silently fall through to the 0d floor catalog as if it were live research. Emit, in your finding output, one escalation line per uncovered surface:

NEEDS_DEPENDENCY_RESEARCH: <dependency>:<file:line>: <what you need to know>

Then proceed under the assumed WORST-CASE realistic external condition per Rule 10 (rules/finding-output-format.md), tagging the finding [EXTERNAL-ASSUMPTION: <assumed condition>]. Note: native WebSearch/ WebFetch (non-MCP Claude Code tools) remain available if you need a single targeted check beyond the ledger — but the ledger is the primary source and should cover the large majority of surfaces; ad-hoc web search is not a substitute for reading it first.

0c. Compile Hazard Catalog

Applicability criteria (same as FORK_ANCESTRY):

• YES: The audited code calls the function or reads the state involved in this hazard
• NO: The audited code does not interact with the affected function/state (document why)
• CHECK: Cannot determine without deeper analysis — flag for depth trace

0c-bis. Asset-Form Delivery Check (MANDATORY for every bridge/gateway/router callback + outbound deposit/withdraw)

Cross-chain gateways frequently deliver the gas token in a DIFFERENT FORM than the handler assumes — native vs wrapped (e.g. ETH vs WETH). This is an asset-FORM mismatch, distinct from the asset-IDENTITY (declared-output-token vs delivered-token) mismatch. For EACH inbound callback (onCall/onReceive/onRevert/router callback) and EACH outbound deposit/withdraw:

1. From the external protocol's docs/source, determine whether it DELIVERS/EXPECTS the asset in NATIVE or WRAPPED form (many gas-token bridges auto-unwrap to native on delivery and auto-wrap on send).
2. Assert the handler's FIRST value-moving op matches that form: a wrapped-ERC20 approve/transferFrom/swap requires the asset to already be wrapped; a .call{value:}/native send requires it to be native.
3. RED FLAG → emit a CHECK candidate (never a silent UNVERIFIED): the callback names a wrapped-token address as the asset param but the handler moves it via ERC20 approve/transfer with NO deposit{value:}/withdraw() reconciliation (or vice-versa). The missing inbound native→wrapped (or wrapped→native) conversion is a candidate asset-form mismatch — verify reachability and impact.
4. If the delivery form cannot be confirmed from docs/source, escalate to a CHECK candidate for depth tracing — do NOT drop it as UNVERIFIED.