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 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

See 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

See iron-laws.md for complete rules.

References