Plamen — Web3 Security Auditor for Claude Code

An autonomous smart contract security audit agent for Claude Code. Orchestrates 15–95 specialized AI agents across 8 phases to produce comprehensive security audit reports — from reconnaissance to verified PoC exploits.

Supports EVM/Solidity, Solana/Anchor, Aptos Move, and Sui Move via a tree architecture with shared rules and language-specific analysis branches.

Built for Claude Opus 4.6 (1M context). Works on Max (Core/Thorough) and Pro (Light mode) subscriptions.

Shell: All commands use Unix syntax. On Windows, use Git Bash (included with Git for Windows). On macOS/Linux, use your regular terminal. If pip/python don't work, try pip3/python3 instead.

Why ~/.claude? Claude Code reads its configuration, slash commands, agent definitions, and MCP server settings from ~/.claude/. This is not configurable — the repo must be cloned to this exact location for /plamen and all pipeline features to work.

Existing Claude Code users: ~/.claude will be overwritten. Back up your existing config first:

mv ~/.claude ~/.claude.backup

# 1. Clone into ~/.claude (required — Claude Code reads config from this path)
git clone https://github.com/PlamenTSV/plamen.git ~/.claude
cd ~/.claude

# 2. Initialize submodules (slither-mcp, farofino-mcp)
git submodule update --init --recursive

# 3. Install Python deps
pip install -r requirements.txt

# 4. Install MCP server deps (~2GB download — includes PyTorch for embeddings)
pip install -r custom-mcp/unified-vuln-db/requirements.txt
pip install -r custom-mcp/solodit-scraper/requirements.txt
pip install -r custom-mcp/defihacklabs-rag/requirements.txt
pip install -e custom-mcp/solana-fender
pip install -r custom-mcp/farofino-mcp/requirements.txt

# 4b. EVM users only — install slither MCP (requires Python 3.11+, solc)
pip install -e custom-mcp/slither-mcp    # skip if not auditing Solidity

# 5. Configure MCP servers + API keys (BEFORE building RAG)
cp mcp.json.example mcp.json
cp settings.json.example settings.json
# Edit mcp.json — add your API keys (see Configuration below)
# At minimum, get a free Solodit key: https://solodit.cyfrin.io
# Then set it for the current shell:
export SOLODIT_API_KEY=your_key_here     # needed for step 6

# 6. Build the RAG vulnerability database (~5 min, requires internet)
#    Without SOLODIT_API_KEY: only ~700 entries indexed (vs ~4000 with it)
cd custom-mcp/unified-vuln-db
python -m unified_vuln.indexer index -s solodit --max-pages 10
python -m unified_vuln.indexer index -s defihacklabs
python -m unified_vuln.indexer index -s immunefi
cd ../..

# 7. Run (terminal wrapper with interactive UI)
python plamen.py
# Or from Claude Code: /plamen
# Or add ~/.claude to PATH and just type: plamen

You'll need a smart contract project to audit (e.g., a Foundry or Hardhat project). The Setup menu inside the wrapper can install chain-specific tools (Foundry, Solana, Aptos, Sui) for you.

Having trouble? Open Claude Code and paste the contents of SETUP.md — it contains step-by-step instructions that Claude Code can follow to install everything for you automatically.

• Architecture
• Audit Modes
• How It Works
• Language Support
• Skill System
• Security Rules
• MCP Servers
• Prerequisites
• Installation
• Configuration
• Building the RAG Database
• Two Ways to Run
• Repository Structure
• Severity Matrix
• Cost Estimation
• Contributing
• License

                          ┌─────────────────────────────────┐
                          │       ORCHESTRATOR (CLAUDE.md)   │
                          │  Detects language, reads phase   │
                          │  prompts, spawns agents,         │
                          │  enforces gates                  │
                          └──────────┬──────────────────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          ▼                          ▼                          ▼
   ┌──────────────┐          ┌──────────────┐          ┌──────────────┐
   │  Phase 1     │          │  Phase 2     │          │  Phase 3     │
   │  RECON       │───────►  │  INSTANTIATE │───────►  │  BREADTH     │
   │  (4 agents)  │          │  (orchestr.) │          │  (2-7 agents)│
   └──────────────┘          └──────────────┘          └──────┬───────┘
                                                              │
          ┌───────────────────────────────────────────────────┘
          ▼
   ┌──────────────┐     ┌──────────────┐     ┌─────────────────┐
   │  Phase 3b    │     │  Phase 3c    │     │  Phase 4a       │
   │  RE-SCAN     │──►  │  PER-CONTRACT│──►  │  INVENTORY      │
   │  (sonnet,    │     │  (sonnet,    │     │  + Side Effect  │
   │   2 iters)   │     │   1/cluster) │     │  Trace Audit    │
   └──────────────┘     └──────────────┘     └──────┬──────────┘
                                                    │
          ┌─────────────────────────────────────────┘
          ▼
   ┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
   │  Phase 4a.5  │     │  Phase 4b       │     │  Phase 4c    │
   │  SEMANTIC    │──►  │  DEPTH LOOP     │──►  │  CHAIN       │
   │  INVARIANTS  │     │  (8+ agents ×   │     │  ANALYSIS    │
   │  (sonnet)    │     │   1-3 iters)    │     │  + Enablers  │
   └──────────────┘     │  + Niche agents │     └──────┬───────┘
                        │  + Inv. Fuzz    │            │
                        │  + Medusa Fuzz  │            │
                        │  + Design Stress│            │
                        └─────────────────┘            │
                                                       │
          ┌────────────────────────────────────────────┘
          ▼
   ┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
   │  Phase 5     │     │  Phase 5.1   │     │  Phase 6         │
   │  VERIFY      │──►  │  SKEPTIC-    │──►  │  REPORT          │
   │  (N verifier │     │  JUDGE       │     │  Index → 3 Tier  │
   │   agents)    │     │  (Thorough)  │     │  Writers →       │
   └──────────────┘     └──────────────┘     │  Assembler       │
                                              └──────────────────┘
                                                      │
                                                      ▼
                                               AUDIT_REPORT.md

The workflow is fully autonomous — provide a smart contract project and optionally documentation. The orchestrator detects the language, loads the appropriate branch, and handles everything from pattern detection to PoC verification to final report assembly.

Proven-only mode (--proven-only): Available in all modes. Caps findings with only [CODE-TRACE] evidence (no executed PoC or fuzzer counterexample) at Low severity. Useful for benchmark comparisons where only mechanically proven findings should drive severity.

Split into 4 agents to prevent timeout:

• Agent 1A (sonnet): RAG queries — unified-vuln-db, Solodit live search
• Agent 1B (opus): Documentation parsing, fork ancestry research, trust model extraction
• Agent 2 (sonnet): Build environment, static analysis (Slither → Farofino/Aderyn → grep fallback), test suite
• Agent 3 (opus): Pattern detection, attack surface mapping, template recommendations with BINDING MANIFEST

Produces 17+ scratchpad artifacts consumed by all downstream phases.

Reads the BINDING MANIFEST, resolves skill templates, applies merge hierarchy (max 3 skills/agent), and composes agent prompts with instantiated parameters.

All agents spawned in a single message. Each runs a targeted sweep per vulnerability class across its scope, producing findings with precondition/postcondition analysis.

• Re-scan: 2-3 sonnet agents re-analyze with an exclusion list of known findings. Counters LLM attention saturation.
• Per-contract: 1 agent per contract/cluster at maximum depth. Zero distraction from other contracts.

Consolidates all findings, promotes static analysis results, performs side effect trace audit on external token interactions.

Sonnet agent enumerates write sites, defines semantic invariants, detects mirror variables, flags conditional writes and accumulation exposures. Pass 2 (Thorough) traces consequences recursively.

Iteration 1 (always): 4 depth agents + 3 blind spot scanners + validation sweep + niche agents, all in parallel.

Niche agents (flag-triggered, 1 budget slot each):

