audit

# Smart Contract Security Audit Orchestrates the complete audit workflow from scope resolution to final report. ## Directory Structure At audit start, create: ``` .vigilo/ ├── recon/ ├── findings/ │ ├── high/ │ └── medium/ ├── poc/ └── reports/ ``` --- ## Workflow ``` Phase 0 Phase 1 Phase 2 Phase 3 Phase 4 (scope) (recon) (audit) (PoC) (report) │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ scope.txt ─→ explorator ──┐ speculator ──┼─→ recon/*.md ─→ sub-auditors ─→ findings/ ─→ PoC ─→ report │ (max 3 parallel) └─ protocol type detected ``` **Data Flow**: 1. **Phase 0**: Resolve scope.txt 2. **Phase 1**: Recon agents output to .vigilo/recon/ 3. **Phase 2**: Auditors READ recon results → SELECT auditors by protocol type → WRITE findings 4. **Phase 3**: PoC validates findings 5. **Phase 4**: Generate reports **CRITICAL**: Execute ALL phases automatically without waiting for user input. --- ## Phase 0: Scope Resolution ### Resolve Scope ``` 1. Read("scope.txt") → If exists, use it 2. Else Read("README.md") → Extract scope section, create scope.txt 3. Else Auto-detect: Glob("src/**/*.sol"), exclude test/mock/lib ``` See [scope-resolution.md](references/scope-resolution.md) for detailed logic. **→ IMMEDIATELY proceed to Phase 1** --- ## Phase 1: Reconnaissance (Parallel) Launch both agents in parallel: ``` Task(subagent_type="explorator", prompt="Analyze code structure.") Task(subagent_type="speculator", prompt="Analyze documentation.") ``` **Output:** - .vigilo/recon/code-findings.md - .vigilo/recon/docs-findings.md **→ IMMEDIATELY proceed to Phase 2 when both complete** --- ## Phase 2: Deep Analysis (Parallel, Max 3 Auditors) ### Step 1: Read Recon Results Read the recon outputs: - .vigilo/recon/code-findings.md - .vigilo/recon/docs-findings.md Extract from recon: - **Protocol Type**: AMM/Lending/Vault/Governance/Bridge/Staking - **Key Entry Points**: Main functions to audit - **Identified Risks**: Preliminary vulnerability hints ### Step 2: Select Auditors Based on Protocol Type | Protocol Type | Auditors | |--------------|----------| | AMM/DEX | flashloan-auditor, oracle-auditor, reentrancy-auditor | | Lending | oracle-auditor, logic-auditor, flashloan-auditor | | Vault/ERC4626 | logic-auditor, reentrancy-auditor, defi-auditor | | Governance | flashloan-auditor, access-control-auditor, logic-auditor | | Bridge | cross-chain-auditor, access-control-auditor, reentrancy-auditor | | Staking | logic-auditor, reentrancy-auditor, defi-auditor | See [auditor-selection.md](references/auditor-selection.md) for detailed guidance. ### Step 3: Launch 3 Auditors in Parallel **CRITICAL**: Include recon context in prompt so auditors use the gathered information. Launch Task for each auditor with prompt containing: - Protocol Type: (from recon) - Key Entry Points: (from recon) - Instructions to read recon from .vigilo/recon/ - Instructions to write findings to .vigilo/findings/{severity}/{auditor-type}/ **Example prompt for sub-auditor:** ``` You are the reentrancy-auditor. Analyze for reentrancy vulnerabilities. Read recon: .vigilo/recon/code-findings.md Write findings to: .vigilo/findings/high/reentrancy/ ``` Launch all 3 auditors **in a single message** (parallel execution). **CRITICAL**: Auditors write attack scenarios only, NO PoC code. **Output:** .vigilo/findings/{severity}/{auditor}/ **→ IMMEDIATELY proceed to Phase 3 when all complete** --- ## Phase 3: PoC Validation (Sequential) For each High/Medium finding: 1. Read finding from .vigilo/findings/{severity}/{auditor}/ 2. Invoke Skill(vigilo:poc) with finding path 3. PoC generates test → `test/poc/{Severity}-{id}-{title}.t.sol` 4. Validation log → `.vigilo/poc/{Severity}-{id}-{title}.md` 5. Run forge test, handle failures (max 3 retries) 6. Validate: Test pass + assertions prove impact → VALIDATED **File Naming Convention**: `{Severity}-{id}-{kebab-case-title}` ``` Example for "H-01-donation-attack-inflated-collateral": - Scenario: .vigilo/findings/high/logic/H-01-donation-attack-inflated-collateral.md - PoC Code: test/poc/H-01-donation-attack-inflated-collateral.t.sol - PoC Log: .vigilo/poc/H-01-donation-attack-inflated-collateral.md ``` **CRITICAL**: Test passing ≠ VALIDATED. PoC must prove the claimed impact. **→ IMMEDIATELY proceed to Phase 4 when all findings processed** --- ## Phase 4: Report Generation Invoke Skill(vigilo:report) Generates submission-ready reports: - .vigilo/reports/submissions/H-01-donation-attack-inflated-collateral.md - .vigilo/reports/submissions/M-01-stale-price-check.md Each report is copy-paste ready for target platform (default: Code4rena). --- ## Iron Laws | Rule | Description | |------|-------------| | **SCOPE FIRST** | Always check scope.txt before analyzing code | | **NO POC WITHOUT SCENARIO** | Auditors write scenarios, main agent generates PoC | | **TEST PASS ≠ VALIDATED** | PoC must prove claimed impact, not just pass | | **AUTO-CONTINUE** | No waiting for user between phases | See [iron-laws.md](references/iron-laws.md) for complete rules. --- ## References | File | When to Load | |------|--------------| | [scope-resolution.md](references/scope-resolution.md) | Phase 0: Scope resolution details | | [auditor-selection.md](references/auditor-selection.md) | Phase 2: Protocol-specific auditor selection | | [iron-laws.md](references/iron-laws.md) | All phases: Critical rules |