Cerberus Proof Auditor

SEPARATE ENTRIES PER SUBJECT (MANDATORY): NEVER merge multiple contracts or vulnerability classes into a single analysis entry. Each contract MUST have its own storage layout section if forge inspect succeeded. Each attack vector MUST be a separate numbered entry — do not group unrelated paths. When multiple Slither printers succeed, present each as its own labelled section. Correct: '### Attack Vector 1 — Reentrancy in withdraw()' and '### Attack Vector 2 — …'

Operating rules

1. Run phases in order: init -> preflight_or_repair -> architecture -> semantic_index -> ast_semantic_index -> action_catalog -> authority_graph -> dependency_graph -> rule_scan -> invariant_candidates -> finding_candidates -> finding_confirmation -> proof_planning -> hypothesis_triage -> poc_design -> scaffold_tests -> submission_bundle when those later phases are needed.
   • When both semantic_index.json and ast_semantic_index.json are present, downstream phases MUST prefer the AST-backed version for all structural data (function bodies, call edges, storage access, guard extraction).
   • The ast_semantic_index phase is marked degraded when neither forge build-info nor slither --json output is available; the regex fallback index is still produced.
2. Before starting a later phase, read .audit_board/status.json and confirm the prior phase produced usable artifacts. If a prior phase has "ok": false only because tooling degraded, inspect the artifacts and warnings first, note the limitation explicitly, and continue only if the output is still materially useful.
3. Treat generated artifacts as hypotheses until confirmed by source review or deterministic tests.
4. Never overwrite files outside .audit_board/ or test/.
5. scaffold_tests.py must not overwrite existing tests unless you intentionally pass --force.
6. Before phase execution begins, read meta/improvement_hotspots.json if it exists and use the top recurring hotspots as a preflight checklist.
7. After each phase, perform a local monitoring pass by inspecting status.json plus the newly created artifacts and append structured observations to the persistent skill log whenever the skill misbehaves, produces weak output, or exposes a clearly actionable improvement.
8. init is rerunnable and should preserve existing blackboard notes; do not treat it as a destructive reset.
9. If forge is installed in a standard user-local path but missing from PATH, prefer fixing the environment or invoking the discovered binary path rather than treating Foundry as unavailable.
10. When contest artifacts such as README.md, scope.txt, or out_of_scope.txt exist, ingest them during architecture and preserve that metadata for later severity and scope reasoning.
11. Prefer vectors where authority-linked setters and role-gated sinks drift apart.
12. Prefer reusing the repo's existing harness such as test/Base.t.sol when scaffolding proofs.
13. Treat phase success as contingent on artifact quality, not just file creation; empty heading stubs and placeholder-only markdown are failures.
14. Treat exploit-family rankings as hypotheses that require corroborating repo evidence such as native rule hits or privilege/invariant overlap.
15. scaffold_tests.py should only report success when the generated tests compile in the local repo.
16. Prefer exploit-driven outputs over artifact-only outputs: every serious hypothesis should state the invariant being broken, the minimum assumptions required, and the next deterministic confirmation step.
17. Track proof maturity explicitly using the progression hypothesis -> source_confirmed -> locally_reproduced -> deterministic_poc -> submission_ready. A sixth state, rejected, applies when false-positive rejection paths (guard equivalence, parent-guard shadow, out-of-scope disqualification, dead-code filtering) explicitly rule out a finding candidate.
18. When the repo already contains a relevant harness or mocks, reuse them and record the exact file path in poc_spec.md.
19. For contest workflows, produce a submission-ready report style matching one of: minimal_with_poc, detailed_with_instructions, severity_argument_only.
20. If a finding appears to be mainly a governance, recovery, or blast-radius issue rather than direct fund loss, call that out explicitly in severity_assessment.md instead of overselling it.

Reference Corpus

Cerberus ships with a local references/ corpus for focused checklists and taxonomy support:

