Hexor

AI Agents for Smart Contract Security

Tip

New! Hexor agents now feature RAG-powered intelligence with 300+ real-world exploit examples and comprehensive tool usage guides. Agents automatically query the knowledge base for vulnerability patterns, exploit techniques, and CLI best practices during analysis.

---

🦉 Hexor Overview

Hexor are autonomous AI agents specialized in smart contract security - they analyze Solidity code, deploy contracts to test environments, find vulnerabilities, and validate them through actual proof-of-concepts. Built for blockchain developers and security researchers who need fast, accurate smart contract auditing without the overhead of manual reviews or the false positives of static analysis alone.

Key Capabilities:

• 🔧 Complete smart contract testing toolkit - Foundry, Slither, Mythril, Echidna
• 🔗 Multi-chain support - Test on Ethereum, BSC, Polygon, Arbitrum, and more
• 🤝 Teams of agents that collaborate and specialize by vulnerability type
• ✅ Real validation with exploits and PoCs, not just warnings
• 💻 Developer-first CLI with actionable audit reports

🎯 Use Cases

• Smart Contract Auditing - Automated security analysis of Solidity contracts and DeFi protocols
• Pre-deployment Security - Catch critical vulnerabilities before mainnet launch
• Rapid Security Research - Test contracts on mainnet forks with real state
• CI/CD Integration - Block vulnerable contracts in your deployment pipeline

---

🚀 Quick Start

Prerequisites:

• Docker (running)
• Python 3.12+
• An LLM provider key (e.g. get OpenAI API key or use a local LLM)

Installation & First Audit

# Install Hexor
pipx install hexor-agent

# Configure your AI provider
export HEXOR_LLM="openai/gpt-5"
export LLM_API_KEY="your-api-key"

# Audit a smart contract project
hexor --target ./your-defi-protocol

Note

First run automatically pulls the sandbox Docker image with Foundry and security tools. Results are saved to hexor_runs/<run-name>

☁️ Run Hexor in Cloud

Want to skip the local setup, API keys, and unpredictable LLM costs? Run the hosted cloud version of Hexor at app.usehexor.com.

Launch a smart contract audit in just a few minutes—no setup or configuration required—and you'll get:

• A full audit report with validated findings and remediation steps
• Shareable dashboards your team can use to track fixes over time
• CI/CD and GitHub integrations to block risky changes before deployment
• Continuous monitoring so new vulnerabilities are caught quickly

Run your first audit now →

---

✨ Features

🛠️ Smart Contract Security Toolkit

Hexor agents come equipped with comprehensive blockchain security tools:

• Foundry Integration - Deploy, test, and interact with contracts using anvil, forge, and cast
• Static Analysis - Slither for automated vulnerability detection
• Symbolic Execution - Mythril for deep path exploration and edge case discovery
• Property Fuzzing - Echidna for invariant testing and property validation
• Multi-chain Forking - Test on Ethereum, BSC, Polygon, Arbitrum, Optimism, Avalanche, and more
• Terminal & Python - Custom exploit development and validation scripts
• RAG Knowledge Base - 300+ real-world exploit examples, audit reports, and tool usage guides
• Knowledge Management - Structured findings and vulnerability documentation

🧠 RAG-Powered Intelligence

Hexor agents leverage a comprehensive knowledge base with Retrieval-Augmented Generation (RAG):

• 300+ Real-World Exploits - PoC code from actual DeFi hacks and vulnerabilities
• Audit Report Database - Validated findings from professional security audits
• Tool Usage Guides - CLI examples and configuration for Slither, Echidna, Medusa, Mythril, Foundry
• Vulnerability Patterns - Attack vectors, exploitation techniques, and remediation strategies
• Smart Indexing - Automatic metadata extraction (vulnerability type, severity, protocol)
• Semantic Search - Find relevant exploits, reports, and guides using natural language queries

Agent RAG Integration:

Agents automatically query the knowledge base during analysis:

• Code review agents search for similar vulnerability patterns
• Tool agents retrieve configuration examples and usage guides
• Validation agents find exploit templates for PoC development
• All agents assess severity by referencing real audit findings