• EVENT_COMPLETENESS — event emission coverage
• SEMANTIC_GAP_INVESTIGATOR — sync gaps, accumulation exposure, conditional writes
• SPEC_COMPLIANCE_AUDIT — spec-to-code compliance
• SIGNATURE_VERIFICATION_AUDIT — replay, malleability, EIP-712, nonces
• SEMANTIC_CONSISTENCY_AUDIT — cross-contract unit mismatches, formula drift, magic numbers

Invariant fuzzing (EVM Thorough only):

• Foundry invariant fuzz campaign (from semantic invariants)
• Medusa stateful fuzz campaign (parallel, standalone harness, 15-min timeout)

Iterations 2-3 (Thorough): Devil's Advocate agents re-examine uncertain findings with structural adversarial role, contrastive path summaries, fresh MCP calls.

Confidence scoring (haiku, batched): 4-axis model (Evidence × 0.25 + Consensus × 0.25 + Analysis Quality × 0.3 + RAG Match × 0.2). Routes findings to CONFIDENT/UNCERTAIN/LOW_CONFIDENCE with severity-weighted spawn priority.

• Agent 1: Exhaustive enabler enumeration (5 actor categories per dangerous state), finding grouping with anti-absorption rules
• Agent 2: Postcondition→precondition chain matching, composition coverage map, RAG validation for chains

Mandatory PoC execution. Every finding gets:

1. Written PoC from language-specific templates
2. Compiled and executed (max 5 retry attempts with structured recovery)
3. Fuzz variant (Medium+, Thorough mode)
4. Evidence tagged: [POC-PASS], [POC-FAIL], [CODE-TRACE], [MEDUSA-PASS]

Pre-PoC feasibility gates (Reachability + Math Bounds) prevent wasted verification effort.

After standard verification:

1. Skeptic (sonnet): INVERSION MANDATE — if standard said CONFIRMED, skeptic tries to REFUTE, and vice versa
2. If skeptic AGREES → high confidence (dual-confirmed)
3. If skeptic DISAGREES → Judge (haiku): "prove it or lose it" — stronger mechanical evidence wins

• Index Agent (haiku): Clean ID assignment, root-cause consolidation, tier assignment, strict mode demotion
• 3 Tier Writers (parallel): Opus for Critical+High, Sonnet for Medium, Sonnet for Low+Info
• Assembler (haiku/sonnet): Merges sections, quality checks, writes AUDIT_REPORT.md

Tree architecture — shared root with language-specific branches. No file contains content for more than one language.

Language detection is automatic (Step 0) based on config files and source file patterns.

Skills are methodology files loaded into agents at instantiation time. Three tiers:

Always-available skills triggered by pattern flags from recon. Examples: ORACLE_ANALYSIS, SEMI_TRUSTED_ROLES, TOKEN_FLOW_TRACING, FLASH_LOAN_INTERACTION.

Loaded only when recon classifies the protocol as a matching type. Appended to existing agents (no new agent spawned):

Spawn as independent agents (1 depth budget slot each). Used when a concern needs dedicated focus:

16 rules (R1–R16) enforced across all agents:

Plamen uses 9 MCP servers configured in mcp.json. 2 are bundled in custom-mcp/, 2 are git submodules, 5 are npm packages. Two additional bundled libraries (solodit-scraper, defihacklabs-rag) serve as data sources for the RAG database.

EVM/Solidity:

Solana:

Aptos Move:

Sui Move:

git clone https://github.com/PlamenTSV/plamen.git ~/.claude
cd ~/.claude
git submodule update --init --recursive

Note: This clones into ~/.claude which is where Claude Code looks for its configuration. If you already have a ~/.claude directory, back it up first.

# Plamen wrapper
pip install -r requirements.txt

# MCP servers (~2GB download — includes PyTorch for embeddings)
pip install -r custom-mcp/unified-vuln-db/requirements.txt
pip install -r custom-mcp/solodit-scraper/requirements.txt
pip install -r custom-mcp/defihacklabs-rag/requirements.txt
pip install -e custom-mcp/solana-fender
pip install -r custom-mcp/farofino-mcp/requirements.txt

# EVM users only (requires Python 3.11+, solc)
pip install -e custom-mcp/slither-mcp

cp mcp.json.example mcp.json
cp settings.json.example settings.json

