SolidityGuard AI 🛡️

AI-Powered Smart Contract Security Audit Tool

A sophisticated multi-agent AI system that performs comprehensive security audits on Solidity smart contracts using adversarial reasoning, static analysis simulation, and attack scenario modeling.

---

📊 Status & Badges

GitHub Activity:

---

📋 Overview

SolidityGuard AI is an open-source smart contract security auditing framework powered by CrewAI. It deploys a 6-agent sequential pipeline to analyze Solidity contracts for vulnerabilities across multiple dimensions:

🔄 Reentrancy & MEV attacks 🔐 Access control flaws 🧮 Arithmetic vulnerabilities (overflow/underflow) ⚙️ Logic errors & state inconsistencies 💰 Economic incentive attacks 🚫 Denial of Service vectors

Each agent specializes in a different stage of the audit, passing context down the pipeline to produce a professional markdown audit report with confirmed findings, attack scenarios, and remediation recommendations.

---

✨ Key Features

• 🤖 6-Agent Pipeline: Contract Planner → Static Analysis → Vulnerability Hunter → Exploit Crafter → Verification → Report Writer
• ⚔️ Adversarial Analysis: AI agents reason about attacks from an adversary's perspective
• 🎯 No Manual Tool Dependencies: Doesn't require Slither, 4naly3er, or other CLI tools—AI simulates static analysis findings
• 🔨 Attack Scenario Modeling: Full proof-of-concept attack scenarios with transaction sequences
• ✅ Risk Verification Layer: Independent verification agent challenges findings before final report
• 📄 Markdown Reports: Publication-ready audit reports in markdown format
• 🎓 Educational & Production Ready: Built-in sample vulnerable contract for testing; supports custom audits
• 🔌 API-First Design: Built on CrewAI framework—easily extensible and embeddable

---

🚀 Quick Start

⚙️ Installation

Prerequisites:

• 🐍 Python 3.10 or higher
• 📦 pip or uv package manager

Clone & Install:

git clone https://github.com/baties/smartcontract_security_crewai.git
cd smartcontract_security_crewai-project/sc_security

# Using UV (recommended)
uv sync

# OR using pip
pip install -e ".[dev]"

🔑 Set API Keys:

Create a .env file in sc_security/ directory:

# Required: OpenAI API key for Claude/GPT models
OPENAI_API_KEY=sk-proj-YOUR-KEY-HERE

# Optional: Serper API key for web search (used by agents)
SERPER_API_KEY=your-serper-key-here

# Optional: LLM model selection (defaults to gpt-4o-mini)
MODEL=gpt-4o-mini

💻 Usage

Audit a Contract:

# Audit the built-in vulnerable sample contract
sc_security

# Audit your own contract
sc_security path/to/YourContract.sol

📋 Output:

• audit_report.md — completed audit report with all findings and recommendations

---

🏗️ Architecture

Agent Pipeline

The audit follows a sequential 6-stage pipeline:

┌─────────────────────────────────────────────────────────────────────┐
│ 1. CONTRACT PLANNER                                                 │
│    ↳ Read contract code                                             │
│    ↳ Produce comprehensive audit plan (functions, state, risks)     │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 2. STATIC ANALYSIS AGENT                                            │
│    ↳ Simulate Slither/4naly3er findings                             │
│    ↳ Classify: GENUINE | FALSE_POSITIVE | NEEDS_DEEPER              │
│    ↳ Identify gaps static tools cannot catch                        │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 3. VULNERABILITY HUNTER                                             │
│    ↳ Adversarial deep-dive on 6 attack categories                   │
│    ↳ Find exploitable issues (not false positives)                  │
│    ↳ Rank by severity (Critical → Low)                              │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 4. EXPLOIT CRAFTER                                                  │
│    ↳ Model complete attack scenarios for each finding               │
│    ↳ Transaction sequences, attacker profiles, PoC pseudocode       │
│    ↳ Financial impact estimates                                     │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 5. VERIFICATION AGENT                                               │
│    ↳ Challenge every finding with skeptical reasoning               │
│    ↳ Verify attack paths are actually exploitable                   │
│    ↳ Eliminate false positives, downgrade uncertain findings        │
└─────────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│ 6. REPORT WRITER                                                    │
│    ↳ Synthesize all findings into professional markdown report      │
│    ↳ Executive summary, risk tables, recommendations                │
│    ↳ Output: audit_report.md                                        │
└─────────────────────────────────────────────────────────────────────┘

