ai-smart-contract-auditor 1.0.4

AI-powered smart contract security auditor with parallel processing

AI Smart Contract Auditor

Version 2.0.0 | Production-Ready Security Platform

An advanced AI-powered smart contract security auditing system with multi-agent architecture, comprehensive vulnerability database, and modern web interface. Built to detect vulnerabilities, generate proof-of-concept exploits, and provide actionable fix suggestions for Solidity, Vyper, and Rust smart contracts.

---

🚀 Quick Start

Command-Line Interface

# Clone repository
git clone https://github.com/jw3b-dev/AI-Smart-Contract-Auditor.git
cd AI-Smart-Contract-Auditor

# Run automated setup
bash scripts/setup.sh

# Run audit
python ai_auditor.py examples/vulnerable/reentrancy.sol

Web Interface

Deploy the modern React dashboard for managing audits through a user-friendly interface. See DOCUMENTATION.md for deployment instructions.

---

📋 Table of Contents

• Features
• Architecture
• Installation
• Usage
• File Structure
• Documentation
• Database
• Performance
• Contributing
• License

---

✨ Features

Core Auditing

The AI auditor employs a multi-agent architecture with five specialized agents working in concert to provide comprehensive security analysis. The Chief Auditor Agent orchestrates the overall audit workflow and synthesizes findings from all agents. The Static Analysis Agent performs code analysis using industry-standard tools like Slither and custom pattern matching. The Dynamic Analysis Agent conducts runtime testing with Foundry and Halmos for formal verification. The PoC Specialist Agent generates executable proof-of-concept exploits to validate vulnerabilities. Finally, the Validation & Reporting Agent cross-references findings against the vulnerability database and generates detailed reports.

Vulnerability Database

The system maintains an extensive database of 47,294 vulnerability findings and 305,943 proof-of-concept exploits sourced from leading security platforms. Data is integrated from Sherlock (16,469 findings, 304,406 PoCs), Solodit (7,013 findings), DeFiHackLabs (663 real-world exploits), 4naly3er (22,656 findings), and Web3Bugs (493 academic vulnerabilities). This comprehensive database enables semantic search and pattern matching to identify known vulnerability classes.

Advanced Features

PoC Generation: Automatically generates proof-of-concept exploits using AI-powered code synthesis, running 15x faster than manual creation.

Fix Suggestions: Provides specific, actionable fix recommendations with code examples, operating 20x faster than manual analysis.

Risk Scoring: Vulnerabilities are scored using a CVSS-style methodology considering impact, exploitability, and context.

Report Generation: Comprehensive audit reports can be exported in JSON, PDF, or Markdown formats.

Parallel Processing: Achieves 17.7x speedup through intelligent parallelization of analysis tasks.

Vector Database: ChromaDB integration with 14,291 embeddings enables sub-second semantic search.

Web Interface

The modern React-based dashboard provides an intuitive interface for managing audits. Features include contract upload with drag-and-drop, real-time audit progress tracking, interactive findings display organized by severity, multi-format report export, and responsive design for all devices.

CI/CD Integration

GitHub Actions workflows enable automated security auditing in continuous integration pipelines. Features include pre-commit hooks for local validation, configurable severity thresholds, Slack and email notifications, and automatic PR comments with findings.

Collaborative Auditing

Multi-auditor workflows support team-based security reviews with role-based access control, peer review systems, consensus-based validation, and comprehensive audit trails.

Custom Training

Protocol-specific fine-tuning capabilities allow AI models to specialize in particular DeFi protocols or contract patterns through training data management, vulnerability pattern definitions, and OpenAI fine-tuning integration.

---

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                      Web Interface                          │
│         React 19 + TypeScript + Tailwind CSS 4              │
└──────────────────────┬──────────────────────────────────────┘
                       │ tRPC API
┌──────────────────────┴──────────────────────────────────────┐
│                    Backend Server                           │
│         Express 4 + tRPC 11 + Drizzle ORM                   │
└──────────────────────┬──────────────────────────────────────┘
                       │ Python Bridge
┌──────────────────────┴──────────────────────────────────────┐
│                  AI Auditor Engine                          │
│           Multi-Agent System (5 Agents)                     │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────────────┐
│                   Data Layer                                │
│  MySQL/TiDB | ChromaDB | Vulnerability Database             │
└─────────────────────────────────────────────────────────────┘

