EXODUS: Swarm Intelligence for Autonomous Cybersecurity

EXODUS is a lightweight, modular, open-source cybersecurity framework. Create and share your agents, add capabilities by creating plugins, and automate your agent teams for pentesting, reconnaissance, vulnerability discovery, and much more.

---

<div align="center"> <img src="docs/machine_resolution.gif" alt="EXODUS - Autonomous Hack The Box Machine Resolution" width="800"/> *Autonomous resolution of a Hack The Box machine using the Exodus framework (Video accelerated)* </div>

---

Key Features

• Use the model you want: support for DeepSeek, Ollama, Google, OpenAI, and more.
• Modular architecture: easily create or use plugins to add functionalities to your agents.
• Multi-agent swarm architecture: from individual agents to specialized teams with different patterns (central orchestrator, agent delegation, etc.)
• Lightweight implementation: avoids heavy agent libraries and uses only what is strictly necessary.

📋 Table of Contents

• Installation & Setup
• Quick Start
• Execution Modes (Engines)
• Creating Custom Plugins
• Creating Custom Agents
• Agent Handoffs
• Secure Execution Modes
• Technical Highlights
• Architecture

🚀 Installation & Setup

One-Line Installation (Recommended)

To install EXODUS on Linux or macOS, simply run the following command in your terminal:

bash <(curl -sSL https://raw.githubusercontent.com/exodialabsxyz/exodus/main/exodus/install/bootstrap.sh)

This script will automatically detect your OS, install dependencies, and set up everything for you.

Prerequisites

• Python 3.11 or higher
• Docker (optional, for isolated execution mode)
• An API key for your chosen LLM provider (Google Gemini, OpenAI, etc.)

Installation

# Clone the repository
git clone https://github.com/exodialabsxyz/exodus.git
cd exodus

# Install EXODUS
pip install -e .

Initial Configuration

1. Copy the example configuration:

   cp settings.toml.example settings.toml
   

2. Configure your LLM provider: Edit settings.toml and add your API key:

   [llm]
   default_model = "gemini/gemini-2.5-flash"
   default_provider = "litellm"
   default_max_context_tokens = 700000
   custom_api_base = ""  # Optional: for local models or custom endpoints
   
   [llm.default_provider_config]
   api_key = "your-api-key-here"
   

3. Configure execution mode:

   [agent]
   default_agent = "triage_agent"
   max_iterations = 100
   execution_mode = "local"  # or "docker"
   
   [agent.execution.docker]
   default_image = "parrotsec/security:7.0"
   default_image_name = "exodus_container"
   

4. Set logging level:

   [logging]
   level = "INFO"  # DEBUG, INFO, WARNING, ERROR
   format = "[exodus] %(asctime)s - %(name)s - %(levelname)s - %(message)s"
   

⚡ Quick Start

Start a Chat Session

# Start with default agent
exodus-cli chat

# Start with a specific agent
exodus-cli chat --agent triage_agent

# Use a different model
exodus-cli chat --model "gemini/gemini-2.5-pro"

# Adjust temperature
exodus-cli chat --temperature 0.7

Example Usage

# Start with the triage agent for automatic task routing
exodus-cli chat --agent triage_agent

> "Scan 192.168.1.1 for open ports and services"
# triage_agent will automatically transfer to recon_agent
# recon_agent will execute the scan and provide results

Using Ollama (Local Models)

[llm]
default_model = "ollama/granite4:latest"
custom_api_base = "http://localhost:11434"

[llm.default_provider_config]
api_key = "ollama_apikey"

⚙️ Execution Modes (Engines)

EXODUS provides two distinct execution engines designed for different operational scenarios:

Interactive Mode (Human-in-the-Loop)

The default engine for manual operation where a human operator (pentester, security analyst) maintains control and directs agent actions in real-time.

# Start interactive chat session
exodus-cli chat --agent triage_agent

Use Cases:

• Manual pentesting: Operator analyzes results and decides next steps
• Exploratory reconnaissance: Human expertise guides the investigation
• Training and learning: Understand how agents work step-by-step
• Compliance requirements: Maintain human oversight for sensitive operations

Characteristics:

• Human operator controls the flow
• Agent responds to each user message
• Full visibility into agent reasoning
• Manual approval before critical actions
• Interactive feedback and course correction

Example workflow:

You: "Scan this target for open ports"
Agent: [Executes nmap scan, shows results]
You: "Now enumerate the HTTP service on port 80"
Agent: [Performs HTTP enumeration]
You: "Looks vulnerable, try directory bruteforce"
Agent: [Executes gobuster]

---

Automated Mode (Autonomous Execution)

The automated engine (exodus-cli auto) enables fully autonomous operation with advanced planning, reflection, and self-correction capabilities. Designed for tasks that require minimal human intervention.

# Execute autonomous mission
exodus-cli auto "Perform complete reconnaissance on exodialabs.xyz" \
  --agent recon_agent \
  --session scan_20250107 \
  --verbose

Use Cases:

• Automated scanning: Schedule unattended reconnaissance of infrastructure
• CI/CD security testing: Integrate into pipelines for continuous assessment
• Bug bounty automation: Autonomous discovery of vulnerabilities
• Large-scale operations: Deploy agent swarms for distributed tasks
• Repetitive workflows: Automate routine security assessments

Advanced Features:

1. Dynamic Planning

The agent generates a structured task plan based on the objective:

Objective: "Scan target and find vulnerabilities"
Plan:
  ├─ task_1: Port scan and service discovery
  ├─ task_2: HTTP/SMB enumeration (depends on task_1)
  ├─ task_3: Vulnerability identification
  ├─ task_4: Exploit validation
  └─ task_5: Report generation

2. Strategic Reflection

Periodic self-evaluation to ensure progress:

• Iteration-based: Reviews progress every N steps (default: 25)
• Task-based: Evaluates after N completed tasks (default: 3)
• Actions: CONTINUE, REPLAN, ESCALATE, or COMPLETE

Reflection Checkpoint:
  Progress: 3/6 tasks (50%)
  Avg Score: 8.5/10
  Action: CONTINUE
  Reasoning: "Making good progress, no blockers detected"

3. Dynamic Replanning

Agent can regenerate the plan mid-execution if:

• Strategy isn't working (repeated failures)
• Environment changed (new services discovered)
• Task becomes irrelevant (objective already achieved)

Reflection: REPLAN (confidence: 9.0)
  Reasoning: "Initial plan assumed SSH access, but only HTTP is available.
             Pivoting to web-based exploitation strategy."

Plan Updated:
  ├─ task_1: ✓ Port scan completed
  ├─ task_2: ✓ Service enumeration
  ├─ task_3_new: Web vulnerability scan (modified)
  └─ task_4_new: SQL injection testing (new approach)

4. Checkpoint & Resume

Execution state is automatically saved:

# Start mission
exodus-cli auto "Long-running task" --session my_mission

# Interrupt with Ctrl+C or timeout
^C Interrupted by user

# Resume from checkpoint
exodus-cli auto --resume --session my_mission

5. Escalation to Human

Agent can request assistance when stuck:

Reflection: ESCALATE
  Reasoning: "Credentials required to proceed. Manual intervention needed."

Agent requests human assistance

Configuration Options:

[agent.automated]
reflection_iteration_interval = 25  # Reflect every N steps
reflection_task_interval = 3        # Reflect every N completed tasks
allow_replanning = true             # Enable dynamic replanning
min_task_score = 0.3                # Minimum acceptable task quality

---

Choosing the Right Mode

| Aspect | Interactive Mode | Automated Mode | |--------|------------------|----------------| | Control | Human operator | Autonomous agent | | Planning | Manual | Dynamic (LLM-generated) | | Reflection | N/A | Every N tasks/iterations | | Replanning | N/A | Automatic when needed | | Best For | Exploratory work, HITL | Repetitive tasks, CI/CD | | Overhead | Requires constant attention | Set and forget | | Use Case | Pentesting engagement | Automated security scanning |

---

🔧 Creating Custom Plugins

Create powerful tools for your agents with just a simple decorator. EXODUS automatically generates the OpenAI-compatible schema:

from exodus.core.decorators import tool

@tool(
    name="port_scanner",
    type="cli",
    description="Scans ports on a target host using nmap"
)
def port_scanner(target: str, ports: str = "1-1000") -> str:
    """Scans the specified ports on the target."""
    return f"nmap -p {ports} {target}"

# Register your plugin class
class SecurityPlugin:
    @staticmethod
    def get_tools():
        return {
            port_scanner.tool_name: port_scanner,
        }

To make your plugin discoverable, register it in your pyproject.toml:

[project.entry-points."exodus.plugins.tools"]
security = "your_package.plugins:SecurityPlugin"

EXODUS will automatically discover and load all plugins from the exodus.plugins.tools entry point group at startup.

Plugin System:

• Python tools: Execute code directly in your environment
• CLI tools: Return shell commands executed in isolated containers
• Auto-validation: Pydantic models generated automatically from type hints
• Auto-discovery: Plugins loaded via Python entry points (exodus.plugins.tools)
• Distributable: Share your plugins as PyP