Vulnerability Categories

The system analyzes contracts across 6 primary attack vectors:

1. 🔁 Reentrancy – External calls violating Checks-Effects-Interactions pattern
2. 🔓 Access Control – Missing or bypassable privilege checks
3. 🔢 Arithmetic – Overflow, underflow, division by zero
4. ⚡ Logic Errors – Incorrect state updates, broken invariants, edge cases
5. 💸 Economic/Incentive – Flash loan vectors, MEV, sandwich attacks, fund drainage
6. 🚫 Denial of Service – Permanent withdrawal blocking, gas griefing, unbounded loops

---

📖 Usage Examples

📝 Example 1: Audit Built-in Sample Contract

cd sc_security
sc_security

This runs the full audit on the VulnerableVault sample contract (intentionally vulnerable for demonstration). Output:

============================================================
  SolidityGuard AI — Smart Contract Security Audit
  6-Agent CrewAI Pipeline
============================================================

[Contract Planner] Analyzing contract structure...
[Static Analysis Agent] Simulating tool findings...
[Vulnerability Hunter] Searching for exploitable issues...
[Exploit Crafter] Modeling attack scenarios...
[Verification Agent] Challenging findings...
[Report Writer] Generating final report...

[SolidityGuard] Audit complete. Report saved to: audit_report.md

📂 Example 2: Audit Custom Contract

# Single contract
sc_security /path/to/MyToken.sol

# Result: audit_report.md with findings specific to MyToken

🐍 Example 3: Programmatic Usage

from sc_security.crew import ScSecurity

# Audit a contract programmatically
contract_code = open("MyContract.sol").read()
inputs = {"contract_code": contract_code}

crew = ScSecurity().crew()
result = crew.kickoff(inputs=inputs)

print(result)  # Full audit output

---

⚙️ Configuration

🔑 Environment Variables

Variable	Required	Default	Purpose
OPENAI_API_KEY	✅ Yes	—	OpenAI API key for LLM access
MODEL	❌ No	gpt-4o-mini	LLM model to use
SERPER_API_KEY	❌ No	—	Web search API (optional)

📋 Agent & Task Configuration

Agents and tasks are defined in YAML config files:

• src/sc_security/config/agents.yaml – Agent personalities, roles, goals
• src/sc_security/config/tasks.yaml – Task descriptions, expected outputs, context chains

Modify these files to customize agent behavior, prompts, or output expectations.

🐍 Python Configuration

Main entry point: src/sc_security/main.py

def run():
    """Run the audit crew."""
    contract_path = sys.argv[1] if len(sys.argv) > 1 else None
    contract_code = _load_contract(contract_path)

    inputs = {"contract_code": contract_code}
    ScSecurity().crew().kickoff(inputs=inputs)

---

📦 Project Structure

smartcontract_security_crewai-project/
├── README.md                           # This file
├── sc_security/                        # Main Python package
│   ├── pyproject.toml                  # Project metadata & dependencies
│   ├── uv.lock                         # UV lock file
│   ├── .env                            # API keys (git-ignored)
│   ├── src/sc_security/
│   │   ├── main.py                     # CLI entry point
│   │   ├── crew.py                     # CrewAI crew definition
│   │   ├── config/
│   │   │   ├── agents.yaml             # Agent configurations
│   │   │   └── tasks.yaml              # Task configurations
│   │   ├── tools/
│   │   │   ├── __init__.py
│   │   │   └── custom_tool.py          # Custom agent tools
│   │   └── knowledge/
│   │       └── user_preference.txt     # Domain knowledge (optional)
│   └── .venv/                          # Virtual environment
└── .gitignore                          # Git ignore configuration