See DOCUMENTATION.md for detailed architecture information.

---

📦 Installation

Prerequisites

• Python 3.11+ with pip
• Node.js 22+ with pnpm (for web interface)
• Foundry for dynamic analysis
• MySQL/TiDB database (for web interface)
• OpenAI API key

Core Auditor Setup

# Clone repository
git clone https://github.com/jw3b-dev/AI-Smart-Contract-Auditor.git
cd AI-Smart-Contract-Auditor

# Run automated setup
bash scripts/setup.sh

# OR manual installation:
pip install -r requirements.txt
curl -L https://foundry.paradigm.xyz | bash && foundryup
export OPENAI_API_KEY="your-api-key"

Web Interface Setup

cd /path/to/ai-auditor-web
pnpm install
pnpm db:push
pnpm dev  # Development
pnpm build && pnpm start  # Production

See DOCUMENTATION.md for complete installation instructions.

---

🔧 Usage

Command-Line Interface

# Basic audit
python ai_auditor.py examples/vulnerable/reentrancy.sol

# Multiple contracts
python ai_auditor.py examples/vulnerable/*.sol

# Generate PDF report
python ai_auditor.py examples/vulnerable/reentrancy.sol --output report.pdf --format pdf

# Quick check (static analysis only)
python ai_auditor.py examples/vulnerable/reentrancy.sol --quick

# Parallel processing
python ai_auditor.py examples/vulnerable/*.sol --parallel

Web Interface

1. Start the server: pnpm dev
2. Navigate to http://localhost:3000
3. Login with Manus OAuth
4. Upload contract via "New Audit"
5. Monitor progress and view findings
6. Export reports in desired format

CI/CD Integration

# Install GitHub Actions workflow
cp cicd/workflows/audit.yml .github/workflows/

# Install pre-commit hook
cp cicd/hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit

See DOCUMENTATION.md for comprehensive usage examples.

---

📁 File Structure

AI-Smart-Contract-Auditor/
│
├── README.md                          # This file
├── DOCUMENTATION.md                   # Complete technical guide
├── DEVELOPMENT.md                     # Developer guide
├── CHANGELOG.md                       # Version history
├── LICENSE                            # MIT License
│
├── ai_auditor.py                      # Main CLI entry point
├── requirements.txt                   # Python dependencies
│
├── src/                               # Source code
│   ├── main.py                       # Main application logic
│   ├── features/                     # Advanced features
│   │   ├── poc_generator.py          # PoC generation
│   │   ├── fix_suggester.py          # Fix recommendations
│   │   ├── risk_scorer.py            # Risk scoring
│   │   ├── report_generator.py       # Report generation
│   │   └── code4rena_filter.py       # Validation filtering
│   ├── tools/                        # External tool wrappers
│   │   ├── slither_wrapper.py        # Slither integration
│   │   ├── foundry_wrapper.py        # Foundry integration
│   │   └── 4naly3er_wrapper.py       # 4naly3er integration
│   ├── memory/                       # Vector database
│   │   └── vector_db.py              # ChromaDB integration
│   ├── parallel/                     # Parallel processing
│   │   ├── parallel_processor.py     # Core parallel engine
│   │   ├── parallel_audit.py         # Parallel auditing
│   │   └── parallel_database.py      # Parallel DB queries
│   ├── training/                     # Custom training
│   │   └── custom_training.py        # Training framework
│   └── utils/                        # Utilities
│       ├── checkpoints.py            # Checkpoint management
│       └── [scrapers and collectors]
│
├── database/                          # Vulnerability database
│   ├── vulnerability_db/
│   │   └── vulnerabilities_database.json  # 47,294 findings
│   ├── integrations/                 # Data integration scripts
│   │   ├── sherlock.py               # Sherlock integration
│   │   ├── solodit_findings.py       # Solodit integration
│   │   └── 4naly3er.py               # 4naly3er integration
│   └── processors/                   # Data processors
│       ├── defihacklabs_parser.py    # DeFiHackLabs parser
│       ├── extract_pocs.py           # PoC extraction
│       └── solodit_markdown_parser.py # Solodit parser
│
├── data/                              # Processed data
│   ├── processed/                    # Processed findings
│   │   ├── findings.json             # All findings
│   │   ├── pocs.json                 # All PoCs
│   │   └── statistics.json           # Statistics
│   └── embeddings/                   # Vector embeddings
│
├── data_sources/                      # Raw data (archived)
│   ├── README.md                     # Download instructions
│   ├── sherlock/                     # Sherlock data
│   ├── solodit/                      # Solodit data
│   ├── defihacklabs/                 # DeFiHackLabs data
│   ├── 4naly3er/                     # 4naly3er data
│   └── web3bugs/                     # Web3Bugs data
│
├── output/                            # Generated outputs (.gitignored)
│   ├── reports/                      # Audit reports
│   ├── fixes/                        # Fix suggestions
│   └── pocs/                         # Generated PoCs
│
├── examples/                          # Example contracts
│   ├── README.md                     # Usage guide
│   ├── vulnerable/                   # Vulnerable contracts
│   │   └── reentrancy.sol            # Reentrancy example
│   └── safe/                         # Safe implementations
│
├── tests/                             # Test suite
│   ├── unit/                         # Unit tests
│   ├── integration/                  # Integration tests
│   ├── e2e/                          # End-to-end tests
│   └── fixtures/                     # Test fixtures
│
├── benchmarks/                        # Performance benchmarks
│   └── results/                      # Benchmark results
│
├── cicd/                              # CI/CD integration
│   ├── workflows/audit.yml           # GitHub Actions workflow
│   ├── hooks/pre-commit              # Git pre-commit hook
│   ├── config/audit-ci.yml           # CI configuration
│   └── INSTALLATION.md               # Installation guide
│
├── collaboration/                     # Collaborative auditing
│   ├── collaborative_auditing.py     # Multi-auditor framework
│   └── audits/                       # Audit results
│
├── poc_library/                       # PoC catalog
│   ├── catalog.json                  # PoC catalog
│   ├── index.json                    # PoC index
│   └── statistics.json               # Statistics
│
├── poc_templates/                     # PoC templates
│   └── test_poc/                     # Foundry test template
│
├── scripts/                           # Setup and maintenance
│   ├── setup.sh                      # Installation script
│   ├── update_database.sh            # Database updates
│   └── validate_deployment.sh        # Deployment validation
│
├── docs/                              # Documentation
│   ├── archive/                      # Archived documents
│   ├── research/                     # Research notes
│   ├── images/                       # Diagrams and screenshots
│   └── api/                          # API documentation
│
├── config/                            # Configuration files
│   ├── default.yaml                  # Default configuration
│   └── examples/                     # Example configurations
│
└── .github/                           # GitHub-specific files
    ├── workflows/                    # GitHub Actions
    └── ISSUE_TEMPLATE/               # Issue templates

---

📚 Documentation

The project documentation is organized into four strategic documents:

DOCUMENTATION.md

Complete Technical Reference (20,000+ words)

Comprehensive guide covering all aspects of the system including introduction and overview, architecture and system design, installation and setup procedures, usage guide for all interfaces, detailed feature documentation, database information, API reference, and troubleshooting guides.

DEVELOPMENT.md

Developer Guide (15,000+ words)

In-depth information for contributors including development environment setup, architecture deep dive, database integration details, contributing guidelines and code style, testing procedures and coverage, deployment processes, and performance optimization techniques.

CHANGELOG.md

Version History

Complete changelog tracking all versions, features, and improvements including version 2.0.0 (current release), integration milestones, enhancement timeline, breaking changes, and deprecations.

Additional Resources

• cicd/INSTALLATION.md - CI/CD setup guide
• examples/README.md - Example contracts guide
• data_sources/README.md - Data sources documentation
• docs/archive/ - Historical documentation and reports
• Inline Documentation - Comprehensive docstrings in source code

---

💾 Database

Vulnerability Database Statistics

Source	Findings	PoCs	Description
Sherlock	16,469	304,406	Audit contest findings
Solodit	7,013	0	Aggregated audit reports
DeFiHackLabs	663	1,537	Real-world exploits
4naly3er	22,656	0	Automated analysis
Web3Bugs	493	0	Academic vulnerabilities
Total	47,294	305,943	Complete database

Vector Database

• Embeddings: 14,291 semantic vectors
• Technology: ChromaDB with OpenAI embeddings
• Search Speed: <1 second
• Dimensions: 1536 (text-embedding-3-small)

See DOCUMENTATION.md for database details.

---

⚡ Performance

Metric	Value	Description
Parallel Speedup	17.7x	Multi-contract acceleration
Success Rate	97.5%	Audit completion rate
Vector Search	<1s	Semantic search time
PoC Generation	15x faster	vs. manual creation
Fix Suggestions	20x faster	vs. manual analysis
Average Audit	2-5 min	Per contract

See DEVELOPMENT.md for optimization details.

---

🧪 Testing

The AI Smart Contract Auditor has a comprehensive test suite with 621 tests achieving 100% pass rate, 76.80% code coverage, and 2x faster execution with parallel testing.

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test categories
pytest tests/unit/           # Unit tests
pytest tests/integration/    # Integration tests
pytest tests/e2e/            # End-to-end tests
pytest tests/performance/    # Performance tests

# Run with benchmarks
pytest tests/performance/ --benchmark-only

Test Suite Statistics

Category	Tests	Status
Unit Tests	457	✅ 100% passing
Integration Tests	48	✅ 100% passing
E2E Tests	33	✅ 100% passing
Performance Tests	29	✅ 100% passing
Property-Based Tests	29	✅ 100% passing
Edge Case Tests	46	✅ 100% passing
Generated Data Tests	27	✅ 100% passing
TOTAL	621	✅ 100%

Test Documentation

For detailed testing information, see:

• tests/README.md - Complete testing guide
• tests/TEST_SUITE_STATUS.md - Test suite status
• DEVELOPMENT.md - Developer testing guide

---

🤝 Contributing

We welcome contributions! Please see DEVELOPMENT.md for detailed guidelines.

Quick Start

# Fork and clone
git clone https://github.com/YOUR_USERNAME/AI-Smart-Contract-Auditor.git
cd AI-Smart-Contract-Auditor

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pytest black flake8

# Run tests
python -m pytest

# Format code
black .

Code Style

• Follow PEP 8 for Python
• Use Black for formatting
• Add type hints to functions
• Write descriptive commit messages
• Include tests for new features

See DEVELOPMENT.md for complete style guide.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

This project builds upon the excellent work of the smart contract security community:

• Sherlock for comprehensive audit contest data
• Solodit for aggregated audit reports from 15 audit firms
• DeFiHackLabs for real-world exploit reproductions
• 4naly3er for automated analysis patterns
• Web3Bugs for academic vulnerability research
• OpenAI for GPT models powering AI analysis
• Trail of Bits for Slither static analyzer
• Foundry for dynamic analysis framework

---

📞 Support

• Documentation: DOCUMENTATION.md
• Developer Guide: DEVELOPMENT.md
• GitHub Issues: Submit an issue
• Changelog: CHANGELOG.md

---

🗺️ Roadmap

Completed (v2.0.0)

• ✅ Multi-agent architecture with 5 specialized agents
• ✅ Vulnerability database with 47K+ findings and 305K+ PoCs
• ✅ PoC generation, fix suggestions, risk scoring
• ✅ Web interface with React dashboard
• ✅ CI/CD integration with GitHub Actions
• ✅ Collaborative auditing workflows
• ✅ Custom training framework
• ✅ Code4rena validation filtering
• ✅ Vector database with 14K+ embeddings
• ✅ Comprehensive documentation
• ✅ Repository restructuring with clean organization

Planned (v2.1.0)

• 🔄 Email notifications for audit completion
• 🔄 API rate limiting for production use
• 🔄 Advanced analytics and charts
• 🔄 Mobile app for iOS/Android

Future (v3.0.0)

• 📋 Blockchain integration for on-chain verification
• 📋 Multi-chain support (Polygon, Arbitrum, Optimism)
• 📋 Enterprise features (SSO, RBAC, compliance reports)
• 📋 Real-time collaborative editing

See CHANGELOG.md for complete version history.

---

Built with ❤️ by the AI Smart Contract Auditor team

Star ⭐ this repository if you find it useful!

---

Version: 2.0.0
Last Updated: November 3, 2025
Status: Production Ready
Database: 47,294 vulnerabilities | 305,943 PoCs | 14,291 embeddings
Repository: Professionally restructured with clean organization