sc-auditor

sc-auditor

Your AI-powered smart contract security co-pilot for Claude Code and Codex CLI.

Version: 2.0.0 | Author: Archethect

Table of Contents

• Overview
• What's New in v2.0.0
• How It Works
• Prerequisites
• Installation
• Configuration
• Quick Start
• Usage
  • Interactive Audit
  • Individual MCP Tools
• Audit Methodology
• Troubleshooting
• Development
• Credits
• License

Overview

sc-auditor turns your AI coding assistant into a security auditor. Point it at a Solidity codebase and it will map the architecture, dispatch six parallel agents to hunt for bugs across different vulnerability classes, then verify every finding through a Devil's Advocate pipeline that demands proof before confirmation.

Under the hood: static analysis (Slither, Aderyn), real-world vulnerability intelligence (Solodit), fuzz testing (Echidna, Medusa), symbolic execution (Halmos), and a rigorous Map-Hunt-Attack methodology — all orchestrated through prompt-driven multi-agent pipelines.

1. Interactive Audit Skill (/security-auditor) — a structured multi-phase pipeline with parallel agent lanes for systematic vulnerability discovery.
2. Individual MCP Tools — eight tools you can invoke directly for ad-hoc analysis.

What's New in v2.0.0

v2.0.0 is a ground-up rearchitecture. The hardcoded audit pipeline has been replaced with a prompt-driven multi-agent orchestration model — every phase is now executed by specialized sub-agents dispatched in parallel, with structured checkpoints for crash recovery and context-window resilience.

Parallel Hunt Lanes — Six specialized agents hunt simultaneously, each targeting a distinct vulnerability class: callback liveness, accounting/entitlement, semantic consistency, token/oracle statefulness, economic differentials, and an auto-triggered adversarial deep lane for cross-contract attack paths. Inspired by @pashov's structured agent lane methodology and adversarial verification approach.

Devil's Advocate Verification Pipeline — Every finding goes through a formal 6-dimension DA evaluation during ATTACK, then an independent skeptic (VERIFY) tries to break it with inversion mandate. Conflicts are resolved by a proof-based judge: "prove it or lose it."

Proof-or-Demote — ATTACK agents must attempt at least one proof method (Foundry PoC, Echidna, Medusa, Halmos) for confirmed vulnerabilities. In benchmark mode, unproven HIGH/MEDIUM findings are automatically demoted.

Checkpoint Discipline — Agents self-checkpoint after every phase. The orchestrator can resume from any phase after crashes, context compaction, or session interruptions.

Expanded Tool Suite — Eight MCP tools: Slither, Aderyn, Solodit search, Cyfrin checklist, Foundry PoC generation, Echidna fuzzing, Medusa fuzzing, and Halmos symbolic execution.

How It Works

                    /security-auditor src/
                           |
              SETUP -----> MAP -----> HUNT -----> ATTACK -----> VERIFY -----> REPORT
           (1 agent)   (1 agent)  (5-6 agents)  (N agents)   (N agents)
                                    parallel      parallel     parallel
                                       |
                  +--------------------+--------------------+
                  |          |         |         |          |
              Callback  Accounting  Semantic  Token/    Economic
              Liveness  Entitlement Consist.  Oracle    Differ.
                  |          |         |         |          |
                  +----+-----+---------+----+----+----------+
                       |                    |
                  Adversarial Deep     (auto-trigger)
                  (cross-contract)

Each HUNT lane produces prioritized hotspots. You pick which ones to deep-dive. ATTACK agents trace call paths, run the Devil's Advocate protocol, construct exploit sketches, and generate proofs. VERIFY agents independently challenge every finding with an inversion mandate. A judge resolves conflicts.

Prerequisites

Required

• Node.js >= 22 — Download from nodejs.org
• Claude Code CLI or Codex CLI — See Claude Code docs or Codex docs
• Solodit API Key — Required for the search_findings tool:
  1. Go to solodit.cyfrin.io
  2. Sign in > dropdown menu (top-right) > API Keys
  3. Generate and save your key

Optional (Recommended)

• Slither + solc — Static analysis: