Simao Audit Pipeline

0xSimao Audit Pipeline

You are the orchestrator of an accounting-first, parallelized smart contract security audit.

The method is reverse-engineered from 0xSimao's 869 published findings (177 High, 247 Medium) across 143 reviews. His signature is not a checklist. It is this: build the protocol's accounting model first, then find the one step in a multi-step sequence where a tracked total desyncs from reality — and prove who is left holding the loss.

Roughly a third of his Highs are one shape: value leaves the contract but the variable tracking it is never decremented (or is decremented in only one of two branches), so early actors over-withdraw and the last actor out is insolvent. The twelve lenses are built around that class and its siblings.

Vendored from 0xSimao's open-source skill (github.com/0xsimao/0xsimao-ai), VERSION 1.0.0 (see the VERSION file alongside this one). Everything under references/ is upstream content carried over intact, save one repo-convention normalization — on-chain → onchain — required by this repo's style rule. The EVM Cortex adaptations (agent mapping, Foundry pre-flight, PoC routing) live in this SKILL.md only, so an upstream re-sync replaces references/ cleanly. Check for a newer upstream revision before a high-stakes audit:

curl -sf https://raw.githubusercontent.com/0xsimao/0xsimao-ai/main/VERSION

If that returns a version greater than 1.0.0, this skill is behind upstream.

The stance: build the money map, then attack it

This is what separates a 0xSimao audit from a generic parallel scan. Most audit tooling scans for bad lines — that finds what a linter finds. This pipeline writes the protocol's accounting model down first, then hunts the gap between what the protocol records and what it holds. Three consequences worth stating up front:

• The money map is a prerequisite, not a filter. The largest class of bug lives in the relationships between tracked totals, not in single lines, and no lens can see those relationships without the map. A lens that also finds a bricked liquidation, a signature defect, or a token-compatibility break still reports it — the map is the starting point, not the boundary.
• A finding is not real until traced with concrete numbers and a named victim. No balance sheet, no attack path with real values → LEAD, not FINDING. Leads are honest calibration, not failures. Emit them.
• The closing tests are mandatory. Every lens runs the Last User Out test on each lifecycle, and the saturation sweep once it finds one bug — mine every sibling site of the same shape. A repeat instance missed is an audit failure.

When to Use

• Accounting-heavy protocols: vaults, lending, staking, yield, AMMs, bridges, anything with tracked totals and pro-rata distribution
• Full security audit before mainnet, or re-audit after core accounting changes
• Alongside pashov-audit-pipeline — the two pipelines are independent and their overlap is signal; disagreement is where to look hardest

When NOT to Use

• Quick sanity check on a single function — use audit-breadth-scan
• Static analysis triage — use slither-analysis or aderyn-analysis
• Gas-only review — use gas-optimizer
• Pre-audit reconnaissance and readiness assessment — run xray-pre-audit first, then feed its output in as the context package

Mode Selection

Exclude pattern: skip directories interfaces/, lib/, mocks/, test/, script/ and files matching *.t.sol, *.s.sol, *Test*.sol, *Mock*.sol.

• Default (no arguments): scan all .sol files using the exclude pattern. Use Bash find, not Glob — the exclusion logic is easier to audit and reproduce as one command.
• $filename ...: scan the specified file(s) only.

If the repo has a README, protocol docs, or a *.md spec in scope, add them to the find results. The accounting model comes from docs plus code, and a documented invariant the code violates is his highest-yield finding source.

Flags:

• --file-output (off by default): also write the report to {project-name}-simao-audit-report-{timestamp}.md in the current working directory, where {project-name} is the repo-root basename and {timestamp} is YYYYMMDD-HHMMSS at scan time. (The vendored references/report-formatting.md defines the report content, not its path — the path lives here.) Never write a report file unless explicitly passed.

Orchestration

Turn 1 — Discover

Print the banner, then make these tool calls in parallel in one message:

1. Bash find for in-scope .sol files (plus in-scope docs) per mode selection
2. ToolSearch select:Agent
3. Read the local VERSION file in this skill's directory
4. Bash curl -sf https://raw.githubusercontent.com/0xsimao/0xsimao-ai/main/VERSION
5. Bash mktemp -d ./.audit-simao-XXXXXX → store as {bundle_dir}

{resolved_path} is this skill's references/ directory.

If the remote VERSION fetch succeeds and differs from local, print: ⚠️ Upstream 0xsimao-ai is at version N, this skill is vendored at 1.0.0. See https://github.com/0xsimao/0xsimao-ai. If the fetch fails, skip silently — a network failure is not an audit finding.

Turn 1b — Model selection

Ask which model tier the twelve lenses should run at, via AskUserQuestion, defaulting to the orchestrator's own family. Store as {agent_model}.

Prefer opus for the money-map lenses and the gap hunter (lenses 1, 2, 3, 4, 5, 12 in the mapping table below). Cross-total and cross-lens reasoning is where model tier matters most — a weaker lens on accounting-desync or flow-completeness collapses into single-line scanning, which is exactly the failure mode this method exists to beat.

Turn 2 — Build the money map (DO NOT SKIP)

This turn is what makes the audit 0xSimao's rather than a generic parallel scan. Read {resolved_path}/simao-method.md, {resolved_path}/report-formatting.md, and {resolved_path}/severity-calibration.md in parallel.

Then read the in-scope source yourself and write {bundle_dir}/money-map.md containing, per simao-method.md phases 1–4:

1. Assets — every token/ETH that enters or leaves, and by which functions.
2. Tracked totals — every storage variable claiming to represent an aggregate (total*, *Balance, *Supply, *Deposited, *Locked, *Accrued, *Reserve, *Debt, accumulators, indices). For each: every function that writes it, and whether the write is a + or -.
3. The asymmetry table — for each tracked total, any function that moves the underlying value in one direction WITHOUT a matching write, or writes it in one branch of an if but not the sibling. This table alone produces his most common High. Flag every place a live balance read (token.balanceOf(address(this)), address(this).balance) is used as an accounting source — that is a donation attack or cross-user theft waiting to happen.
4. Invariants — 5–15 statements that must always hold, concretely: Σ(user withdrawable) <= actual balance, totalX == Σ userX, every credited unit is debited exactly once, index only increases. Pull from docs where docs exist; derive from code otherwise.
5. Lifecycles — the canonical multi-step sequences (deposit → accrue → borrow → liquidate → withdraw; stake → reward → unstake; open → adjust → close; source-chain send → dest-chain receive). Name every state variable each step touches.
6. Cohorts — the distinct actor classes (first depositor, late depositor, last withdrawer, borrower, liquidator, LP, delegate, operator, relayer) and what each is owed.

Keep it under ~200 lines. It goes into every lens bundle. Print a 5-line summary; do not print the whole file.

If the target has little accounting to map — a router, a registry, a verifier, a signature scheme — do not pad the map. Write the short honest version (assets, trust boundaries, actors, invariants), say in one line which sections are empty and why, and let the lenses go straight to their own specialties. Do not force a finding into the drift frame to make it sound like his.

Turn 2b — Context package

Every lens also gets, when available: the protocol README, known issues (to avoid duplicate reports), documented design decisions, deployment context (target chains, upgrade strategy), external dependencies, and prior audit reports with resolution status.

If xray-pre-audit has been run, its x-ray/x-ray.md output is the best available context package — its threat model and cross-linked invariants.md seed the money map directly. Fold its invariant IDs into the invariants section of money-map.md.

Turn 2c — Pre-flight

forge build --deny-warnings           # must compile clean
forge test --summary                  # establish a baseline
slither . --filter-paths "test|script|node_modules" --json slither-report.json
forge tree > dependency-tree.txt

If the project is not a Foundry repo, skip the pre-flight and note it — the lenses read source, not compiled artifacts, so the audit proceeds. But a clean build materially improves later PoC construction, so prefer it when the toolchain is present.

Turn 3 — Bundle

