⚡ ShadowForge Council

Multi-agent AI system for automated smart contract security auditing.

Overview

ShadowForge Council is a multi-agent AI framework that orchestrates multiple LLM instances with specialized security roles to perform deep smart contract audits. Each agent brings a distinct expertise — vulnerability hunting, exploit development, mathematical analysis — and their findings are synthesized into a unified, high-confidence report.

Think of it as a virtual security audit team that runs 24/7.

Architecture

┌──────────────────────────────────────────────────┐
│                  Council Orchestrator             │
│          (Parallel execution + consensus)         │
├──────────┬──────────┬──────────┬─────────────────┤
│  Agent 1 │  Agent 2 │  Agent 3 │    Agent N      │
│  VulnHunt│  Exploit │  Math    │    Custom...    │
│  (Grok)  │(DeepSeek)│ (Grok)   │                 │
└──────────┴──────────┴──────────┴─────────────────┘
     │           │           │
     └───────────┴───────────┘
              ▼
     ┌─────────────────┐
     │  Consensus Engine│
     │  (Dedup + Score) │
     └────────┬────────┘
              ▼
     ┌─────────────────┐
     │  Report Generator│
     │  (MD / JSON)     │
     └─────────────────┘

Features

Feature	Description
Multi-Agent	Run multiple AI models in parallel with specialized security roles
Provider Agnostic	Supports DeepSeek, Grok (xAI), and Ollama (local models)
Consensus	Cross-validates findings across agents to reduce false positives
Specialized Roles	Vulnerability Hunter, Exploit Developer, Math Auditor, Gas Optimizer
Report Generation	Outputs structured reports compatible with Immunefi submission format
Configurable	YAML-based configuration for agents, prompts, and thresholds

Quick Start

Installation

git clone https://github.com/eawhitehat/shadowforge-council.git
cd shadowforge-council
pip install -r requirements.txt
cp .env.example .env  # Add your API keys

Run an Audit

# Audit a Solidity file with the full council
python council.py audit --file ./contracts/Vault.sol

# Audit with specific agents only
python council.py audit --file ./contracts/Vault.sol --agents vuln_hunter,exploit_dev

# Audit from contract address (fetches source from explorer)
python council.py audit --address 0x... --chain ethereum

# Quick single-agent analysis
python council.py quick --file ./contracts/Token.sol --provider deepseek

Python API

from src.core.council import Council
from src.core.config import CouncilConfig

config = CouncilConfig.from_yaml("configs/default.yaml")
council = Council(config)

# Run full council audit
report = council.audit("path/to/Contract.sol")

# Access findings
for finding in report.findings:
    print(f"[{finding.severity}] {finding.title}")
    print(f"  Confidence: {finding.confidence}%")
    print(f"  Agreed by: {', '.join(finding.agreed_by)}")

Agent Roles

🔴 Vulnerability Hunter

Primary role: Identify attack vectors across all vulnerability classes. Focus: Reentrancy, access control, oracle manipulation, flash loans.

🟠 Exploit Developer

Primary role: Convert theoretical vulnerabilities into working PoCs. Focus: Foundry test scripts, attack contract code, step-by-step exploitation.

🟡 Mathematical Auditor

Primary role: Analyze numerical precision, invariants, and economic attacks. Focus: Rounding errors, division-before-multiplication, token exchange rates.

🔵 Architecture Reviewer

Primary role: Evaluate contract architecture and integration risks. Focus: Proxy patterns, upgrade safety, cross-contract interactions.

Configuration

# configs/default.yaml
council:
  name: "ShadowForge Council"
  consensus_threshold: 2  # Min agents that must agree on a finding
  parallel: true
  timeout: 120  # seconds per agent

agents:
  - name: vuln_hunter
    role: vulnerability_hunter
    provider: grok
    model: grok-3
    temperature: 0.1

  - name: exploit_dev
    role: exploit_developer
    provider: deepseek
    model: deepseek-chat
    temperature: 0.2

  - name: math_auditor
    role: mathematical_auditor
    provider: grok
    model: grok-3
    temperature: 0.0

Providers

Provider	Models	Local	API Key Required
DeepSeek	deepseek-chat, deepseek-coder	❌	✅
Grok (xAI)	grok-3, grok-3-mini	❌	✅
Ollama	Any local model	✅	❌

Disclaimer

This tool is designed for authorized security research and bug bounty hunting only. Always obtain proper authorization before auditing smart contracts. The authors are not responsible for misuse.

License

MIT License — see LICENSE for details.

---

Author: @eawhitehat — Web3 Security Researcher & Bug Bounty Hunter