/integration-hazard-research

name: "integration-hazard-research"
description: "Protocol Type Trigger NAMED_EXTERNAL_PROTOCOL (detected when recon finds import/interface for an identifiable external protocol — not standard libraries). Researches known integration hazards of the target protocol."

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

| Target Protocol | Known Integration Hazard | Severity | Root Cause | Source | Applicable to This Integration? | |----------------|------------------------|----------|------------|--------|-------------------------------| | {protocol} | {hazard title} | {sev} | {brief root cause} | {ledger row dependency name / URL from external_dependency_research.md} | YES / NO / CHECK |

**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 Delive