---

🧠 How It Works

The VulnerableVault Example

The project includes a built-in demo contract with 3 intentional vulnerabilities:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract VulnerableVault {
    mapping(address => uint256) public balances;

    // VULN-001: Reentrancy
    function withdraw(uint256 amount) external {
        require(balances[msg.sender] >= amount);
        (bool success, ) = msg.sender.call{value: amount}("");
        require(success);
        balances[msg.sender] -= amount;  // State update AFTER call
    }

    // VULN-002: Missing access control
    function setPaused(bool _paused) external {
        paused = _paused;  // No msg.sender check!
    }

    // VULN-003: State inconsistency
    function emergencyWithdraw() external {
        payable(owner).transfer(address(this).balance);
        // Drains contract but leaves user balances untouched
    }
}

When audited, the system detects:

1. Reentrancy in withdraw() – external call before state update
2. Access control bypass in setPaused() – any address can pause
3. State mismatch in emergencyWithdraw() – contract drains but balances remain

---

🛠️ CLI Commands

Command	Purpose
sc_security	🎯 Audit the built-in sample contract
sc_security <path>	📁 Audit a custom contract file
run_crew	▶️ Alias for sc_security
train <n_iterations> <output_file>	🧠 Train the crew on sample contract
replay <task_id>	🔄 Replay a specific task from previous execution
test <n_iterations> <eval_llm>	✅ Test crew performance
run_with_trigger	⚡ Run with event triggering

---

🧪 Testing & Development

✅ Run Tests

cd sc_security
python -m pytest

🧠 Train the Crew (Optimize Prompts)

sc_security train 3 training_results.json

Trains the crew for 3 iterations and saves results for prompt optimization.

🔄 Replay Task Execution

sc_security replay <task_id>

Reruns a specific task from a previous execution using saved context.

---

📋 Report Output Format

Example: audit_report.md

---
# SMART CONTRACT SECURITY AUDIT REPORT
**Contract:** VulnerableVault
**Audit Date:** 2025-12-15
**Audited By:** SolidityGuard AI — Multi-Agent Audit Team

## EXECUTIVE SUMMARY
The VulnerableVault contract contains 3 confirmed critical vulnerabilities that allow fund theft via reentrancy, unauthorized pause, and state inconsistency attacks.

## RISK OVERVIEW
| Severity | Count |
|----------|-------|
| Critical | 3 |
| High     | 0 |
| Medium   | 0 |
| Low      | 0 |

## FINDINGS

### VULN-001: Reentrancy in withdraw()
**Severity:** Critical | **Category:** Reentrancy | **Affected Function:** `withdraw()`

#### Description
The withdraw() function performs an external call before updating the balance state, violating the Checks-Effects-Interactions pattern...

#### Impact
An attacker can drain the entire vault by recursively calling withdraw() through a malicious contract's receive() function.

#### Proof of Concept
1. Deploy AttackerContract with receive() that calls VulnerableVault.withdraw()
2. Call vault.deposit() with 1 ETH
3. Call vault.withdraw(1 ether)
4. receive() triggers instantly, calls withdraw() again
5. Repeat until vault empty

#### Recommendation
Move the balance update BEFORE the external call:
```solidity
function withdraw(uint256 amount) external {
    require(balances[msg.sender] >= amount);
    balances[msg.sender] -= amount;  // Update state FIRST
    (bool success, ) = msg.sender.call{value: amount}("");
    require(success);
}

...

---

## 🤝 Contributing

Contributions are welcome! Areas for enhancement:

- [ ] 🔹 Add support for Vyper contracts
- [ ] 🔌 Integrate real Slither/4naly3er tool calls
- [ ] ⛽ Add gas optimization analysis
- [ ] 📂 Support for multi-file audits
- [ ] 🎨 Web UI for report visualization
- [ ] 🎯 Custom agent templates for specific protocols (AMM, lending, etc.)

### 📋 Contribution Guidelines

1. **Fork the repository** 🍴
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`) 🌳
3. **Make your changes** with clear commit messages 📝
4. **Write tests** for new functionality 🧪
5. **Submit a pull request** with description of changes 🚀