Edit mcp.json with your API keys. See Configuration. At minimum, get a free Solodit API key — it's needed to index the largest RAG data source (3400+ findings).

The default settings.json.example auto-approves all tool calls required for autonomous auditing. Critical permissions — removing any of these will break the pipeline:

The deny list blocks destructive operations (rm -rf, sudo, force push). Review and adjust if desired.

The env block sets MCP timeouts: MCP_TIMEOUT (30s connection) and MCP_TOOL_TIMEOUT (300s = 5 min execution). The 5-minute tool timeout accounts for ChromaDB cold start on first use — the RAG database and embedding model load into memory on the first MCP call per session, which can take 1-5 minutes. After warm-up, calls return in seconds.

Set your Solodit key first, then build:

export SOLODIT_API_KEY=your_key_here

See Building the RAG Database for full instructions.

python plamen.py

The startup screen runs a dependency check showing which tools are available.

Copy mcp.json.example to mcp.json and configure:

The example below shows a subset. Copy mcp.json.example for the full 9-server configuration including solana-fender, farofino, and memory.

{
  "mcpServers": {
    "slither-analyzer": {
      "command": "slither-mcp",
      "args": []
    },
    "unified-vuln-db": {
      "command": "python",
      "args": ["-m", "unified_vuln.server"],
      "cwd": "./custom-mcp/unified-vuln-db"
    },
    "foundry-suite": {
      "command": "npx",
      "args": ["-y", "@pranesh.asp/foundry-mcp-server"],
      "env": { "RPC_URL": "YOUR_RPC_URL" }
    },
    "evm-chain-data": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server"],
      "env": { "ETHERSCAN_API_KEY": "YOUR_KEY" }
    },
    "tavily-search": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": { "TAVILY_API_KEY": "YOUR_KEY" }
    },
    "helius": {
      "command": "npx",
      "args": ["-y", "helius-mcp@latest"],
      "env": { "HELIUS_API_KEY": "YOUR_KEY" }
    }
  }
}

Path notes: The cwd fields use relative paths (./custom-mcp/...). Claude Code resolves these relative to ~/.claude/. If you installed elsewhere, use absolute paths.

All keys are optional. The pipeline degrades gracefully — missing keys mean reduced coverage, not failure. You can leave YOUR_* placeholders in mcp.json and the pipeline will skip those services.

Recommended: Get the free Solodit API key — it provides 3400+ indexed findings vs ~700 without it. The Tavily key is also recommended as the WebSearch fallback when RAG MCP tools are slow on first use.

The unified-vuln-db MCP server uses a ChromaDB vector database populated from three sources. Build it before your first audit.

cd custom-mcp/unified-vuln-db

# Index from all sources
python -m unified_vuln.indexer index -s solodit --max-pages 10
python -m unified_vuln.indexer index -s defihacklabs
python -m unified_vuln.indexer index -s immunefi

# Verify
python -m unified_vuln.indexer stats

# Index ALL Solodit findings (thousands of pages)
python -m unified_vuln.indexer index -s solodit --max-pages 100

# Clone DeFiHackLabs dataset for deeper coverage
git clone https://github.com/SunWeb3Sec/DeFiHackLabs.git data/DeFiHackLabs
python -m unified_vuln.indexer index -s defihacklabs

# Immunefi
python -m unified_vuln.indexer index -s immunefi

python -m unified_vuln.indexer clear
# Then run the index commands above

The data/ directory (ChromaDB, caches) is gitignored. Each user builds their own database.

The first MCP tool call in each Claude Code session loads the ChromaDB database and sentence-transformers embedding model into memory. This can take 1-5 minutes depending on your hardware. Subsequent calls are instant. The pipeline handles this automatically — the recon agent's probe-first pattern detects slow MCP responses and falls back to WebSearch (Tavily) or code-level analysis.

Plamen can be launched from its dedicated terminal wrapper or from inside Claude Code. Both go through the same audit pipeline — the difference is how you start it.

The terminal wrapper is a standalone Rich + InquirerPy application that handles dependency checking, tool installation, cost estimation, and launches Claude Code for you.

plamen