• use references/sharp_edges.md to pressure-test attack hypotheses and explain why a pattern is dangerous
• use references/validations.md to sanity-check whether suspicious code patterns deserve explicit mention in 02_static_analysis.md
• use references/patterns.md only when proposing mitigations, safer rewrites, or test ideas

Treat the vendored references as support material, not as a replacement for repo-specific source review, generated artifacts, or deterministic tests. Do not cite every matching pattern mechanically; include only patterns that materially map to the current codebase.

Required inputs

• target_contract_dir (string): Directory that contains Solidity source files.

Optional inputs

• target_contract_name (string): Solidity contract name for Foundry scaffolding.
• target_contract_path (string): Repo-relative .sol import path for that contract.
• primary_contract_path (string): Repo-relative .sol file to prioritize when the repo has multiple entrypoints or many interfaces.
• primary_contract_name (string): Contract name to prioritize when selecting the primary architecture target.
• force_scaffold_overwrite (boolean): Only use when replacing an existing scaffold is explicitly intended.

Outputs

All scripts write into .audit_board/ and print a single JSON object describing the phase result. Improvement feedback is stored persistently in this skill's own meta/ directory so future runs can learn from it.

Status schema:

{
  "phase": "architecture",
  "ok": true,
  "mode": "full",
  "artifacts": {
    "flattened": ".audit_board/context_flattened.sol",
    "topology": ".audit_board/topology_map.txt"
  },
  "warnings": [],
  "errors": [],
  "details": {
    "target_dir": "/abs/path/to/src"
  }
}

Interpretation:

• ok: the phase produced at least one usable artifact
• mode: full only when required external tools are available and they produced usable analysis output; otherwise degraded
• warnings: soft failures the agent can reason around
• errors: hard blockers that require correction before retrying

NO CONTEXT BLOAT (MANDATORY): NEVER dump entire files, logs, or tool outputs into artifacts or responses. Extract ONLY the targeted fields, sections, or entries requested. When a tool returns more than ~100 lines, summarize and reference — do not reproduce verbatim. Incorrect: pasting the full phase1_tooling.log as analysis output. Correct: extracting the 3-5 lines relevant to the current phase question.

Blackboard layout

• .audit_board/status.json
• .audit_board/skill_monitor_context.json
• .audit_board/01_threat_model.md
• .audit_board/02_static_analysis.md
• .audit_board/03_attack_vectors.md
• .audit_board/04_proofs.md
• .audit_board/contest_context.json
• .audit_board/privilege_map.md
• .audit_board/invariant_map.md
• .audit_board/rule_scan.json
• .audit_board/rule_scan.md
• .audit_board/exploit_rankings.md
• .audit_board/exploit_hypotheses.md
• .audit_board/proof_status.json
• .audit_board/poc_spec.md
• .audit_board/severity_assessment.md
• .audit_board/submission_notes.md
• .audit_board/context_flattened.sol
• .audit_board/topology_map.txt
• .audit_board/external_calls.txt
• .audit_board/storage_layout.json
• .audit_board/phase1_tooling.log
• .audit_board/phase2_tooling.log
• .audit_board/PoC/

Persistent improvement memory:

• meta/skill_improvements.jsonl
• meta/skill_improvements.md
• meta/improvement_hotspots.json
• meta/resolved_hotspots.json

Mandatory Monitoring Pass

Before running Phase 0, perform a local monitoring pass setup for the skill execution.

Monitoring responsibilities:

• inspect .audit_board/status.json after every phase
• inspect any newly created artifact that is obviously low quality, incomplete, contradictory, or missing expected structure
• log only high-signal observations
• avoid duplicating identical observations already recorded in the same run
• propose concrete fixes, not vague criticism
• read meta/improvement_hotspots.json before starting so recurring weaknesses are checked first

When to log:

• the skill crashes, times out, or enters degraded mode unexpectedly
• the output is syntactically valid but clearly weak, underspecified, or missing required sections
• a script behavior contradicts SKILL.md
• a recurring warning/error suggests the skill design should change
• an obvious determinism, safety, or usability improvement becomes visible during execution

When not to log:

• normal degraded mode caused by genuinely missing external tools that the user did not install
• user-authored audit conclusions that are outside the scripted skill behavior
• speculative improvements with no clear evidence

Logging command:

python3 resources/log_improvement.py \
  --run-id <run_id> \
  --phase <phase_name> \
  --severity medium \
  --category output_quality \
  --summary "Threat model omitted privileged roles section" \
  --suggested-fix "Add a post-generation validator that checks for required threat-model headings." \
  --evidence .audit_board/01_threat_model.md

Suggested monitoring checklist:

Review `meta/improvement_hotspots.json` before the run. After each phase, inspect status plus the newly generated artifacts. If you see unintended behavior, low-quality output, contradictions with SKILL.md, or clear opportunities to improve determinism, safety, or usefulness, append exactly one structured log entry with resources/log_improvement.py. The log will refresh the hotspot and summary artifacts automatically. Do not block the main execution unless the failure is severe enough that the skill should stop.

Fast Improvement Loop

Before Phase 0:

• read meta/improvement_hotspots.json if it exists
• treat the top 3 hotspots as a preflight checklist for the current run

After any call to resources/log_improvement.py:

• meta/skill_improvements.md and meta/improvement_hotspots.json refresh automatically
• prefer fixing items that are both high severity and repeated across multiple runs

When the same hotspot recurs in 2+ runs:

• call it out explicitly in the monitor update
• if the current task is skill maintenance, patch that hotspot before adding new capability

When a hotspot is fixed:

• mark it with python3 resources/resolve_hotspot.py --action resolve --fingerprint <id> --resolution-note "<what changed>"
• do not delete historical evidence; resolved hotspots remain visible in summary artifacts
• if the same issue appears again later, reopen it with --action reopen

Phase 0: Initialize

Run:

• python3 resources/init_workspace.py --target-dir <target_contract_dir>

Purpose:

• create .audit_board/
• create missing placeholder artifacts without clobbering existing analyst-authored notes
• detect whether forge and slither are available
• record the inferred project root
• create .audit_board/skill_monitor_context.json with run_id and persistent log paths
• create placeholder contest, privilege, and invariant artifacts for later phases
• create placeholder rule-scan and exploit-ranking artifacts for later phases
• create placeholder exploit-hypothesis, proof-status, PoC-spec, severity, and submission artifacts for later phases

Success criteria:

• .audit_board/ exists
• .audit_board/status.json contains an init entry
• dependency availability is recorded in details.dependencies
• monitor context contains a run_id

Phase 1: Architecture Analysis

Run:

• python3 resources/analyze_architecture.py --target-dir <target_contract_dir>

Behavior:

• discovers Solidity files
• selects a deterministic primary contract, preferring concrete entrypoint-style contracts over interfaces and utility files
• runs forge flatten when available
• probes slither --list-printers and selects the first supported printer from the configured candidates for each section
• prefers a prebuilt Foundry path of forge build --build-info plus slither . --ignore-compile --print <printer> when forge is available
• falls back across multiple Slither invocation strategies, including auto-compile and target-directory runs, before declaring printer output unavailable
• treats Slither outputs such as No contract was analyzed / analyzed (0 contracts) as unusable noise, not successful printer output
• if Slither output is unavailable, emits a source-derived fallback topology with declarations, inheritance edges, and import relationships
• writes raw command output to .audit_board/phase1_tooling.log
• post-validates that required markdown artifacts contain substantive populated entries rather than empty headings

Artifacts:

• .audit_board/context_flattened.sol
• .audit_board/topology_map.txt
• .audit_board/contest_context.json
• .audit_board/privilege_map.md

Agent follow-up:

