IVExES is an advanced Python framework for cybersecurity vulnerability analysis and exploitation using multi-agent AI systems. It combines knowledge bases (CWE, CAPEC, MITRE ATT&CK) with dynamic analysis capabilities for automated security assessment. You can find an auto generated documentation under IVExES
- Python 3.12+
- Docker and Docker Compose
- uv package manager (recommended)
-
Clone the repository:
git clone https://github.com/LetsDrinkSomeTea/ivexes.git cd ivexes -
Full setup (recommended):
make setup
This will build Docker images, sync dependencies, and start the LiteLLM proxy.
-
Configure environment variables: Create a
.envfile with your API keys:LLM_API_KEY=your_openai_api_key_here # or OPENAI_API_KEY=your_openai_api_key_here
from ivexes.agents import SingleAgent
from ivexes.config import PartialSettings
settings = PartialSettings(
model='openai/gpt-4o-mini',
codebase_path='/path/to/vulnerable/code',
vulnerable_folder='vulnerable-version',
patched_folder='patched-version'
)
agent = SingleAgent(settings=settings)
await agent.run_interactive()IVExES provides a comprehensive framework for automated vulnerability analysis through:
- Multi-Agent Architecture: Specialized AI agents for different aspects of security analysis
- Knowledge Base Integration: MITRE ATT&CK, CWE, CAPEC, and CVE databases
- Dynamic Code Analysis: Container-based sandbox environment with Neovim LSP integration
- Automated Reporting: Structured vulnerability reports with exploitation details
- Extensible Design: Modular architecture supporting custom agents and tools
- BaseAgent: Abstract foundation with settings management and execution modes
- SingleAgent: Individual agent for focused vulnerability assessment
- MultiAgent: Orchestrates multiple specialized agents for complex analysis
- MVPAgent: Minimal viable product implementation for quick analysis
- HTBChallengeAgent: Specialized for Hack The Box challenge analysis
- Neovim LSP integration for intelligent code analysis
- Tree-sitter parsing for code structure understanding
- Container-based isolation for safe code examination
- Docker-based execution environments
- Kali Linux container for security testing
- Automatic setup from archives with secure isolation
- ChromaDB for knowledge storage and retrieval
- MITRE ATT&CK framework integration
- CVE and vulnerability pattern matching
- Embedding-based similarity search
# Setup and dependency management
make setup # Complete setup (images, deps, services)
make sync # Install/update dependencies
make build-images # Build Docker images
make run-litellm # Start LiteLLM proxy
# Code quality
make format # Format and fix code
make format-check # Check formatting
make lint # Run linter
make check # Run all quality checks
# Testing
make tests # Run test suite
# Documentation
make build-docs # Build documentation
make serve-docs # Serve docs locally
make deploy-docs # Deploy to GitHub Pagesivexes/
├── src/ivexes/ # Main package source
│ ├── agents/ # AI agent implementations
│ ├── code_browser/ # Code analysis tools
│ ├── config/ # Configuration management
│ ├── sandbox/ # Execution environments
│ ├── vector_db/ # Knowledge base integration
│ └── tools.py # Shared utilities
├── container/ # Docker configurations
│ ├── kali_sandbox/ # Security testing environment
│ ├── nvim_lsp/ # Code analysis container
│ └── litellm/ # LLM proxy service
├── examples/ # Usage examples
├── tests/ # Test suite
└── docs/ # Documentation
IVExES uses environment variables for configuration with sensible defaults.
Create .env and .secrets.env files as needed:
# API Configuration
LLM_API_KEY=your_api_key # Required: LLM provider API key
LLM_BASE_URL=https://api.openai.com/v1 # LLM endpoint
# Model Configuration
MODEL=openai/gpt-4o-mini # Primary model
REASONING_MODEL=openai/o4-mini # Reasoning model
TEMPERATURE=0.3 # Model temperature (0.0-2.0)
# Analysis Configuration
CODEBASE_PATH=/path/to/code # Analysis target
VULNERABLE_CODEBASE_FOLDER=vulnerable # Vulnerable version folder
PATCHED_CODEBASE_FOLDER=patched # Patched version folder
# System Configuration
LOG_LEVEL=INFO # Logging level
MAX_TURNS=10 # Agent conversation limit# Embedding Configuration
EMBEDDING_PROVIDER=builtin # builtin, local, or openai
EMBEDDING_MODEL=builtin # Embedding model
CHROMA_PATH=/tmp/ivexes/chromadb # Vector database path
# Sandbox Configuration
SANDBOX_IMAGE=kali-ssh:latest # Container image
SETUP_ARCHIVE=/path/to/setup.tgz # Analysis setup archiveimport asyncio
from ivexes.agents import SingleAgent
from ivexes.config import PartialSettings
settings = PartialSettings(
model='openai/gpt-4o-mini',
codebase_path='/path/to/vulnerable/code',
vulnerable_folder='vulnerable-v1.0',
patched_folder='patched-v1.1'
)
agent = SingleAgent(settings=settings)
# Interactive mode
await agent.run_interactive()
# Streaming mode
async for chunk in agent.run_streamed():
print(chunk, end='')
# Synchronous mode
result = agent.run()
print(result)from ivexes.agents import MultiAgent
agent = MultiAgent(settings=settings)
await agent.run_interactive()from ivexes.agents import HTBChallengeAgent
agent = HTBChallengeAgent(
challenge_name="buffer_overflow_example",
settings=settings
)
await agent.run_interactive()IVExES uses Docker containers for isolation and specialized environments:
- Unified API for multiple LLM providers
- Request routing and load balancing
- Usage tracking and rate limiting
- Security testing environment
- Pre-installed penetration testing tools
- Isolated execution for exploit development
- Intelligent code analysis
- Language server protocol integration
- Syntax highlighting and error detection
- Static Analysis: Code structure and pattern recognition
- Dynamic Analysis: Runtime behavior in controlled environments
- Differential Analysis: Comparison between vulnerable and patched versions
- Knowledge Integration: CVE, CWE, CAPEC, and MITRE ATT&CK correlation
- Specialized Roles: Different agents for reconnaissance, analysis, and exploitation
- Collaborative Analysis: Multi-agent coordination for complex vulnerabilities
- Adaptive Learning: Continuous improvement through feedback loops
- Context Awareness: Maintains conversation history and analysis state
- Structured Reports: Markdown-formatted vulnerability assessments
- Exploitation Details: Step-by-step exploitation procedures
- Risk Assessment: CVSS scoring and impact analysis
- Remediation Guidance: Specific mitigation recommendations
Dependencies not installing:
# Use UV for dependency management
uv sync --all-extras --all-packages --group dev
# Or fallback to pip
pip install -e ".[dev]"Docker issues:
# Rebuild images
make build-images
# Check service status
docker compose ps
# View logs
docker compose logsLiteLLM proxy not starting:
# Check configuration
cat container/litellm/config/config.yaml
# Restart service
docker compose restart- Check the documentation
- Review example scripts
- Open an issue on GitHub for bugs or feature requests
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Contributions are welcome! Please read the contributing guidelines and submit pull requests to the main repository.
If you use IVExES in your research, please cite:
@software{ivexes2024,
title={IVExES: Intelligent Vulnerability Extraction \& Exploit Synthesis},
author={Julian Faigle},
year={2025},
url={https://github.com/LetsDrinkSomeTea/ivexes}
}Note: IVExES is designed for educational and authorized security testing purposes only. Users are responsible for ensuring compliance with applicable laws and regulations.