This opens an interactive UI with arrow-key menus:

 ██████╗ ██╗      █████╗ ███╗   ███╗███████╗███╗   ██╗
 ██╔══██╗██║     ██╔══██╗████╗ ████║██╔════╝████╗  ██║
 ██████╔╝██║     ███████║██╔████╔██║█████╗  ██╔██╗ ██║
 ██╔═══╝ ██║     ██╔══██║██║╚██╔╝██║██╔══╝  ██║╚██╗██║
 ██║     ███████╗██║  ██║██║ ╚═╝ ██║███████╗██║ ╚████║
 ╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝

⬡ Web3 Security Auditor  v1.0.0

> Select audit mode:
    Light      15-18 agents | Pro plan  | best under 3k LOC
    Core       25-45 agents | Max plan  | ALL severities
    Thorough   35-95 agents | Max plan  | ALL severities + fuzz
    ──────────
    Compare    variable     | DELTA report
    Setup      install tools + build RAG DB

The Setup option shows your full toolchain status and lets you install missing tools (Foundry, Solana, Aptos, Sui, Medusa, etc.) and build the RAG database — all from the same UI, with automatic prerequisite detection and cross-platform support (Windows, macOS, Linux).

After selecting a mode, the wrapper walks you through target selection, documentation, scope, proven-only mode, shows a cost estimate, then hands off to Claude Code.

To make plamen available as a command, add ~/.claude to your PATH:

# Unix/macOS — add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.claude:$PATH"

