pre-audit-threat-model

pre-audit-threat-model

Audit-readiness x-ray. Build the threat model BEFORE running any tooling so every later pass has an entry-point list, an actor map, and a stated invariant set to evaluate against.

When to use

• First skill on any new Solidity engagement. Always.
• Operator says "x-ray", "audit readiness", "prep this protocol", "summarize this protocol", or "where do I start".
• Re-run when the codebase changes meaningfully (new contract, new role, new external integration); the cached x-ray.md is otherwise the source of truth.

Pipeline (3 steps, sequential)

Step 1 — Enumerate and measure

1. Detect source dir: read foundry.toml src= first, else hardhat.config.*, else try src/ then contracts/.
2. Count: source files, nSLOC (no ~ prefix in the report), test files, test functions, stateful-fuzz files, foundry-invariant files, echidna/medusa/halmos/certora configs, fork tests. These signal test presence — never infer "no tests" from coverage tool failure.
3. Run coverage in background (forge coverage, or a project-local hardhat coverage only if the project already has Hardhat installed — never npx-fetch a remote tool). If the toolchain is missing, surface the failure reason and continue — coverage is not a gate.
4. Run a git-security scan: branch shape (linear / merged / squashed-import), fix-commit candidates (commits whose message matches fix|patch|vuln|exploit|audit), late changes (commits in the final 10% of history), forked deps, tech-debt markers (TODO/FIXME density), test co-change rate per source file.
5. Glob for spec/whitepaper docs and extract only stated invariants, actor definitions, trust assumptions, economic properties. Tag spec-derived claims (per spec) so auditors can tell code-verified from spec-stated.

Step 2 — Read source and classify entry points

1. Read every in-scope .sol. Skip interfaces/, vendored copies of OZ/Uniswap libs, tests/mocks. For each contract record: type & inheritance, roles & access control, value-holding state vars, external calls, fund flows, invariant comments, require/assert statements.
2. Entry-point grep gate (PCRE — Bash, not the Grep tool):

   # single-line signatures
   grep -rnP 'function\s+\w+\s*\([^)]*\)\s+(external|public)(?!.*\b(view|pure)\b)' src/ --include='*.sol'
   # multi-line signatures (visibility on closing-paren line)
   grep -rnP '^\s*\)\s+(external|public)(?!.*\b(view|pure)\b)' src/ --include='*.sol' -B5
   

3. Classify EACH grep hit by reading its body: permissionless (no modifier AND no internal msg.sender check), role-gated (modifier or internal restriction — acceptOwnership style counts), or admin-only. nonReentrant alone is NOT access control. The grep list is the source of truth — subagent summaries lose.
4. Centralization analysis per privileged role: enumerate operational actions, distinguish role-transfer delays from action delays, mark which actions can extract user funds.
5. Pause-coverage analysis: which critical functions are whenNotPaused, which aren't. Integrate gaps into the relevant role's attack surface — do NOT make a standalone "Centralization Risks" section (that duplicates Actors / Trust Boundaries / Attack Surfaces).