Smart Contract Audit skill for Codex

An audit is worth something when every reported issue has a reproducible proof (a failing test or a precise call sequence), severity reflects impact times likelihood, and the report says plainly what was not reviewed. An audit reduces risk; it never certifies a contract as safe, and the report must say so.

Scope and rules first

Before reading code, confirm with the user and record in the report:

• The exact commit hash and the files in scope (and those out of scope: libraries, mocks).
• That the code is theirs or they are authorized to have it reviewed.
• That proof-of-concept exploits run only on local forks or local chains. Never send transactions to a live deployment, even a “test” one on mainnet, to demonstrate a bug.
• Known issues, previous audits, and the threat model they care about (admin trusted or not?).

If a finding affects a live deployment holding funds, stop and tell the user privately before writing anything else; disclosure decisions are theirs.

Workflow

- [ ] 1. Freeze scope: commit hash, file list, nSLOC (cloc or scc), compiler version
- [ ] 2. Build and run the existing tests; note coverage gaps
- [ ] 3. Map the system: contracts, roles, entry points, value flows, external dependencies
- [ ] 4. Write down invariants the protocol must keep (in words, then as test assertions)
- [ ] 5. Run static analysis and triage every result
- [ ] 6. Manual review, function by function, with the checklist below
- [ ] 7. Write a PoC test for each suspected issue; drop or downgrade what you cannot prove
- [ ] 8. Write the report; review fixes against the same PoCs

Step 3: map before judging

Produce a table like this for every external or public non-view function:

Function	Caller	Moves value?	Calls out to	State written	Guard
deposit	anyone	in	token	balances, totals	nonReentrant
setOracle	owner	no	-	oracle	onlyOwner

Functions that are callable by anyone, move value and call out deserve the most time. Note every external dependency: tokens (which kinds: fee-on-transfer, rebasing, ERC-777 hooks, USDT’s missing return value, blocklists), oracles, AMMs, bridges, other protocols.

Step 5: tooling

forge build && forge test -vv
forge coverage --report summary          # may need --ir-minimum on stack-too-deep code
slither . --filter-paths "lib|test|script" --exclude-dependencies
slither . --print human-summary
aderyn .                                  # writes report.md

Slither and Aderyn install via pip and cargo or their installers and need network; ask for approval in a sandbox. Treat their output as leads, not findings. Classify each result as true positive, false positive (say why) or informational. Never paste raw tool output into the report.

Step 6: manual review checklist

Go through each function against these questions. For the full catalog with vulnerable and fixed code for each class, read references/vulnerability-catalog.md when a question below raises a suspicion.

Access control

• Is every state-changing privileged function guarded? Are initializers protected and called in the deploy script (_disableInitializers() in implementation constructors)?
• Can roles be renounced or transferred to zero by mistake? Is there a single EOA with power to drain funds? (Centralization risk: report it even when “by design”.)

Reentrancy

• External calls (token transfers, ETH sends, hooks in ERC-721/1155/777 receivers, callbacks) before state updates? Cross-function reentrancy through a second function sharing state?
• Read-only reentrancy: does a view function return inconsistent values mid-call that another protocol uses as a price?

Arithmetic and accounting

• Rounding direction in share/asset conversions; first-depositor inflation on ERC-4626 vaults (OZ 4.9+/5.x mitigates with virtual shares and _decimalsOffset).
• Division before multiplication; precision loss with low-decimal tokens (USDC has 6).
• unchecked blocks and downcasts (uint128(x)) without SafeCast.
• Does sum(user balances) == total hold after every function? Write it as an invariant.

Oracles and prices

• Spot prices from AMM reserves or balanceOf(pool) are flash-loan manipulable.
• Chainlink: stale updatedAt, answer <= 0, wrong decimals, missing L2 sequencer check.

Tokens

• Fee-on-transfer and rebasing tokens break amount-based accounting.
• Missing return values (USDT) without SafeERC20. Approval race and infinite approvals.
• Tokens with blocklists (USDC) can make a push-payment loop revert for everyone.

Signatures and replay

• EIP-712 domain includes chainId and verifyingContract; nonce consumed; deadline checked.
• ecrecover zero-address result and s-malleability handled (use OZ ECDSA).
• Permit front-running: a permit call that reverts because someone already used it must not block the user’s flow (wrap in try/catch).

Denial of service and griefing

• Unbounded loops, push payments to arbitrary addresses, reliance on exact balances (address(this).balance == x, which forced ETH breaks).

MEV and ordering

• Missing slippage limits (minAmountOut) and deadlines on swaps and liquidations.
• Commit-reveal needed? Can a front-runner sandwich or steal a first-come reward?

Upgradeability

• Storage layout collisions, uninitialized implementations, missing _authorizeUpgrade guard, selfdestruct/delegatecall in implementations. See $upgradeable-contracts.

Cross-chain and L2

• block.number semantics differ on L2s (Arbitrum returns an L1-ish number).
• PUSH0 and other opcodes on chains with older EVMs; hard-coded chain IDs.

Step 7: proving issues

Write each PoC as a Foundry test that fails on the vulnerable code and passes after the fix. Name it after the finding ID.

function test_H01_reentrancyDrainsVault() public {
    vm.deal(address(attacker), 1 ether);
    attacker.attack{value: 1 ether}();
    // Vault started with 10 ETH from honest users.
    assertGt(address(attacker).balance, 1 ether, "attacker profited");
    assertLt(address(vault).balance, 10 ether, "honest funds lost");
}

For protocols that integrate live contracts, fork locally at a pinned block: vm.createSelectFork(vm.rpcUrl("mainnet"), 21_000_000); (needs an RPC URL and network). Pinning the block keeps the PoC reproducible.

Severity

Severity	Impact	Typical example
Critical	Direct theft or permanent freezing of user funds, no preconditions	Unprotected withdrawAll
High	Loss of funds with realistic preconditions; protocol insolvency	Oracle manipulation via flash loan
Medium	Funds at risk under unlikely conditions; core function broken; temporary freeze	Blocklisted recipient freezes a payout loop
Low	Minor value leak, edge-case misbehaviour, best-practice deviation with some risk	Missing zero-address check on a settable param
Informational	Code quality, gas, docs	Unused variable, missing NatSpec

Severity = impact x likelihood. A Critical impact behind an owner-only call is usually Medium or “centralization risk” if the owner is trusted per the agreed threat model; say which.

Output contract

# Security review: <Project> @ <commit>

**Scope:** src/Vault.sol, src/Strategy.sol (612 nSLOC). Out of scope: lib/, script/
**Method:** manual review, Slither 0.11, Aderyn, Foundry PoCs on a local fork at block N
**Disclaimer:** time-boxed review; absence of findings is not a guarantee of security.

| ID | Title | Severity | Status |
|---|---|---|---|
| H-01 | Reentrancy in withdraw drains vault | High | Fixed in abc123 |

## H-01 Reentrancy in withdraw drains vault
**Location:** src/Vault.sol#L88-L97
**Description:** what is wrong and why, in three to six sentences.
**Impact:** who loses what, under which conditions.
**Proof of concept:** test/poc/H01.t.sol::test_H01_reentrancyDrainsVault
**Recommendation:** concrete code change.
**Fix review:** verified in commit abc123; PoC now fails to profit.

Hard rules

• No finding without a location and either a PoC or a precise, checkable call sequence.
• Do not inflate severity to look thorough or deflate it to please the client.
• Re-run every PoC against the fix commit before marking an issue fixed.
• Keep findings private to the user; never post them in public issues or PRs without consent.