---

## 📄 License

This project is licensed under the **MIT License** – see [LICENSE](LICENSE) file for details.

You are free to use, modify, and distribute this software, with appropriate attribution.

---

## ⚠️ Disclaimer & Limitations

### ❌ IMPORTANT: AI-Generated Reports Require Human Review

**SolidityGuard AI** is an experimental AI-powered analysis tool. **This is NOT a substitute for professional human audits.**

#### ⛔ Limitations:

- ❌ **No guarantee of finding all vulnerabilities** – AI agents may miss edge cases
- ❌ **False positives possible** – AI may flag non-issues as vulnerabilities
- ❌ **Cannot detect off-chain attacks** – Only analyzes code, not external dependencies
- ❌ **No formal verification** – Proofs generated are pseudocode, not mathematically formal
- ❌ **Depends on LLM quality** – Output quality varies with model and prompt engineering

#### 🚫 Unaudited Categories:

- ⚙️ Compiler-level vulnerabilities
- 📚 Third-party library exploits
- 💱 Economic attacks requiring cross-protocol interaction
- ⏰ Time-dependent race conditions
- 🔮 Oracle manipulation (without deep DeFi context)

#### ✅ Best Practices:

1. ✔️ **Use this as a first-pass filter** – catches obvious issues quickly
2. ✔️ **Always have a human auditor review findings** – especially Critical/High severity
3. ✔️ **Combine with static analysis tools** – Slither, 4naly3er, Certora run in parallel
4. ✔️ **Test with multiple models** – GPT-4, Claude, etc. for cross-validation
5. ✔️ **For production contracts** – hire professional audit firms (Trail of Bits, Consensys, etc.)

---

## 📚 Resources

- 🤖 **CrewAI Framework**: https://github.com/joaomdmoura/crewai
- 📖 **Solidity Security**: https://docs.soliditylang.org/en/latest/security-considerations.html
- 🔒 **OWASP Smart Contracts**: https://owasp.org/www-project-smart-contract-top-10/
- 🏆 **Trail of Bits Audits**: https://trailofbits.com/
- ✅ **Consensys Diligence**: https://consensys.net/diligence/

---

## 💡 Ideas & Feedback

Have ideas for improvements? Found a bug? Feel free to:

- 🐛 **Open an Issue**: https://github.com/baties/smartcontract_security_crewai/issues
- 💬 **Start a Discussion**: https://github.com/baties/smartcontract_security_crewai/discussions
- 🚀 **Submit a Pull Request**: https://github.com/baties/smartcontract_security_crewai/pulls

---

## 🙏 Acknowledgments

This project builds on the excellent work of:
- ⭐ **CrewAI**: Multi-agent AI orchestration framework
- 🧠 **Anthropic/OpenAI**: Large language models powering the agents
- 🔐 **Security Research Community**: OWASP, Trail of Bits, Consensys, Echidna teams

---

**Made with ❤️ for the Solidity & Web3 security community**

<div align="center">

  [![Twitter](https://img.shields.io/badge/Follow%20Us-Twitter-1DA1F2?style=flat&logo=twitter)](https://twitter.com/Batis13Ab)
  [![GitHub](https://img.shields.io/badge/GitHub-Repo-black?style=flat&logo=github)](https://github.com/baties/smartcontract_security_crewai)

  ⭐ **Star us on GitHub if you find this useful!** ⭐

</div>

*Last Updated: 2025-12-15*