# Windows — run once in PowerShell
[System.Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.claude;" + $env:Path, "User")

Or run directly without PATH setup:

python ~/.claude/plamen.py          # any platform
./plamen.sh                         # Unix/macOS
plamen.bat                          # Windows

CLI fast path (skip the wizard):

plamen core /path/to/project --docs whitepaper.pdf
plamen thorough /path/to/project --scope scope.txt --network ethereum --proven-only
plamen setup                        # just run the installer

If you're already in a Claude Code session, type /plamen to launch the audit wizard directly:

> /plamen

This presents a mode selection dialog with previews inside Claude Code, then walks you through target, docs, scope, and launches the full pipeline — all within the same session.

You can also skip the wizard with arguments:

> /plamen core /path/to/project docs: /path/to/docs
> /plamen thorough /path/to/project scope: scope.txt proven-only: true
> /plamen compare report: audit.md ground_truth: reference.md

~/.claude/
├── CLAUDE.md                          # Orchestrator — mode table, critical rules, file refs
├── plamen.py                          # Terminal wrapper (Rich + InquirerPy)
├── plamen.sh / plamen.bat             # Launcher scripts
├── VERSION                            # Semantic version
│
├── commands/
│   └── plamen.md                      # /plamen slash command — wizard + full workflow
│
├── rules/                             # Shared rules (all languages)
│   ├── finding-output-format.md       # Finding template, Rules Applied, Depth Evidence Tags
│   ├── phase3b-rescan-prompt.md       # Breadth re-scan (Thorough)
│   ├── phase4-confidence-scoring.md   # 4-axis scoring, anti-dilution, convergence
│   ├── phase4c-chain-prompt.md        # Chain analysis — enabler enum + chain matching
│   ├── phase5-poc-execution.md        # Mandatory PoC execution protocol
│   ├── phase6-report-prompts.md       # Report pipeline — Index → Tier Writers → Assembler
│   ├── report-template.md             # Report format, severity matrix, consolidation
│   ├── skill-index.md                 # Master skill registry (all trees)
│   └── post-audit-improvement-protocol.md  # Compare mode methodology
│
├── agents/                            # Agent definitions (language-agnostic)
│   ├── depth-token-flow.md
│   ├── depth-state-trace.md
│   ├── depth-edge-case.md
│   ├── depth-external.md
│   ├── security-analyzer.md
│   └── security-verifier.md
│
├── prompts/                           # Language-specific prompts
│   ├── evm/                           # 10 files (includes invariant-fuzz)
│   ├── solana/                        # 9 files
│   ├── aptos/                         # 9 files
│   └── sui/                           # 9 files
│   # Each tree contains:
│   #   phase1-recon-prompt.md         — 4-agent recon with BINDING MANIFEST
│   #   phase4a-inventory-prompt.md    — inventory + side effect trace
│   #   phase4b-loop.md               — adaptive depth loop orchestration
│   #   phase4b-depth-templates.md    — 4 depth agent prompts
│   #   phase4b-scanner-templates.md  — 3 scanners + validation sweep + design stress
│   #   phase5-verification-prompt.md — verifier + skeptic-judge (EVM)
│   #   generic-security-rules.md     — R1-R16 enforcement
│   #   self-check-checklists.md      — per-phase quality gates
│   #   mcp-tools-reference.md        — MCP tool usage guide
│
├── agents/skills/
│   ├── evm/                           # 18 EVM skill templates
│   ├── solana/                        # 19 Solana skill templates
│   ├── aptos/                         # 21 Aptos skill templates
│   ├── sui/                           # 21 Sui skill templates
│   ├── injectable/                    # 5 protocol-type-specific skills
│   └── niche/                         # 5 flag-triggered niche agents
│
├── custom-mcp/                        # MCP servers
│   ├── unified-vuln-db/               # RAG vulnerability database (code only, data/ gitignored)
│   │   ├── unified_vuln/
│   │   │   ├── server.py              # MCP server entry point
│   │   │   ├── indexer.py             # CLI: index, clear, stats
│   │   │   ├── database.py            # ChromaDB interface
│   │   │   ├── schema.py              # Vulnerability data model
│   │   │   ├── chunking.py            # Document chunking
│   │   │   └── sources/               # Data source adapters
│   │   │       ├── solodit.py         # Solodit API + content parser
│   │   │       ├── defihacklabs.py    # DeFiHackLabs exploit corpus
│   │   │       ├── immunefi.py        # Immunefi bug bounty data
│   │   │       └── huggingface.py     # Disabled (diluted results)
│   │   ├── requirements.txt
│   │   └── setup.py
│   ├── solodit-scraper/               # Solodit API scraper with SQLite cache
│   │   ├── solodit_mcp/
│   │   │   ├── server.py
│   │   │   ├── scraper.py
│   │   │   └── database.py
│   │   └── requirements.txt
│   ├── defihacklabs-rag/              # DeFiHackLabs ChromaDB embeddings
│   │   ├── defihacklabs_mcp/
│   │   │   ├── server.py
│   │   │   └── indexer.py
│   │   └── requirements.txt
│   ├── solana-fender/                 # Solana static analysis
│   │   ├── solana_fender_mcp/
│   │   │   ├── __init__.py
│   │   │   └── __main__.py
│   │   └── setup.py
│   ├── farofino-mcp/                  # [submodule] Aderyn + pattern analysis
│   └── slither-mcp/                   # [submodule] Trail of Bits Slither
│
├── mcp.json.example                   # MCP server config template
├── settings.json.example             # Permissions config template
├── requirements.txt                   # Python deps (Rich, InquirerPy)
├── .gitmodules                        # Submodule refs (farofino, slither)
└── .gitignore

Impact × Likelihood:

Downgrade modifiers: on-chain-only exploit (−1 tier), view-function-only (cap Medium), fully-trusted actor required (−1 tier, floor Info).

The plamen.py wrapper estimates token usage before launch, accounting for multi-turn context accumulation per agent. Estimates displayed in the launch summary:

• Input/Output tokens (millions)
• API cost (USD, at current Anthropic pricing)
• Weekly plan usage (% of Pro, Max x5, and Max x20 allowances)

Estimates are rough — actual usage varies with protocol complexity and finding count. Run /cost after an audit for actuals.

Findings carry evidence tags that determine confidence scoring:

See CONTRIBUTING.md. In short:

1. Fork the repository
2. Create a feature branch
3. Follow the anti-bloat gates from post-audit-improvement-protocol.md
4. Submit a PR with the template

MIT

• Trail of Bits — Slither MCP server
• Farofino — Aderyn integration
• SunWeb3Sec — DeFiHackLabs exploit corpus
• Solodit — Audit finding database
• Anthropic — Claude Code runtime