Managing the Knowledge Base:

# View knowledge base statistics
hexor-knowledge info

# Index new documents (exploits, reports, tool guides)
hexor-knowledge index ./path/to/documents

# Index specific file
hexor-knowledge index ./exploit_example.md

# Search the knowledge base
hexor-knowledge search "reentrancy attack DEX"

# Reset to default sample documents
hexor-knowledge reset

# Clear all indexed documents
hexor-knowledge clear --force

Custom Knowledge Base:

Add your own exploit examples, audit reports, or tool guides:

# Add custom documents
mkdir -p ~/.hexor/data/documents/custom
cp your_exploits/*.md ~/.hexor/data/documents/custom/

# Index them
hexor-knowledge index ~/.hexor/data/documents/custom

Hexor automatically extracts metadata (vulnerability types, severity, protocol) from your documents for better search relevance.

🔧 Terminal-First Architecture

Hexor agents use a terminal-first approach for all security tooling, giving them maximum flexibility and access to the latest tool features:

• Direct CLI Execution - Agents execute tools via terminal command with full CLI access
• No Abstraction Overhead - Direct access to all flags, options, and configurations
• Always Up-to-Date - Automatically supports new tool features without code changes
• Tool Agnostic - Works with Slither, Echidna, Medusa, Mythril, Foundry, and custom scripts
• RAG-Guided Usage - Agents query the knowledge base for CLI examples and best practices

Example Agent Workflow:

# Slither static analysis
terminal: slither /workspace --detect reentrancy-eth,access-control --json output.json

# Echidna fuzzing with config
terminal: echidna /workspace/contracts/Vault.sol --contract VaultInvariants --config echidna.yaml

# Medusa multi-worker fuzzing
terminal: medusa fuzz --target /workspace --workers 4 --deployment-order Vault,Strategy

# Mythril symbolic execution
terminal: myth analyze /workspace/contracts/Math.sol --solv 0.8.20 --max-depth 128

# Foundry PoC validation
terminal: forge test --match-test testReentrancyExploit -vvv

Specialized agents (SlitherAgent, EchidnaAgent, MedusaAgent, MythrilAgent) come pre-configured with tool expertise and automatically retrieve usage guides from the RAG knowledge base.

🎯 Comprehensive Vulnerability Detection

Hexor can identify and validate smart contract vulnerabilities including:

• Reentrancy - Single-function, cross-function, and read-only reentrancy
• Access Control - Ownership issues, missing modifiers, privilege escalation
• Integer Issues - Overflow, underflow, precision loss, rounding errors
• DeFi-Specific - Flash loan attacks, oracle manipulation, MEV vulnerabilities
• Logic Flaws - Business logic errors, state management issues, unexpected behaviors
• Gas & DoS - Unbounded loops, gas griefing, denial of service attacks
• External Calls - Unchecked returns, delegatecall vulnerabilities, low-level call issues

🕸️ Graph of Agents

Advanced multi-agent orchestration for comprehensive smart contract auditing:

• Specialized Agents - Dedicated agents for reentrancy, access control, DeFi attacks, etc.
• Parallel Testing - Multiple agents work simultaneously for fast coverage
• Collaborative Validation - Agents share discoveries and validate each other's findings

⚡ Performance Optimization

Hexor includes intelligent caching and streaming to maximize efficiency during security audits:

Smart Tool Result Caching

Automatic Result Caching - Expensive operations (Slither, Echidna, Medusa) are cached to avoid redundant execution:

• Hash-based cache keys - Generated from tool name + arguments + file dependencies
• File dependency tracking - Automatic cache invalidation when source files change
• Configurable TTL - Per-tool time-to-live settings (default: 5 minutes)
• 50-90% faster re-analysis - When code hasn't changed, results are instant

Configuration:

# Enable/disable caching
export HEXOR_CACHE_ENABLED=1  # Default: enabled

# Custom cache directory
export HEXOR_CACHE_DIR=.hexor_cache

# Custom TTL (seconds)
export HEXOR_CACHE_TTL=300  # Default: 5 minutes

# Maximum cache size
export HEXOR_CACHE_MAX_SIZE_MB=1024  # Default: 1GB

Cached Tools:

• slither_run - 10 minute TTL (expensive static analysis)
• echidna_run - 5 minute TTL (fuzzing campaigns)
• medusa_fuzz - 5 minute TTL (parallel fuzzing)
• forge_build - 3 minute TTL (compilation)
• forge_test - 3 minute TTL (test execution)

Streaming Output Support

Real-time Progress Monitoring - Long-running fuzzing tools provide live progress updates:

• Incremental output streaming - See test progress without waiting for completion
• Progress parsing - Extract test counts, coverage metrics, and findings in real-time
• Early termination - React to critical findings immediately
• Better UX - No more staring at a blank screen during 15-minute fuzzing campaigns

Example Progress Output:

Echidna Fuzzing Progress:
├─ Tests: 1000/5000 (20%)
├─ Coverage: 75.5%
├─ Counterexamples: 0
└─ Runtime: 3m 45s

Streaming Architecture:

• Built on subprocess.Popen for line-by-line output
• Progress callbacks for Echidna and Medusa parsers
• Extensible parser system for custom tools

---

💻 Usage Examples

Basic Usage

# Audit a local smart contract project
hexor --target ./defi-protocol

# Audit contracts from GitHub
hexor --target https://github.com/org/defi-contracts

# Test a deployed contract on mainnet fork
hexor --target 0x1234567890123456789012345678901234567890 --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

Advanced Testing Scenarios

# Multi-target: source code + deployed contract
hexor -t ./contracts -t 0x1234567890123456789012345678901234567890 --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY

# Focused vulnerability testing
hexor --target ./contracts --instruction "Focus on reentrancy and flash loan attack vectors"

# Test specific contract file
hexor --target ./contracts/VulnerableBank.sol --instruction "Test for access control and reentrancy issues"

🤖 Headless Mode

Run Hexor programmatically without interactive UI using the -n/--non-interactive flag—perfect for CI/CD and automated security checks. The CLI prints real-time vulnerability findings and the final audit report before exiting. Exits with non-zero code when vulnerabilities are found.

hexor -n --target ./contracts

🔄 CI/CD (GitHub Actions)

Hexor can be added to your pipeline to run security audits on pull requests with a lightweight GitHub Actions workflow:

name: hexor-security-audit

on:
  pull_request:

jobs:
  contract-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Hexor
        run: pipx install hexor-agent

      - name: Run Smart Contract Audit
        env:
          HEXOR_LLM: ${{ secrets.HEXOR_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}

        run: hexor -n -t ./contracts

⚙️ Configuration

export HEXOR_LLM="openai/gpt-5"
export LLM_API_KEY="your-api-key"

# Optional
export LLM_API_BASE="your-api-base-url"  # if using a local model, e.g. Ollama, LMStudio
export PERPLEXITY_API_KEY="your-api-key"  # for enhanced search capabilities

OpenAI's GPT-5 (openai/gpt-5) and Anthropic's Claude Sonnet 4.5 (anthropic/claude-sonnet-4-5) are the recommended models for best results with Hexor. We also support many other options, including cloud and local models, though their performance and reliability may vary.

🤝 Contributing

We welcome contributions from the community! There are several ways to contribute:

Code Contributions

See our Contributing Guide for details on:

• Setting up your development environment
• Running tests and quality checks
• Submitting pull requests
• Code style guidelines

Prompt Modules Collection

Help expand our collection of specialized prompt modules for smart contract security:

• Advanced testing techniques for specific vulnerabilities, DeFi protocols, and blockchain patterns
• See Prompt Modules Documentation for guidelines
• Submit via pull requests or issues

👥 Join Our Community

Have questions? Found a bug? Want to contribute? Join our Discord!

🌟 Support the Project

Love Hexor? Give us a ⭐ on GitHub!

🙏 Acknowledgements

Hexor builds on the incredible work of open-source projects like Strix, Foundry, Slither, Mythril, Echidna, LiteLLM, and Textual. Huge thanks to their maintainers!

Warning

Only test contracts you own or have permission to audit. You are responsible for using Hexor ethically and legally.