Solidity Security Audit

Solidity Security Audit Skill

Purpose

Perform professional-grade smart contract security audits following methodologies established by the world's leading Web3 security firms. Produce actionable, severity-classified findings with remediation guidance.

Context Gathering — When Code Arrives Without Scope

Trigger: User pastes Solidity code (one function, one file, or a repo link) with no additional context — no chain, no Solidity version, no stated scope, no prior audit info.

Do NOT start auditing immediately. Missing context causes wrong severity ratings, irrelevant findings (e.g., flagging L2 issues on mainnet-only code), and wasted effort. Ask the following questions in a single message before proceeding.

Required Context (block until answered)

Ask these as a short numbered list — not a form, not a table:

Before I start the audit, I need a few details:

1. **Scope** — Is this the full codebase, a single contract, or a specific function?
   (Full codebase = I'll check cross-contract interactions; single function = focused review)

2. **Solidity version** — What compiler version are you targeting?
   (Affects: overflow behavior, PUSH0 compatibility, transfer()/send() deprecation in 0.9.0)

3. **Target chain(s)** — Where will this deploy?
   (Mainnet, L2 like Arbitrum/Base/zkSync, multi-chain, or unknown)

4. **Previous audits** — Has this code been audited before? Any known issues or recent changes?
   (If yes → Re-audit mode; if no → Full Audit)

5. **Protocol type** — What does this protocol do?
   (e.g., lending, AMM, vault, bridge, governance — determines which checklist to load)

Defaults If User Cannot Answer

If the user says "just check it" or provides no answers, assume these safe defaults and state them explicitly at the start of the audit:

| Question | Default | Risk | |----------|---------|------| | Scope | Single contract/function provided | May miss cross-contract issues | | Solidity version | Latest stable (^0.8.x) | May miss version-specific bugs | | Target chain | Ethereum mainnet | May miss L2-specific issues | | Previous audits | None — first review | Full Audit mode | | Protocol type | General DeFi | Use Universal DeFi Checks from defi-checklist.md |

Fast Path — Single Function Paste

When a user pastes an isolated function (≤30 lines, no visible contract state or constructor), skip the context questions and do a Quick Scan directly. State:

> "Reviewing this function in isolation. For a full audit including state variables, > access control, and cross-contract interactions, share the full contract."

Then output: severity-tagged bullet list (Critical/High only unless none found, then include Medium).

---

Audit Mode Selection

Before starting, identify the audit mode:

| Mode | When to Use | Entry Point | |------|-------------|-------------| | Full Audit | First-time review of a codebase | Phases 1–5 below | | Re-audit / Diff | Previous audit exists; team applied fixes or added features | references/diff-audit.md | | Integration Review | Contract integrates Uniswap, Chainlink, Aave, Curve, etc. | references/defi-integrations.md + Phase 3 | | Quick Scan | Rapid assessment, limited time | references/quick-reference.md — abbreviated Phase 0 (5 min max), run Phases 1–2 only, focus Phase 3 on Critical/High patterns from quick-reference.md. Output: bullet list of Critical/High findings only; each entry: severity tag, location (File.sol#L), one-line description, remediation pointer. No full report structure required. | | Contest | Submitting to Code4rena, Sherlock, Immunefi, Cantina, or CodeHawks | See Contest Mode section below — platform-specific output format, strategy, and validity rules |

For severity classification guidance at any point, consult references/severity-decision-tree.md.

---

Contest Mode

Activate when the user mentions: "Code4rena", "C4", "Sherlock", "Immunefi", "Cantina", "CodeHawks", "Cyfrin", "warden submission", "Watson submission", "bug bounty submission", "audit contest", "audit competition", "contest finding", or "submit to contest".

Step 0 — Identify the Platform

| Platform | Model | Reward Structure | Severity Used | |----------|-------|-----------------|---------------| | Code4rena | Competitive | H/M split pool; Low = QA pool; Gas = Gas pool | H / M / Low / NC / Gas | | Sherlock | Competitive | H/M split; Low = no payout | H / M only (paid) | | Immunefi | Bug bounty | Tiered fixed payout per severity | Critical / High / Medium / Low | | Cantina | Competitive | H/M/Low reward tiers | Critical / H / M / Low / Info | | CodeHawks / Cyfrin | Competitive | Similar to C4 | H / M / Low / Info / Gas |

Once identified, apply the exact submission format from references/report-template.md → Contest Submission Format.

Step 1 — Scope Verification

Before any review:

• Read the contest README, scope.txt, and known issues list in the contest repo
• Mark all out-of-scope contracts — findings there are immediately invalid
• Note "Admin is trusted" and other protocol assumptions that eliminate entire bug classes
• Check if a bot race report has been submitted (C4 bots claim floating pragma, missing zero-checks, unchecked returns — avoid these)

Step 2 — Priority Stack (Contest ROI)

Contests reward unique, high-impact findings. Allocate review time accordingly:

Highest ROI → spend 70% of time here:

• Reentrancy (all variants, especially cross-function and read-only)
• Oracle manipulation (spot price, TWAP bypass, stale feeds)
• Access control gaps on privileged functions
• Business logic errors (incorrect fee math, state machine violations, off-by-one)
• Economic attacks (flash loan vectors, slippage, MEV)

Medium ROI → spend 25%:

• Integer precision / rounding direction
• Missing input validation (zero-address, bounds — only if exploitable, not bot-fodder)
• DoS vectors (unbounded loops, griefing with real impact)
• Signature replay / EIP-712 errors

Low ROI — skip unless trivial to add:

• Gas optimizations (only if contest has a Gas pool)
• Code style, naming (NC / Info → no payout on most platforms)
• Findings already listed as known issues

Step 3 — Validity Pre-Check

Before writing each finding, apply this filter:

Is there a working attack path an external actor can execute?
├─ No → Invalid (likely rejected)
│
Is the root cause inside the contest scope?
├─ No → Out of scope (invalid)
│
Does the impact require a trusted role (admin, owner)?
├─ Yes, and admin is listed as trusted → Low at best (often invalid)
│
Can the impact be quantified in USD?
├─ Yes → always include the estimate (judges weight concrete impact)
├─ No → describe the qualitative harm precisely
│
Is there a working PoC?
├─ H/M without PoC → likely downgraded or rejected
├─ Build a Foundry test before writing the report

Step 4 — Platform-Specific Rules

Code4rena:

• Each H/M = separate GitHub issue; QA findings bundled in one QA report
• Duplicate = same root cause (not same symptom) → split reward pool
• Unique findings with PoC earn the most; first-mover advantage on uncommon bugs
• Link every finding to exact GitHub permalink (commit hash, not branch)
• Use diff format in mitigations when possible

Sherlock:

• Strict pre-conditions template required: "Internal pre-conditions" + "External pre-conditions"
• admin is trusted = admin-abuse findings are invalid (not even Low)
• "Loss of 1 wei" alone = invalid; needs meaningful dollar impact or significant disruption
• Escalation period: Watson escalation reviewed by Senior Watsons; escalate if you believe judge is wrong
• Valid states must persist after the PoC transaction (not reset by next block)

Immunefi:

• Bug bounty: disclose privately first; no public disclosure until patched
• Critical/High require a working PoC; Medium may be accepted with clear description
• Impact must be real: "theoretical" or "best case" attacks typically rejected
• Include: affected product version, environment (mainnet/testnet), reproduction steps
• Do not include in contest format — use private disclosure channel

Cantina / CodeHawks:

• Similar to C4 in structure; include Context: field with exact file + line reference
• CodeHawks requires explicit Likelihood and Impact labels in addition to combined Severity

Step 5 — Output

Use the exact per-platform format from references/report-template.md → Contest Submission Format.

Do not use private audit report format (no Executive Summary, no Scope section, no Appendix).

Each finding is standalone and must be independently understandable. Judges read hundreds of findings — front-load the impact in the first sentence.

---

Full Audit Workflow

Execute audits in this order. Each phase builds on the previous one.

Phase 0 — Threat Modeling

Audit by Protocol Type — Quick Routing

| Protocol Type | Primary Reference | DeFi Checklist Section | Key Case Studies | |---|---|---|---| | AMM / DEX | defi-integrations.md §Uniswap | defi-checklist.md §AMM | Curve, Cork Protocol | | Lending / Borrowing | defi-integrations.md §Aave | defi-checklist.md §Lending | Euler, Abracadabra | | Vault / Yield (ERC-4626) | defi-integrations.md §ERC-4626 | defi-checklist.md §Vault | — | | Bridge / Messaging | l2-crosschain.md | defi-checklist.md §Bridge | Nomad, Wormhole | | Governance / DAO | vulnerability-taxonomy.md §15 | defi-checklist.md §Governance | Beanstalk, Compound | | Perpetual DEX | perpetual-dex.md | defi-checklist.md §Perp | Hyperliquid HLP | | LST / Restaking | staking-consensus.md | defi-checklist.md §Restaking | Bybit | | Uniswap V4 Hook | defi-integrations.md §V4-Hooks | defi-checklist.md §V4-Hooks | Cork Protocol | | ZK / Rollup | zkvm-specific.md | l2-crosschain.md §ZK | — | | Account Abstraction | account-abstraction.md | audit-questions.md §AA | — | | AI-Generated Code | ai-code-patterns.md | audit-questions.md §AI | Bybit (supply chain) | | Intent / Solver | intent-protocols.md | defi-checklist.md §Intents | — | | CeDeFi / Synthetic | vulnerability-taxonomy.md §4.7 | defi-checklist.md §CeDeFi | xUSD ($285M) | | RWA / Tokenized Assets | rwa-protocols.md | defi-checklist.md §RWA | — | | Options / Structured Products | options-protocols.md | defi-checklist.md §Options | Deus DAO, Lyra AVAX | | Prediction Markets | prediction-markets.md | defi-checklist.md §Prediction | Polymarket UMA disputes, Augur REP | | Multisig / Safe Modules | safe-modules.md | defi-checklist.md §Safe | Radiant Capital | | Move / Sui / Aptos | move-security.md | — (supplement) | Cetus ($223M) |

Before touching code, build a mental model of what the protocol does and what can go wrong economically. This shapes where you spend time in Phase 3.

1. Map the actors: who interacts with this protocol?

• Unprivileged users, liquidity providers, borrowers
• Privileged roles: admin, guardian, keeper, fee recipient
• External actors: MEV bots, flash loan attackers, liquidators, governance participants

1. Identify the crown jewels: what assets or rights are at risk?

• User funds locked in the protocol
• Protocol-owned reserves or insurance funds
• Governance control (ability to upgrade, change parameters, drain)

1. Define critical invariants: what must NEVER be false?

• Solvency: total liabilities ≤ total assets
• Accounting: sum of individual balances = tracked total
• Access: only authorized callers can execute privileged operations

1. Trace trust boundaries: what external systems does this protocol trust?

• Oracles (Chainlink, TWAP, custom)
• External protocol integrations (Uniswap, Aave, Curve)
• Bridging / messaging layers (LayerZero, CCIP, Wormhole)
• Multisig signers or governance

1. Estimate MEV surface: what operations create profitable ordering opportunities?

• Liquidations, arbitrage, sandwich-able swaps
• Front-runnable reveals, claims, or settlements

1. Note upgrade/admin blast radius: if the admin key or a multisig is compromised,

what is the maximum damage? Is there a timelock? A pause mechanism?

Output: a 5–10 line threat summary that focuses the manual review in Phase 3 on the highest-value attack paths. Skip this only for Quick Scan mode.

---

Phase 1 — Reconnaissance

1. Identify the Solidity version, compiler settings, and framework (Hardhat/Foundry)
2. Map the contract architecture: inheritance tree, library usage, external dependencies
3. Identify the protocol type (DeFi lending, AMM, NFT, governance, bridge, vault, etc.)
4. Determine the trust model: who are the privileged roles? What can they do?
5. List all external integrations (oracles, other protocols, token standards)

Phase 2 — Automated Analysis

If tools are available in the environment, run them in this order:

# Static analysis
slither . --json slither-report.json

# Compile and test
forge build
forge test --gas-report

# Custom detectors (if Aderyn is available)
aderyn .

If tools are NOT available, perform manual static analysis covering the same categories these tools check. Read references/tool-integration.md for details.

Phase 3 — Manual Review (Core)

This is where the highest-value findings come from. Follow the vulnerability taxonomy in references/vulnerability-taxonomy.md systematically.

Navigation: Load references/INDEX-vulns.md to quickly locate which file:section covers a given vulnerability type or secure pattern. For DeFi-specific topics, load references/INDEX-defi.md instead. See references/INDEX.md for the full category guide.

CRITICAL PRIORITY — Check these first:

• Reentrancy (all variants: cross-function, cross-contract, read-only)
• Access control flaws (missing modifiers, incorrect role checks, unprotected initializers)
• Price oracle manipulation (spot price usage, single oracle dependency, TWAP bypass)
• Flash loan attack vectors
• Proxy/upgrade vulnerabilities (storage collision, uninitialized implementation, UUPS gaps)
• Unchecked external calls and return values
• ERC-7702 delegation risks (if EOAs or authorization tuples are present: malicious delegation target, stale authorization replay, nonce race, re-initialization of delegated code) — see references/vulnerability-taxonomy.md §17

HIGH PRIORITY:

• Integer overflow/underflow (pre-0.8.x or unchecked blocks)
• Logic errors in business rules (token minting, reward calculations, fee distribution)
• Front-running and MEV exposure (sandwich attacks, transaction ordering dependence)
• Denial of Service vectors (gas griefing, unbounded loops, block gas limit)
• Signature replay and malleability
• Delegatecall to untrusted contracts

MEDIUM PRIORITY:

• Gas optimization issues that affect usability
• Missing event emissions for state changes
• Centralization risks and single points of failure
• Timestamp dependence
• Floating pragma versions
• Missing zero-address checks

LOW / INFORMATIONAL:

• Code style and readability
• Unused variables and imports
• Missing NatSpec documentation
• Redundant code patterns

Phase 4 — DeFi-Specific Analysis

When auditing DeFi protocols, apply the specialized checklist from references/defi-checklist.md. Load references/INDEX-defi.md to navigate protocol-specific entries and invariant tests. Key areas:

• Lending protocols: Liquidation logic, collateral factor manipulation, bad debt scenarios
• AMMs/DEXs: Slippage protection, price impact calculations, LP token accounting
• Vaults/Yield: Share price manipulation (inflation attack), withdrawal queue logic
• Bridges: Message verification, replay protection, validator trust assumptions
• Governance: Vote manipulation, flash loan governance attacks, timelock bypass
• Staking: Reward calculation precision, stake/unstake timing attacks
• RWA protocols: Load `references/rwa

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mariano-aguero
• Source: mariano-aguero/solidity-security-audit-skill
• License: MIT

Install and usage instructions live in the source repository linked above.