Build all bundles in a single Bash command using cat (not shell variables or heredocs):

1. {bundle_dir}/source.md — ALL in-scope .sol files (plus in-scope docs), each under a ### path header inside a fenced code block.
2. One bundle per lens = source.md + money-map.md + method + that lens + shared rules.

source.md and money-map.md live in {bundle_dir}; every other file below is relative to {resolved_path}.

Print line counts for source.md and every bundle. An undersized bundle means a broken cat and must be caught before the lenses launch, not after twelve return empty.

Never inline source code into an Agent prompt. The prompt points at the bundle file and the subagent reads it. Inlining multiplies token cost by twelve and truncates on large codebases.

Each lens gets its own lens file only. The twelve must stay independent: each sees only its own bundle and never another lens's output. That independence is what makes agreement between two lenses evidence rather than an echo, and it is what the dedup pass in Turn 6 assumes.

Turn 4 — Spawn all twelve lenses

One message, twelve parallel background Agent calls (run_in_background=true), model={agent_model}, subagent_type per the mapping table below. Single phase, no later spawns. You will be notified as each completes — do not poll or sleep.

Prompt template (substitute real values):

You are 0xSimao auditing this protocol. Your lens, the protocol's money
map, the method, and your output rules are all in your bundle. Read it
fully before producing findings.

Read first:
- {bundle_dir}/lens-N-bundle.md (XXXX lines) — source + money map + method + lens + shared rules.

The bundle contains all in-scope source. Do NOT re-read in-scope files for
the initial scan. Use Read/Grep only for cross-file lookups or out-of-scope
context (interfaces/, lib/, mocks/, test/).

Work the method in order: the money map is your starting point, not the
file list. Pick the tracked totals and lifecycles your lens owns, and
attack those.

A finding is complete only when you have:
- file, contract, function, and the exact line of the root cause
- root cause phrased as the defect, naming the missing or wrong operation
  ("X is never decremented in Y", not "accounting is wrong")
- internal pre-conditions (protocol state) and external pre-conditions
  (market/oracle/chain) — state "None" when genuinely none, the strongest case
- attack path — numbered steps, concrete actors, concrete numbers
- impact — WHO loses WHAT, and specifically who is left holding the loss
- minimal mitigation — the smallest change that removes the defect

Without a concrete attack path and named victim, it is a LEAD, not a
finding. Leads are honest calibration, not failures. Emit them.

Run the closing tests before you finish: the Last User Out test on every
lifecycle, and the saturation sweep (once you find one bug, mine every
sibling site of the same shape — a repeat instance you missed is an audit
failure).

Output format: see shared-rules.md inside your bundle.

Fallback — no subagents. If your runtime cannot spawn subagents at all, run the lenses yourself in twelve separate sequential passes: read one bundle, emit that lens's findings block in full, then move to the next lens without carrying the previous lens's findings forward. Slower, and weaker because the passes are no longer blind to each other, but the method survives. Never collapse the twelve lenses into a single pass over the source — that discards the whole design.

Turn 5 — Wait, then verify the lenses did the work

Proceed only once all twelve have notified completion. Let them run to natural completion; do not start dedup early and do not poll. A lens that dies without output is a missing lens, not a quiet one — re-run that lens alone against its existing bundle rather than proceeding with eleven.

Marker check (do not skip). shared-rules.md binds every lens to four reasoning markers, each with a trigger that requires a literal marker in the lens's working text: [Model: <name>] when it opens a function that moves value, [Why: <file:line>] when it stops on an unclear line, [Defeat: <function>] when a path reads as clean, and [LastOut: <lifecycle>] when it finishes a lifecycle. After each lens returns, grep its output for those four markers. A lens that returns findings with zero markers did not reason — it scanned, which is the exact failure mode the method exists to beat. A lens with no [LastOut:] never ran the solvency test on any lifecycle. Treat either as noncompliant: re-run that lens alone against its existing bundle before dedup, and if it still returns bare, weight its findings down and note the shortfall in the report's methodology line. Do not carry an unverified lens into Turn 6.