• write .audit_board/01_threat_model.md
• include trusted roles, privileged paths, asset flow, upgrade assumptions, oracle dependencies, and invariants
• read .audit_board/contest_context.json before deciding what is in-scope, known, or likely severity-capped
• use .audit_board/privilege_map.md to pressure-test stale-role and incomplete-rotation bugs
• when relevant, use references/sharp_edges.md to pressure-test upgrade, oracle, access-control, and composability assumptions before finalizing conclusions

Phase 2: State Vectors

Run:

• python3 resources/extract_state_vectors.py --target-dir <target_contract_dir>

Behavior:

• probes slither --list-printers and uses the first supported state-surface printer from function-summary, entry-points, and vars-and-auth
• prefers a prebuilt Foundry path of forge build --build-info plus slither . --ignore-compile --print <printer> when forge is available
• falls back across multiple Slither invocation strategies before declaring printer output unavailable
• treats Slither outputs such as No contract was analyzed / analyzed (0 contracts) as unusable noise, not successful state-surface output
• scans for delegatecall usage directly in source files while ignoring comments
• runs forge inspect <path:Contract> storageLayout for concrete non-test contracts when available
• retries forge inspect ... --force when storage layout is missing from artifacts due to cache issues
• marks the phase degraded when forge inspect produces no usable storage layouts for the inspected contracts, even if delegatecall scanning still found matches
• writes raw command output to .audit_board/phase2_tooling.log

Artifacts:

• .audit_board/external_calls.txt
• .audit_board/storage_layout.json
• .audit_board/invariant_map.md

Agent follow-up:

• write .audit_board/02_static_analysis.md
• separate confirmed anomalies, suspicious patterns, and blocked checks
• review .audit_board/invariant_map.md for setters that update address-linked state without role or permission rotation
• treat storage-layout output as supporting evidence, not as a reason to flood the improvement log with interface/library noise
• when relevant, use references/validations.md as a checklist for code patterns that deserve explicit confirmation or rejection

Phase 2.5: AST-Backed Semantic Extraction

Run:

• python3 resources/ast_semantic_index.py --target-dir <target_contract_dir>

Behavior:

• probes for slither --json output via slither --ignore-compile --json -, falling back to slither --json output.json, then slither with auto-compile, then slither --solc-remap
• if Slither JSON is available, parses it to produce provenance-tracked structural data: exact contract/function/state-var declarations, resolved Identifier nodes for state_reads, resolved Assignment targets for writes, true_writes/false_writes, external/internal call edges, member_calls, auth guards (onlyRole, onlyOwner, require(msg.sender == ...)), and slot assignments
• if Slither JSON is unavailable, falls back to enhanced brace-depth-aware regex extraction with the same output schema
• marks mode: "full" when Slither AST is consumed; mode: "degraded" when regex fallback was used
• sets _ast_mode: true and _ast_source: "slither-json"|"regex-fallback" in the output

Artifacts:

• .audit_board/ast_semantic_index.json

Downstream consumers:

• extract_actions.py, build_authority_graph.py, generate_finding_candidates.py, confirm_findings.py MUST prefer ast_semantic_index.json over semantic_index.json when the former is present.

Phase 3: Attack Vectors

This phase is manual reasoning by the agent.

Inputs:

• .audit_board/01_threat_model.md
• .audit_board/02_static_analysis.md
• .audit_board/contest_context.json
• .audit_board/privilege_map.md
• .audit_board/invariant_map.md
• .audit_board/rule_scan.md
• .audit_board/exploit_rankings.md
• .audit_board/exploit_hypotheses.md
• .audit_board/proof_status.json

Write:

• .audit_board/03_attack_vectors.md

Each attack vector should include:

• attacker prerequisites
• exploit path
• violated invariant
• value impact
• confidence
• missing evidence
• likely contest disposition when obvious: in-scope, known issue, severity-capped, needs-PoC

