## π― Milestones
[-red.svg)](https://app.hackthebox.com/users/2268644)
[-red.svg)](https://app.hackthebox.com/users/2268644)
[-red.svg)](https://app.hackthebox.com/users/2268644)
[-red.svg)](https://app.hackthebox.com/users/2268644)
[![](https://img.shields.io/badge/HTB_"Human_vs_AI"_CTF-top_1_(AIs)_world-red.svg)](https://ctf.hackthebox.com/event/2000/scoreboard)
[![](https://img.shields.io/badge/HTB_"Human_vs_AI"_CTF-top_1_Spain-red.svg)](https://ctf.hackthebox.com/event/2000/scoreboard)
[![](https://img.shields.io/badge/HTB_"Human_vs_AI"_CTF-top_20_World-red.svg)](https://ctf.hackthebox.com/event/2000/scoreboard)
[![](https://img.shields.io/badge/HTB_"Human_vs_AI"_CTF-750_$-yellow.svg)](https://ctf.hackthebox.com/event/2000/scoreboard)
[](https://lu.ma/roboticshack?tk=RuryKF)
[](https://github.com/aliasrobotics/cai)
## π¦ Package Attributes
[](https://badge.fury.io/py/cai-framework)
[](https://pypistats.org/packages/cai-framework)
[](https://github.com/aliasrobotics/cai)
[](https://github.com/aliasrobotics/cai)
[](https://github.com/aliasrobotics/cai)
[](https://github.com/aliasrobotics/cai)
[](https://discord.gg/fnUFcTaQAC)
[](https://arxiv.org/pdf/2504.06017)
[](https://arxiv.org/abs/2506.23592)
A lightweight, ergonomic framework for building bug bounty-ready Cybersecurity AIs (CAIs).
| CAI with `alias0` on ROS message injection attacks in MiR-100 robot | CAI with `alias0` on API vulnerability discovery at Mercado Libre |
|-----------------------------------------------|---------------------------------|
| [](https://asciinema.org/a/dNv705hZel2Rzrw0cju9HBGPh) | [](https://asciinema.org/a/9Hc9z1uFcdNjqP3bY5y7wO1Ww) |
| CAI on JWT@PortSwigger CTF β Cybersecurity AI | CAI on HackableII Boot2Root CTF β Cybersecurity AI |
|-----------------------------------------------|---------------------------------|
| [](https://asciinema.org/a/713487) | [](https://asciinema.org/a/713485) |
> [!NOTE]
> We encourage you to read CAI's the technical report at https://arxiv.org/pdf/2504.06017.
> [!WARNING]
> :warning: CAI is in active development, so don't expect it to work flawlessly. Instead, contribute by raising an issue or [sending a PR](https://github.com/aliasrobotics/cai/pulls).
>
> Access to this library and the use of information, materials (or portions thereof), is **
| | Description | English | Spanish |
|-------|----------------|---------|---------|
| **Episode 0**: What is CAI? | Cybersecurity AI (`CAI`) explained | [](https://www.youtube.com/watch?v=nBdTxbKM4oo) | [](https://www.youtube.com/watch?v=FaUL9HXrQ5k) |
| **Episode 1**: The `CAI` Framework | Vision & Ethics - Explore the core motivation behind CAI and delve into the crucial ethical principles guiding its development. Understand the motivation behind CAI and how you can actively contribute to the future of cybersecurity and the CAI framework. | [](https://www.youtube.com/watch?v=QEiGdsMf29M&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=3) | |
| **Episode 2**: From Zero to Cyber Hero | Breaking into Cybersecurity with AI - A comprehensive guide for complete beginners to become cybersecurity practitioners using CAI and AI tools. Learn how to leverage artificial intelligence to accelerate your cybersecurity learning journey, from understanding basic security concepts to performing real-world security assessments, all without requiring prior cybersecurity experience. | [](https://www.youtube.com/watch?v=hSTLHOOcQoY&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=14) | |
| **Episode 3**: Vibe-Hacking Tutorial | "My first Hack" - A Vibe-Hacking guide for newbies. We demonstrate a simple web security hack using a default agent and show how to leverage tools and interpret CIA output with the help of the CAI Python API. You'll also learn to compare different LLM models to find the best fit for your hacking endeavors. | [](https://www.youtube.com/watch?v=9vZ_Iyex7uI&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=1) | [](https://www.youtube.com/watch?v=iAOMaI1ftiA&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=2) |
| **Episode 4**: Intro ReAct | The Evolution of LLMs - Learn how LLMs evolved from basic language models to advanced multiagency AI systems. From basic LLMs to Chain-of-Thought and Reasoning LLMs towards ReAct and Multi-Agent Architectures. Get to know the basic terms | [](https://www.youtube.com/watch?v=tLdFO1flj_o&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=13) | |
| **Episode 5**: CAI on CTF challenges | Dive into Capture The Flag (CTF) competitions using CAI. Learn how to leverage AI agents to solve various cybersecurity challenges including web exploitation, cryptography, reverse engineering, and forensics. Discover how to configure CAI for competitive hacking scenarios and maximize your CTF performance with intelligent automation. | [](https://www.youtube.com/watch?v=MrXTQ0e2to4&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=13) | [](https://www.youtube.com/watch?v=r9US_JZa9_c&list=PLLc16OUiZWd4RuFdN5_Wx9xwjCVVbopzr&index=12) |
| **Episode 6**: CAI Fluency Framework | Introducing CAI Fluency: An Educational Framework for Cybersecurity AI - Learn about the comprehensive educational platform designed to democratize cybersecurity AI knowledge. Explore the theoretical foundations, the 4 C's competencies (Command, Communication, Critique, Custody), and the three modalities of Human-AI interaction in security contexts. | *Coming soon* | *Coming soon* |
| | | | |
| **Annex 1**: `CAI` 0.5.x release | Introduce version 0.5 of `CAI` including new multi-agent functionality, new commands such as `/history`, `/compact`, `/graph` or `/memory` and a case study showing how `CAI` found a critical security flaw in OT heap pumps spread around the world. | [](https://www.youtube.com/watch?v=OPFH0ANUMMw) | [](https://www.youtube.com/watch?v=Q8AI4E4gH8k) |
| **Annex 2**: `CAI` 0.4.x release and `alias0` | Introducing version 0.4 of `CAI` with *streaming* and improved MCP support. We also introduce `alias0`, the Privacy-First Cybersecurity AI, a Model-of-Models Intelligence that implements a Privacy-by-Design architecture and obtains state-of-the-art results in cybersecurity benchmarks. | [](https://www.youtube.com/watch?v=NZjzfnvAZcc) | |
| **Annex 3**: Cybersecurity AI Community Meeting #1 | First Cybersecurity AI (`CAI`) community meeting, over 40 participants from academia, industry, and defense gathered to discuss the open-source scaffolding behind CAI β a project designed to build agentic AI systems for cybersecurity that are open, modular, and Bug Bounty-ready. | [](https://www.youtube.com/watch?v=4JqaTiVlgsw) | |
## :nut_and_bolt: Install
```bash
pip install cai-framework
```
Always create a new virtual environment to ensure proper dependency installation when updating CAI.
The following subsections provide a more detailed walkthrough on selected popular Operating Systems. Refer to the [Development](#development) section for developer-related install instructions.
### OS X
```bash
brew update && \
brew install git python@3.12
# Create virtual environment
python3.12 -m venv cai_env
# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework
# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env
# Launch CAI
cai # first launch it can take up to 30 seconds
```
### Ubuntu 24.04
```bash
sudo apt-get update && \
sudo apt-get install -y git python3-pip python3.12-venv
# Create the virtual environment
python3.12 -m venv cai_env
# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework
# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env
# Launch CAI
cai # first launch it can take up to 30 seconds
```
### Ubuntu 20.04
```bash
sudo apt-get update && \
sudo apt-get install -y software-properties-common
# Fetch Python 3.12
sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev -y
# Create the virtual environment
python3.12 -m venv cai_env
# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework
# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env
# Launch CAI
cai # first launch it can take up to 30 seconds
```
### Windows WSL
Go to the Microsoft page: https://learn.microsoft.com/en-us/windows/wsl/install. Here you will find all the instructions to install WSL
From Powershell write: wsl --install
```bash
sudo apt-get update && \
sudo apt-get install -y git python3-pip python3-venv
# Create the virtual environment
python3 -m venv cai_env
# Install the package from the local directory
source cai_env/bin/activate && pip install cai-framework
# Generate a .env file and set up with defaults
echo -e 'OPENAI_API_KEY="sk-1234"\nANTHROPIC_API_KEY=""\nOLLAMA=""\nPROMPT_TOOLKIT_NO_CPR=1\nCAI_STREAM=false' > .env
# Launch CAI
cai # first launch it can take up to 30 seconds
```
### Android
We recommend having at least 8 GB of RAM:
1. First of all, install userland https://play.google.com/store/apps/details?id=tech.ula&hl=es
2. Install Kali minimal in basic options (for free). [Or any other kali option if preferred]
3. Update apt keys like in this example: https://superuser.com/questions/1644520/apt-get-update-issue-in-kali, inside UserLand's Kali terminal execute
```bash
# Get new apt keys
wget http://http.kali.org/kali/pool/main/k/kali-archive-keyring/kali-archive-keyring_2024.1_all.deb
# Install new apt keys
sudo dpkg -i kali-archive-keyring_2024.1_all.deb && rm kali-archive-keyring_2024.1_all.deb
# Update APT repository
sudo apt-get update
# CAI requieres python 3.12, lets install it (CAI for kali in Android)
sudo apt-get update && sudo apt-get install -y git python3-pip build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev pkg-config
wget https://www.python.org/ftp/python/3.12.4/Python-3.12.4.tar.xz
tar xf Python-3.12.4.tar.xz
cd ./configure --enable-optimizations
sudo make altinstall # This command takes long to execute
# Clone CAI's source code
git clone https://github.com/aliasrobotics/cai && cd cai
# Create virtual environment
python3.12 -m venv cai_env
# Install the package from the local directory
source cai_env/bin/activate && pip3 install -e .
# Generate a .env file and set up
cp .env.example .env # edit here your keys/models
# Launch CAI
cai
```
### :nut_and_bolt: Setup `.env` file
CAI leverages the `.env` file to load configuration at launch. To facilitate the setup, the repo provides an exemplary [`.env.example`](.env.example) file provides a template for configuring CAI's setup and your LLM API keys to work with desired LLM models.
:warning: Important:
CAI does NOT provide API keys for any model by default. Don't ask us to provide keys, use your own or host your own models.
:warning: Note:
The OPENAI_API_KEY must not be left blank. It should contain either "sk-123" (as a placeholder) or your actual API key. See https://github.com/aliasrobotics/cai/issues/27.
:warning: Note:
If you are using alias0 model, make sure that CAI is >0.4.0 version and here you have an .env example to be able to use it.
```bash
OPENAI_API_KEY="sk-1234"
OLLAMA=""
ALIAS_API_KEY="
" # note, add yours
CAI_STEAM=False
```
### πΉ Custom OpenAI Base URL Support
CAI supports configuring a custom OpenAI API base URL via the `OPENAI_BASE_URL` environment variable. This allows users to redirect API calls to a custom endpoint, such as a proxy or self-hosted OpenAI-compatible service.
Example `.env` entry configuration:
```
OLLAMA_API_BASE="https://custom-openai-proxy.com/v1"
```
Or directly from the command line:
```bash
OLLAMA_API_BASE="https://custom-openai-proxy.com/v1" cai
```
## :triangular_ruler: Architecture:
CAI focuses on making cybersecurity agent **coordination** and **execution** lightweight, highly controllable, and useful for humans. To do so it builds upon 7 pillars: `Agent`s, `Tools`, `Handoffs`, `Patterns`, `Turns`, `Tracing` and `HITL`.
```
βββββββββββββββββ βββββββββββββ
β HITL ββββββββββββΆβ Turns β
βββββββββ¬ββββββββ βββββββββββββ
β
βΌ
βββββββββββββ βββββββββββββ βββββββββββββ βββββββββββββ
β Patterns ββββββββΆβ Handoffs βββββββΆ β Agents βββββββΆβ LLMs β
βββββββββββββ βββββββ¬ββββββ βββββββββββββ βββββββββββββ
β β
β βΌ
ββββββββββββββ ββββββ΄βββββββ βββββββββββββ
β Extensions ββββββββΆβ Tracing β β Tools β
ββββββββββββββ βββββββββββββ βββββββββββββ
β
βββββββββββββββ¬ββββββ΄βββββ¬ββββββββββββββ
βΌ βΌ βΌ βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LinuxCmd ββ WebSearch ββ Code ββ SSHTunnel β
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
If you want to dive deeper into the code, check the following files as a start point for using CAI:
* [__init__.py](https://github.com/aliasrobotics/cai/blob/main/src/cai/__init__.py)
* [cli.py](https://github.com/aliasrobotics/cai/blob/main/src/cai/cli.py) - entrypoint for command line interface
* [util.py](https://github.com/aliasrobotics/cai/blob/main/src/cai/util.py) - utility functions
* [agents](https://github.com/aliasrobotics/cai/blob/main/src/cai/agents) - Agent implementations
* [internal](https://github.com/aliasrobotics/cai/blob/main/src/cai/internal) - CAI internal functions (endpoints, metrics, logging, etc.)
* [prompts](https://github.com/aliasrobotics/cai/blob/main/src/cai/prompts) - Agent Prompt Database
* [repl](https://github.com/aliasrobotics/cai/blob/main/src/cai/repl) - CLI aesthetics and commands
* [sdk](https://github.com/aliasrobotics/cai/blob/main/src/cai/sdk) - CAI command sdk
* [tools](https://github.com/aliasrobotics/cai/tree/main/src/cai/tools) - agent tools
### πΉ Agent
At its core, CAI abstracts its cybersecurity behavior via `Agents` and agentic `Patterns`. An Agent in *an intelligent system that interacts with some environment*. More technically, within CAI we embrace a robotics-centric definition wherein an agent is anything that can be viewed as a system perceiving its environment through sensors, reasoning about its goals and and acting accordingly upon that environment through actuators (*adapted* from Russel & Norvig, AI: A Modern Approach). In cybersecurity, an `Agent` interacts with systems and networks, using peripherals and network interfaces as sensors, reasons accordingly and then executes network actions as if actuators. Correspondingly, in CAI, `Agent`s implement the `ReACT` (Reasoning and Action) agent model[^3]. For more information, see the [example here](https://github.com/aliasrobotics/cai/blob/main/examples/basic/hello_world.py) for the full execution code, and refer to this [jupyter notebook](https://github.com/aliasrobotics/cai/blob/main/fluency/my-first-hack/my_first_hack.ipynb) for a tutorial on how to use it.
```python
from cai.sdk.agents import Agent, Runner, OpenAIChatCompletionsModel
import os
from openai import AsyncOpenAI
from dotenv import load_dotenv
load_dotenv()
agent = Agent(
name="Custom Agent",
instructions="""You are a Cybersecurity expert Leader""",
model=OpenAIChatCompletionsModel(
model=os.getenv('CAI_MODEL', "openai/gpt-4o"),
openai_client=AsyncOpenAI(),
)
)
message = "Tell me about recursion in programming."
result = await Runner.run(agent, message)
```
### πΉ Tools
`Tools` let cybersecurity agents take actions by providing interfaces to execute system commands, run security scans, analyze vulnerabilities, and interact with target systems and APIs - they are the core capabilities that enable CAI agents to perform security tasks effectively; in CAI, tools include built-in cybersecurity utilities (like LinuxCmd for command execution, WebSearch for OSINT gathering, Code for dynamic script execution, and SSHTunnel for secure remote access), function calling mechanisms that allow integration of any Python function as a security tool, and agent-as-tool functionality that enables specialized security agents (such as reconnaissance or exploit agents) to be used by other agents, creating powerful collaborative security workflows without requiring formal handoffs between agents. For more information, please refer to the [example here](https://github.com/aliasrobotics/cai/blob/main/examples/basic/tools.py) for the complete configuration of custom functions.
```python
from cai.sdk.agents import Agent, Runner, OpenAIChatCompletionsModel
from cai.tools.reconnaissance.exec_code import execute_code
from cai.tools.reconnaissance.generic_linux_command import generic_linux_command
import os
from openai import AsyncOpenAI
from dotenv import load_dotenv
load_dotenv()
agent = Agent(
name="Custom Agent",
instructions="""You are a Cybersecurity expert Leader""",
tools= [
generic_linux_command,
execute_code
],
model=OpenAIChatCompletionsModel(
model=os.getenv('CAI_MODEL', "openai/gpt-4o"),
openai_client=AsyncOpenAI(),
)
)
message = "Tell me about recursion in programming."
result = await Runner.run(agent, message)
```
You may find different [tools](cai/tools). They are grouped in 6 major categories inspired by the security kill chain [^2]:
1. Reconnaissance and weaponization - *reconnaissance* (crypto, listing, etc)
2. Exploitation - *exploitation*
3. Privilege escalation - *escalation*
4. Lateral movement - *lateral*
5. Data exfiltration - *exfiltration*
6. Command and control - *control*
### πΉ Handoffs
`Handoffs` allow an `Agent` to delegate tasks to another agent, which is crucial in cybersecurity operations where specialized expertise is needed for different phases of an engagement. In our framework, `Handoffs` are implemented as tools for the LLM, where a **handoff/transfer function** like `transfer_to_flag_discriminator` enables the `ctf_agent` to pass control to the `flag_discriminator_agent` once it believes it has found the flag. This creates a security validation chain where the first agent handles exploitation and flag discovery, while the second agent specializes in flag verification, ensuring proper segregation of duties and leveraging specialized capabilities of different models for distinct security tasks. For more information, please refer to the [example here](https://github.com/aliasrobotics/cai/blob/main/examples/cai/agent_patterns/handoffs.py) for the full execution code.
```python
from cai.sdk.agents import function_tool
from cai.tools.common import run_command
from cai.sdk.agents import Agent, OpenAIChatCompletionsModel, HandoffInputData, Runner, function_tool, handoff, trace
from cai.sdk.agents.extensions import handoff_filters
import os
from openai import AsyncOpenAI
from dotenv import load_dotenv
load_dotenv()
@function_tool
def execute_cli_command(command: str) -> str:
return run_command(command)
flag_discriminator = Agent(
name="Flag discriminator",
description="Agent focused on extracting the flag from the output",
instructions="You are an agent tailored to extract the flag from a given output.",
model=OpenAIChatCompletionsModel(
model=os.getenv('CAI_MODEL', "qwen2.5:14b"),
openai_client=AsyncOpenAI(),
)
)
ctf_agent = Agent(
name="CTF agent",
description="Agent focused on conquering security challenges",
instructions="You are a Cybersecurity expert Leader facing a CTF",
tools=[
execute_cli_command,
],
model=OpenAIChatCompletionsModel(
model= os.getenv('CAI_MODEL', "qwen2.5:14b"),
openai_client=AsyncOpenAI(),
),
handoffs = [flag_discriminator]
)
```
### πΉ Patterns
An agentic `Pattern` is a *structured design paradigm* in artificial intelligence systems where autonomous or semi-autonomous agents operate within a defined *interaction framework* (the pattern) to achieve a goal. These `Patterns` specify the organization, coordination, and communication
methods among agents, guiding decision-making, task execution, and delegation.
An agentic pattern (`AP`) can be formally defined as a tuple:
\\[
AP = (A, H, D, C, E)
\\]
wherein:
- **\\(A\\) (Agents):** A set of autonomous entities, \\( A = \\{a_1, a_2, ..., a_n\\} \\), each with defined roles, capabilities, and internal states.
- **\\(H\\) (Handoffs):** A function \\( H: A \times T \to A \\) that governs how tasks \\( T \\) are transferred between agents based on predefined logic (e.g., rules, negotiation, bidding).
- **\\(D\\) (Decision Mechanism):** A decision function \\( D: S \to A \\) where \\( S \\) represents system states, and \\( D \\) determines which agent takes action at any given time.
- **\\(C\\) (Communication Protocol):** A messaging function \\( C: A \times A \to M \\), where \\( M \\) is a message space, defining how agents share information.
- **\\(E\\) (Execution Model):** A function \\( E: A \times I \to O \\) where \\( I \\) is the input space and \\( O \\) is the output space, defining how agents perform tasks.
When building `Patterns`, we generall y classify them among one of the following categories, though others exist:
| **Agentic** `Pattern` **categories** | **Description** |
|--------------------|------------------------|
| `Swarm` (Decentralized) | Agents share tasks and self-assign responsibilities without a central orchestrator. Handoffs occur dynamically. *An example of a peer-to-peer agentic pattern is the `CTF Agentic Pattern`, which involves a team of agents working together to solve a CTF challenge with dynamic handoffs.* |
| `Hierarchical` | A top-level agent (e.g., "PlannerAgent") assigns tasks via structured handoffs to specialized sub-agents. Alternatively, the structure of the agents is harcoded into the agentic pattern with pre-defined handoffs. |
| `Chain-of-Thought` (Sequential Workflow) | A structured pipeline where Agent A produces an output, hands it to Agent B for reuse or refinement, and so on. Handoffs follow a linear sequence. *An example of a chain-of-thought agentic pattern is the `ReasonerAgent`, which involves a Reasoning-type LLM that provides context to the main agent to solve a CTF challenge with a linear sequence.*[^1] |
| `Auction-Based` (Competitive Allocation) | Agents "bid" on tasks based on priority, capability, or cost. A decision agent evaluates bids and hands off tasks to the best-fit agent. |
| `Recursive` | A single agent continuously refines its own output, treating itself as both executor and evaluator, with handoffs (internal or external) to itself. *An example of a recursive agentic pattern is the `CodeAgent` (when used as a recursive agent), which continuously refines its own output by executing code and updating its own instructions.* |
For more information and examples of common agentic patterns, see the [examples folder](https://github.com/aliasrobotics/cai/blob/main/examples/agent_patterns/README.md).
### πΉ Turns and Interactions
During the agentic flow (conversation), we distinguish between **interactions** and **turns**.
- **Interactions** are sequential exchanges between one or multiple agents. Each agent executing its logic corresponds with one *interaction*. Since an `Agent` in CAI generally implements the `ReACT` agent model[^3], each *interaction* consists of 1) a reasoning step via an LLM inference and 2) act by calling zero-to-n `Tools`. This is defined in`process_interaction()` in [core.py](cai/core.py).
- **Turns**: A turn represents a cycle of one ore more **interactions** which finishes when the `Agent` (or `Pattern`) executing returns `None`, judging there're no further actions to undertake. This is defined in `run()`, see [core.py](cai/core.py).
> [!NOTE]
> CAI Agents are not related to Assistants in the Assistants API. They are named similarly for convenience, but are otherwise completely unrelated. CAI is entirely powered by the Chat Completions API and is hence stateless between calls.
### πΉ Tracing
CAI implements AI observability by adopting the OpenTelemetry standard and to do so, it leverages [Phoenix](https://github.com/Arize-ai/phoenix) which provides comprehensive tracing capabilities through OpenTelemetry-based instrumentation, allowing you to monitor and analyze your security operations in real-time. This integration enables detailed visibility into agent interactions, tool usage, and attack vectors throughout penetration testing workflows, making it easier to debug complex exploitation chains, track vulnerability discovery processes, and optimize agent performance for more effective security assessments.
### πΉ Human-In-The-Loop (HITL)
```
βββββββββββββββββββββββββββββββββββ
β β
β Cybersecurity AI (CAI) β
β β
β βββββββββββββββββββ β
β β Autonomous AI β β
β ββββββββββ¬βββββββββ β
β β β
β β β
β ββββββββββΌββββββββββ β
β β HITL Interaction β β
β ββββββββββ¬ββββββββββ β
β β β
ββββββββββββββββββΌβββββββββββββββββ
β
β Ctrl+C (cli.py)
β
βββββββββββββΌββββββββββββ
β Human Operator(s) β
β Expertise | Judgment β
β Teleoperation β
βββββββββββββββββββββββββ
```
CAI delivers a framework for building Cybersecurity AIs with a strong emphasis on *semi-autonomous* operation, as the reality is that **fully-autonomous** cybersecurity systems remain premature and face significant challenges when tackling complex tasks. While CAI explores autonomous capabilities, we recognize that effective security operations still require human teleoperation providing expertise, judgment, and oversight in the security process.
Accordingly, the Human-In-The-Loop (`HITL`) module is a core design principle of CAI, acknowledging that human intervention and teleoperation are essential components of responsible security testing. Through the `cli.py` interface, users can seamlessly interact with agents at any point during execution by simply pressing `Ctrl+C`. This is implemented across [core.py](cai/core.py) and also in the REPL abstractions [REPL](cai/repl).
## :rocket: Quickstart
To start CAI after installing it, just type `cai` in the CLI:
```bash
ββ# cai
CCCCCCCCCCCCC ++++++++ ++++++++ IIIIIIIIII
CCC::::::::::::C ++++++++++ ++++++++++ I::::::::I
CC:::::::::::::::C ++++++++++ ++++++++++ I::::::::I
C:::::CCCCCCCC::::C +++++++++ ++ +++++++++ II::::::II
C:::::C CCCCCC +++++++ +++++ +++++++ I::::I
C:::::C +++++ +++++++ +++++ I::::I
C:::::C ++++ ++++ I::::I
C:::::C ++ ++ I::::I
C:::::C + +++++++++++++++ + I::::I
C:::::C +++++++++++++++++++ I::::I
C:::::C +++++++++++++++++ I::::I
C:::::C CCCCCC +++++++++++++++ I::::I
C:::::CCCCCCCC::::C +++++++++++++ II::::::II
CC:::::::::::::::C +++++++++ I::::::::I
CCC::::::::::::C +++++ I::::::::I
CCCCCCCCCCCCC ++ IIIIIIIIII
Cybersecurity AI (CAI), vX.Y.Z
Bug bounty-ready AI
CAI>
```
That should initialize CAI and provide a prompt to execute any security task you want to perform. The navigation bar at the bottom displays important system information. This information helps you understand your environment while working with CAI.
Here's a quick [demo video](https://asciinema.org/a/zm7wS5DA2o0S9pu1Tb44pnlvy) to help you get started with CAI. We'll walk through the basic steps β from launching the tool to running your first AI-powered task in the terminal. Whether you're a beginner or just curious, this guide will show you how easy it is to begin using CAI.
From here on, type on `CAI` and start your security exercise. Best way to learn is by example:
### Environment Variables
For using private models, you are given a [`.env.example`](.env.example) file. Copy it and rename it as `.env`. Fill in your corresponding API keys, and you are ready to use CAI.
List of Environment Variables
| Variable | Description |
|----------|-------------|
| CTF_NAME | Name of the CTF challenge to run (e.g. "picoctf_static_flag") |
| CTF_CHALLENGE | Specific challenge name within the CTF to test |
| CTF_SUBNET | Network subnet for the CTF container |
| CTF_IP | IP address for the CTF container |
| CTF_INSIDE | Whether to conquer the CTF from within container |
| CAI_MODEL | Model to use for agents |
| CAI_DEBUG | Set debug output level (0: Only tool outputs, 1: Verbose debug output, 2: CLI debug output) |
| CAI_BRIEF | Enable/disable brief output mode |
| CAI_MAX_TURNS | Maximum number of turns for agent interactions |
| CAI_TRACING | Enable/disable OpenTelemetry tracing |
| CAI_AGENT_TYPE | Specify the agents to use (boot2root, one_tool...) |
| CAI_STATE | Enable/disable stateful mode |
| CAI_MEMORY | Enable/disable memory mode (episodic, semantic, all) |
| CAI_MEMORY_ONLINE | Enable/disable online memory mode |
| CAI_MEMORY_OFFLINE | Enable/disable offline memory |
| CAI_ENV_CONTEXT | Add dirs and current env to llm context |
| CAI_MEMORY_ONLINE_INTERVAL | Number of turns between online memory updates |
| CAI_PRICE_LIMIT | Price limit for the conversation in dollars |
| CAI_REPORT | Enable/disable reporter mode (ctf, nis2, pentesting) |
| CAI_SUPPORT_MODEL | Model to use for the support agent |
| CAI_SUPPORT_INTERVAL | Number of turns between support agent executions |
| CAI_WORKSPACE | Defines the name of the workspace |
| CAI_WORKSPACE_DIR | Specifies the directory path where the workspace is located |
### OpenRouter Integration
The Cybersecurity AI (CAI) platform offers seamless integration with OpenRouter, a unified interface for Large Language Models (LLMs). This integration is crucial for users who wish to leverage advanced AI capabilities in their cybersecurity tasks. OpenRouter acts as a bridge, allowing CAI to communicate with various LLMs, thereby enhancing the flexibility and power of the AI agents used within CAI.
To enable OpenRouter support in CAI, you need to configure your environment by adding specific entries to your `.env` file. This setup ensures that CAI can interact with the OpenRouter API, facilitating the use of sophisticated models like Meta-LLaMA. Hereβs how you can configure it:
```bash
CAI_AGENT_TYPE=redteam_agent
CAI_MODEL=openrouter/meta-llama/llama-4-maverick
OPENROUTER_API_KEY= # note, add yours
OPENROUTER_API_BASE=https://openrouter.ai/api/v1
```
### MCP
CAI supports the Model Context Protocol (MCP) for integrating external tools and services with AI agents. MCP is supported via two transport mechanisms:
1. **SSE (Server-Sent Events)** - For web-based servers that push updates over HTTP connections:
```bash
CAI>/mcp load http://localhost:9876/sse burp
```
2. **STDIO (Standard Input/Output)** - For local inter-process communication:
```bash
CAI>/mcp load stdio myserver python mcp_server.py
```
Once connected, you can add the MCP tools to any agent:
```bash
CAI>/mcp add burp redteam_agent
Adding tools from MCP server 'burp' to agent 'Red Team Agent'...
Adding tools to Red Team Agent
βββββββββββββββββββββββββββββββββββββ³βββββββββ³ββββββββββββββββββββββββββββββββββββββββββββββββββ
β Tool β Status β Details β
β‘βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ©
β send_http_request β Added β Available as: send_http_request β
β create_repeater_tab β Added β Available as: create_repeater_tab β
β send_to_intruder β Added β Available as: send_to_intruder β
β url_encode β Added β Available as: url_encode β
β url_decode β Added β Available as: url_decode β
β base64encode β Added β Available as: base64encode β
β base64decode β Added β Available as: base64decode β
β generate_random_string β Added β Available as: generate_random_string β
β output_project_options β Added β Available as: output_project_options β
β output_user_options β Added β Available as: output_user_options β
β set_project_options β Added β Available as: set_project_options β
β set_user_options β Added β Available as: set_user_options β
β get_proxy_http_history β Added β Available as: get_proxy_http_history β
β get_proxy_http_history_regex β Added β Available as: get_proxy_http_history_regex β
β get_proxy_websocket_history β Added β Available as: get_proxy_websocket_history β
β get_proxy_websocket_history_regex β Added β Available as: get_proxy_websocket_history_regex β
β set_task_execution_engine_state β Added β Available as: set_task_execution_engine_state β
β set_proxy_intercept_state β Added β Available as: set_proxy_intercept_state β
β get_active_editor_contents β Added β Available as: get_active_editor_contents β
β set_active_editor_contents β Added β Available as: set_active_editor_contents β
βββββββββββββββββββββββββββββββββββββ΄βββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββββ
Added 20 tools from server 'burp' to agent 'Red Team Agent'.
CAI>/agent 13
CAI>Create a repeater tab
```
You can list all active MCP connections and their transport types:
```bash
CAI>/mcp list
```
https://github.com/user-attachments/assets/386a1fd3-3469-4f84-9396-2a5236febe1f
## Development
Development is facilitated via VS Code dev. environments. To try out our development environment, clone the repository, open VS Code and enter de dev. container mode:
### Contributions
If you want to contribute to this project, use [**Pre-commit**](https://pre-commit.com/) before your MR
```bash
pip install pre-commit
pre-commit # files staged
pre-commit run --all-files # all files
```
### Optional Requirements: caiextensions
Currently, the extensions are not publicly available as the engineering endeavour to maintain them is significant. Instead, we're making selected custom caiextensions available for partner companies across collaborations.
### :information_source: Usage Data Collection
CAI is provided free of charge for researchers. To improve CAIβs detection accuracy and publish open security research, instead of payment for research use cases, we ask you to contribute to the CAI community by allowing usage data collection. This data helps us identify areas for improvement, understand how the framework is being used, and prioritize new features. Legal basis of data collection is under Art. 6 (1)(f) GDPR β CAIβs legitimate interest in maintaining and improving security tooling, with Art. 89 safeguards for research. The collected data includes:
- Basic system information (OS type, Python version)
- Username and IP information
- Tool usage patterns and performance metrics
- Model interactions and token usage statistics
We take your privacy seriously and only collect what's needed to make CAI better. For further info, reach out to researchοΌ aliasrobotics.com. You can disable some of the data collection features via the `CAI_TELEMETRY` environment variable but we encourage you to keep it enabled and contribute back to research:
```bash
CAI_TELEMETRY=False cai
```
### Reproduce CI-Setup locally
To simulate the CI/CD pipeline, you can run the following in the Gitlab runner machines:
```bash
docker run --rm -it \
--privileged \
--network=exploitflow_net \
--add-host="host.docker.internal:host-gateway" \
-v /cache:/cache \
-v /var/run/docker.sock:/var/run/docker.sock:rw \
registry.gitlab.com/aliasrobotics/alias_research/cai:latest bash
```
## FAQ
OLLAMA is giving me 404 errors
Ollama's API in OpenAI mode uses `/v1/chat/completions` whereas the `openai` library uses `base_url` + `/chat/completions`.
We adopt the latter for overall alignment with the gen AI community and empower the former by allowing users to add the `v1` themselves via:
```bash
OLLAMA_API_BASE=http://IP:PORT/v1
```
See the following issues that treat this topic in more detail:
- https://github.com/aliasrobotics/cai/issues/76
- https://github.com/aliasrobotics/cai/issues/83
- https://github.com/aliasrobotics/cai/issues/82
Where are all the caiextensions?
See [all caiextensions](https://gitlab.com/aliasrobotics/alias_research/caiextensions)
How do I install the report caiextension?
[See here](#optional-requirements-caiextensions)
How do I set up SSH access for Gitlab?
Generate a new SSH key
```bash
ssh-keygen -t ed25519
```
Add the key to the SSH agent
```bash
ssh-add ~/.ssh/id_ed25519
```
Add the public key to Gitlab
Copy the key and add it to Gitlab under https://gitlab.com/-/user_settings/ssh_keys
```bash
cat ~/.ssh/id_ed25519.pub
```
To verify it:
```bash
ssh -T git@gitlab.com
Welcome to GitLab, @vmayoral!
```
How do I clear Python cache?
```bash
find . -name "*.pyc" -delete && find . -name "__pycache__" -delete
```
If host networking is not working with ollama check whether it has been disabled in Docker because you are not signed in
Docker in OS X behaves funny sometimes. Check if the following message has shown up:
*Host networking has been disabled because you are not signed in. Please sign in to enable it*.
Make sure this has been addressed and also that the Dev Container is not forwarding the 8000 port (click on x, if necessary in the ports section).
To verify connection, from within the VSCode devcontainer:
```bash
curl -v http://host.docker.internal:8000/api/version
```
Run CAI against any target
The starting user prompt in this case is: `Target IP: 192.168.3.10, perform a full network scan`.
The agent started performing a nmap scan. You could either interact with the agent and give it more instructions, or let it run to see what it explores next.
How do I interact with the agent? Type twice CTRL + C
If you want to use the HITL mode, you can do it by presssing twice ```Ctrl + C```.
This will allow you to interact (prompt) with the agent whenever you want. The agent will not lose the previous context, as it is stored in the `history` variable, which is passed to it and any agent that is called. This enables any agent to use the previous information and be more accurate and efficient.
Can I change the model while CAI is running? /model
Use ```/model``` to change the model.
How can I list all the agents available? /agent
Use ```/agent``` to list all the agents available.
Where can I list all the environment variables? /config
How to know more about the CLI? /help
How can I trace the whole execution?
The environment variable `CAI_TRACING` allows the user to set it to `CAI_TRACING=true` to enable tracing, or `CAI_TRACING=false` to disable it.
When CAI is prompted by the first time, the user is provided with two paths, the execution log, and the tracing log.
Can I expand CAI capabilities using previous run logs?
Absolutely! The **memory extension** allows you to use a previously sucessful runs ( the log object is stored as a **.jsonl file in the [log](cai/logs) folder** ) in a new run against the same target.
The user is also given the path highlighted in orange as shown below.
How to make use of this functionality?
1. Run CAI against the target. Let's assume the target name is: `target001`.
2. Get the log file path, something like: ```logs/cai_20250408_111856.jsonl```
3. Generate the memory using any model of your preference:
```shell JSONL_FILE_PATH="logs/cai_20250408_111856.jsonl" CTF_INSIDE="false" CAI_MEMORY_COLLECTION="target001" CAI_MEMORY="episodic" CAI_MODEL="claude-3-5-sonnet-20241022" python3 tools/2_jsonl_to_memory.py ```
The script [`tools/2_jsonl_to_memory.py`](cai/tools/2_jsonl_to_memory.py) will generate a memory collection file with the most relevant steps. The quality of the memory collection will depend on the model you use.
4. Use the generated memory collection and execute a new run:
```shell CAI_MEMORY="episodic" CAI_MODEL="gpt-4o" CAI_MEMORY_COLLECTION="target001" CAI_TRACING=false python3 cai/cli.py```
Can I expand CAI capabilities using scripts or extra information?
Currently, CAI supports text based information. You can add any extra information on the target you are facing by copy-pasting it directly into the system or user prompt.
**How?** By adding it to the system ([`system_master_template.md`](cai/repl/templates/system_master_template.md)) or the user prompt ([`user_master_template.md`](cai/repl/templates/user_master_template.md)). You can always directly prompt the path to the model, and it will ```cat``` it.
How CAI licence works?
CAIβs current license does not restrict usage for research purposes. You are free to use CAI for security assessments (pentests), to develop additional features, and to integrate it into your research activities, as long as you comply with local laws.
If you or your organization start benefiting commercially from CAI (e.g., offering pentesting services powered by CAI), then a commercial license will be required to help sustain the project.
CAI itself is not a profit-seeking initiative. Our goal is to build a sustainable open-source project. We simply ask that those who profit from CAI contribute back and support our ongoing development.