Incalmo: An Autonomous LLM-assisted System for Red Teaming Multi-Host Networks

GitHub issues GitHub pull requests GitHub commit activity GitHub contributors GitHub stars GitHub forks

Incalmo is an autonomous AI-driven network penetration testing tool that automatically conducts intelligent red-teaming activities with the aim to enhance and assist operator abilities when performing complex network attack tasks.

Research Paper: On the Feasibility of Using LLMs to Execute Multistage Network Attacks

Website: Visit our website for more information!

</div>

Prerequisites
Installation
Usage
Tech Stack
Project Structure
Contributing
License
Acknowledgements
Support

Prerequisites

Docker Desktop - Required for containerized environment
Python 3.13+ - Required for local development
uv - Fast Python package installer (recommended) or pip
LLM API Keys - At least one of the following:
- OpenAI API Key - For GPT models
- Anthropic API Key - For Claude models
- Google API Key - For Gemini models
- DeepSeek API Key - For DeepSeek models
Node.js (Optional) - Only needed for UI Interface

Installation

1. Setup configuration

Create a configuration file by copying the example:

cp config/config_example.json config/config.json

Then edit config/config.json as needed.

2. Set API Keys

Create an environment file by copying the example:

cp .env.example .env

Then add LLM API keys to .env.

3. Start the Development Environment

Navigate to the docker directory and start the containers:

cd docker
docker compose up

MHBench Integration

Before starting the containers, set the MODE environment variable to "remote" in both docker/docker-compose.attacker.yml and docker/docker-compose.yml.

Before Step 4, compile and set up the MHBench environment for your experiment. Ensure config.json has the C2 server configured as:
"c2c_server": "http://localhost:8888"

4. Run Incalmo

In a new terminal window, attach to the running container and execute Incalmo:

cd docker
docker compose exec attacker /bin/bash
uv run main.py

UI Interface (optional)

If you want to use the web-based interface for Incalmo:

1. Start Backend

Follow Steps 1 through 3 in the Setup Instructions.

2. Install Node.js dependencies

Install Node dependencies:

cd incalmo/frontend/incalmo-ui
npm install

3. Start the React Server

Once dependencies are installed, run the react server:

npm start

This will lauch the frontend at http://localhost:3000

Usage

Note: A "strategy" is the logic behind an attack. See the strategies/ folder for examples of llm based attacks and state machine based attacks.

To use an your choice of an LLM-based attack:

Follow the setup and then:
Specify in config/config.json what LLMs to use (list is available in the registry). Use the config_example.json as a template
Run main.py as described in the setup
Observe the status of the attack through the logs in the output directory. Your attack will be timestamped and used to name the logs folder

This is the most stable way to test attack.

Incalmo also supports creating non-LLM state-machine strategies. To use a custom (non-LLM/manual) strategy for attacks:

Follow the setup and then:
Specify in config/config.json what manual strategy to use (list is available in strategies/state_machine). Use the config_example_state_machine.json as a template and fill in the strategy name as the class name.
Run main.py as described in the setup
Observe the status of the attack through the logs in the output directory. Your attack will be timestamped and used to name the logs folder
To create your own basic strategy, create a file in strategies/state_machine as follows:

class YourStrategyName(IncalmoStrategy):
    async def step(self) -> bool:
    # Your attack/strategy logic

It may be easier to look at examples of existing strategies to understand formatting and strategy abilities

To use the UI:

Instead of running main.py, launch the frontend and use the UI to start and stop attacks and observe logs. This is the cleanest/easiest way to observe the attacks in real time

Tech Stack

Backend: Python 3.13, Flask, Celery, SQLite
LLM Integration: LangChain, OpenAI, Anthropic, Google Gemini, DeepSeek
Frontend: React, TypeScript, Node.js
Containerization: Docker, Docker Compose
Package Management: uv

Project Structure

Incalmo/
├── .env.example               # Template for environment configuration
├── CITATION.cff               # Research paper citation metadata
├── LICENSE                    # MIT License
├── main.py                    # CLI entry point - runs Incalmo strategy
├── README.md                  # Project Guide
├── config/                    # Configuration management
├── docker/                    # Docker containerization
│   ├── attacker/              # Attacker container configuration
│   └── equifax/               # Target environment (Equifax breach simulation)
│       ├── database/          # Database server container
│       └── webserver/         # Web server container
├── incalmo/                   # Core application code
│   ├── incalmo_runner.py      # Main strategy execution runner
│   ├── server.py              # Flask server entry point
│   ├── api/                   # Client API for C2 server communication
│   ├── c2server/              # Command & Control server
│   │   ├── agents/            # Agent implementations
│   │   ├── celery/            # Async task queue
│   │   ├── payloads/          # Exploit and deployment payloads
│   │   └── routes/            # Flask blueprints for API endpoints
│   ├── core/                  # Core attack framework
│   │   ├── actions/           # Action classes 
│   │   │   ├── EmptyServiceActions/   # Placeholder actions
│   │   │   ├── HighLevel/         # High-level actions
│   │   │   │   └── llm_agents/        # LLM-agent action implementations
│   │   │   └── LowLevel/          # Low-level commands
│   │   │       └── privledge_escalation/      # Privilege escalation exploits
│   │   ├── models/            # Core domain models
│   │   │   ├── events/        # Event system for state updates
│   │   │   └── network/       # Network infrastructure models
│   │   ├── services/          # Core logic services
│   │   └── strategies/        # Attack strategies
│   │       ├── llm/               # LLM-based strategies
│   │       ├── state_machine/     # Rule-based strategies
│   │       ├── testers/           # Strategy testing utilities
│   │       └── util/              # Strategy utilities
│   ├── frontend/              # Web interface
│   │   └── incalmo-ui/        # React-based UI
│   └── models/                # Shared data models (Pydantic)
└── output/                    # Execution logs and results

Contributing

Contributions are always welcome! Please raise issues or make PR's if you have ideas on how to improve this project

License

This project is licensed under the MIT License

Acknowledgements

To cite this project or paper, check out the Citation specifications

Support

For support, email hello@incalmo.ai

Incalmo

Install / Use

README