When relevant, use references/sharp_edges.md to avoid missing known exploit families, and use references/patterns.md only when proposing concrete mitigations or proof strategies.

Phase 3.5: Rule Scan

Run:

• python3 resources/rule_scan.py --target-dir <target_contract_dir>

Behavior:

• parses references/validations.md into native regex/context checks
• scans Solidity files under the target directory and emits normalized validation hits
• parses references/sharp_edges.md into exploit-family heuristics
• ranks likely exploit classes based on matched detection patterns

Artifacts:

• .audit_board/rule_scan.json
• .audit_board/rule_scan.md
• .audit_board/exploit_rankings.md

Agent follow-up:

• use .audit_board/rule_scan.md to seed 02_static_analysis.md with concrete, file-backed checks instead of manual grep alone
• use .audit_board/exploit_rankings.md to rank attack vectors before spending time on lower-signal hypotheses
• do not treat regex hits as confirmed findings; they are triage signals until source review proves impact

Phase 3.7: Hypothesis Triage

Run:

• python3 resources/triage_hypotheses.py --target-dir <target_contract_dir>

Behavior:

• fuses privilege_map, invariant_map, rule_scan, exploit_rankings, and existing attack-vector notes
• emits exploit hypotheses instead of raw pattern dumps
• tracks proof maturity and the next blocking confirmation step
• highlights likely high-signal classes such as broken recovery paths, asset lockups, stale authority, and external dependency deadlocks

Artifacts:

• .audit_board/exploit_hypotheses.md
• .audit_board/proof_status.json

Agent follow-up:

• prune weak hypotheses aggressively
• promote only repo-backed hypotheses into 03_attack_vectors.md
• make sure every surviving high-priority hypothesis has a concrete proof plan

Phase 3.8: PoC Design

Run:

• python3 resources/design_poc.py --finding-title "<finding_title>" [--target-contract-name <name>] [--target-contract-path <path>]

Behavior:

• searches the repo for reusable tests, fixtures, mocks, and helper utilities
• suggests the minimal harness needed to prove the finding deterministically
• records exact assertions, suggested state setup, and likely blocker assumptions
• produces severity framing that separates direct-loss issues from recovery or amplifier issues

Artifacts:

• .audit_board/poc_spec.md
• .audit_board/severity_assessment.md
• .audit_board/submission_notes.md

Agent follow-up:

• prefer the smallest deterministic proof over a full protocol redeploy
• implement only the assertions needed to prove impact
• keep the proof aligned with the likely contest submission style

Phase 4: Foundry Scaffold

Run:

• python3 resources/scaffold_tests.py --contract-name <target_contract_name> --contract-path <target_contract_path>
• optionally add --output-dir test/root-audit to colocate scaffolds with audit-specific proofs
• add --force only if replacing an existing scaffold is explicitly intended

Behavior:

• validates the contract name and import path
• refuses unsafe paths
• refuses to overwrite existing test files by default
• defaults output to test/root-audit/
• reuses test/Base.t.sol automatically when present
• injects contest, privilege, and invariant hints from .audit_board/ into the scaffold comments
• creates contract-specific exploit and invariant test templates
• now treats generated tests as proof-oriented scaffolds that must preserve measurable impact assertions and suggested harness reuse hints

Artifacts:

• <output-dir>/<ContractName>ExploitPoC.t.sol
• <output-dir>/<ContractName>InvariantTest.t.sol

Agent follow-up:

• implement setup and exploit logic
• prefer proving impact with the existing harness instead of redeploying the entire protocol from scratch
• run deterministic tests only after replacing TODO markers
• write .audit_board/04_proofs.md as confirmed, inconclusive, or rejected
• update .audit_board/proof_status.json when a hypothesis changes maturity

Phase 5: Submission Bundle

Run:

• python3 resources/build_submission_bundle.py --finding-id <slug> --title "<title>" --severity <severity> --template <minimal_with_poc|detailed_with_instructions|severity_argument_only> --poc-path <path>

Behavior:

• creates .audit_board/PoC/final_submission/ when missing
• writes a contest-ready report skeleton with the requested template
• copies or references the PoC file into the bundle
• updates a bundle manifest for multi-finding submissions

Artifacts:

• .audit_board/PoC/final_submission/
• .audit_board/PoC/final_submission/MANIFEST.md

Agent follow-up:

• tighten wording for the contest platform before final submission
• remove duplicate drafts so the bundle has a single preferred report per finding

Proof Maturity Labels

Proof maturity tracks each finding through a defined progression:

Proof Confirmability Labels

Each proof plan entry produced by plan_proofs.py MUST include a confirmability field:

Each proof plan also MUST include:

• false_positive_risk: low | medium | high | unknown — derived from guard equivalence, scope status, and parent inheritance checks
• blocking_assumptions: explicit list of preconditions that must hold for the PoC to work
• minimum_test_commands: concrete forge test / forge script commands that would exercise the finding

Finding Confirmation Schema

Each entry in finding_confirmations.json MUST include:

Prioritization Guidance

Bias triage toward:

1. In-scope authority drift, stale privilege, and broken recovery paths.
2. Asset-affecting accounting mismatches.
3. Oracle and external trust-boundary failures.
4. Upgrade and initialization hazards.

De-rank vectors that:

• rely on out-of-scope files without a strong in-scope bridge
• are already acknowledged in the README or prior audit context
• cannot be demonstrated through a compile-ready proof or deterministic state argument

Severity coaching:

• prefer High only when the proof demonstrates direct fund loss, permanent lockup, or irrecoverable liveness failure over protocol-owned assets
• prefer Medium for concrete but bounded asset or trust-boundary failures
• prefer Low for deterministic governance/recovery weaknesses that do not directly freeze or steal assets by themselves
• label amplifier findings as such in submission_notes.md

Examples

Initialize:

python3 resources/init_workspace.py --target-dir src

Architecture analysis:

python3 resources/analyze_architecture.py --target-dir src

State extraction:

python3 resources/extract_state_vectors.py --target-dir src

Rule scan:

python3 resources/rule_scan.py --target-dir src

Hypothesis triage:

python3 resources/triage_hypotheses.py --target-dir src

PoC design:

python3 resources/design_poc.py --finding-title "Expired auction remains unsettled due to stuck filler" --target-contract-name DutchTrade --target-contract-path contracts/plugins/trading/DutchTrade.sol

Scaffold tests:

python3 resources/scaffold_tests.py --contract-name Vault --contract-path src/Vault.sol

Build submission bundle:

python3 resources/build_submission_bundle.py --finding-id vault-lockup --title "Vault funds can be permanently locked" --severity High --template minimal_with_poc --poc-path test/root-audit/VaultExploitPoC.t.sol

Regression Validation

After changing the skill's contract-selection or architecture logic, run:

python3 resources/eval_regressions.py

This eval builds a minimal Foundry-style fixture with both IEVault.sol and EVault.sol and fails unless:

• the architecture phase prefers the concrete implementation contract
• degraded mode still emits a non-empty, source-derived topology artifact
• the storage-layout skip filter correctly excludes /test/, /interfaces/, /interface/, /mock/, /mocks/, /script/, /scripts/, and .t.sol files
• the skip filter correctly retains production contracts under src/

Scaffold overwrite:

python3 resources/scaffold_tests.py --contract-name Vault --contract-path src/Vault.sol --force

Improvement logging:

python3 resources/log_improvement.py --run-id run-2026-03-25T12-00-00+00-00 --phase architecture --severity high --category runtime_error --summary "forge flatten failed in a configured Foundry repo" --suggested-fix "Capture and classify stderr so the agent can retry intelligently." --evidence .audit_board/phase1_tooling.log