AI agents that run a penetration test end to end and write the report.

[!WARNING] REDCELL runs real offensive tooling. Only point it at systems you own or are authorized to test. Staying in scope and within the law is on you.

What it is

REDCELL runs a team of LLM agents through a pentest. An orchestrator plans the engagement and hands objectives to executor agents, which run real tools inside a Kali container and report back. You watch and steer the run from an operator console: a chat that drives the orchestrator, a live agent graph and activity feed, a live view of the browser the agent drives, a terminal on any reverse shell the agent catches, and a report to hand over when the work is done.

Models are pluggable through LiteLLM, so you can point it at OpenAI, Anthropic, Google, GLM, DeepSeek, Kimi, a local Ollama, or anything else it supports. Every run checkpoints as it goes, so a crash or a restart picks up where it left off.

Features

  • Multi-agent engine. A LangGraph plan/act loop. The orchestrator delegates objectives to executor agents that run shell tools and record findings, loot, and hosts as they work.
  • Structured tools. Dedicated tools for nmap, nuclei, directory and vhost discovery, and Metasploit search and run. Each parses its own output into the attack surface or findings, so a scan records hosts and vulnerabilities without a follow-up step. run_command covers anything without a dedicated tool.
  • Real execution, local or remote. Tools run in a Kali container over docker exec. Pick localhost or a saved server per session; a remote server runs the same container over SSH with host networking.
  • Agent browser. For login flows and JavaScript-heavy apps that shell tools cannot reach, an agent drives a real Chromium in the Kali container. You watch it live and can take control to click through something yourself, then hand it back.
  • Reverse shells. An agent opens a listener, catches the shell, and gives you an interactive terminal on it. You can also open your own terminals and run commands yourself.
  • Network pivoting. Route tool traffic through a caught reverse shell to reach hosts that are only visible from the compromised machine. A chisel reverse SOCKS tunnel carries it, and nmap runs through the tunnel automatically.
  • Chat drives the run. Tell the chat what you want and it steers the live orchestrator, or reopens a finished run to take on new work. It answers questions about the engagement too.
  • Code-scan sessions. Point a session at a public git repo or a local folder for a source-code security review, with findings mapped back to file and line.
  • Per-session config. Set the execution server, the model, and an optional egress proxy per session. Servers and proxies come with a real connection test so you know they work before you rely on them.
  • Findings triage. Verify or dismiss findings and merge duplicates the agent recorded twice. The report leaves out the dismissed ones and marks the verified ones.
  • Reports. Export a PDF plus JSON and SARIF. The write-up is generated by the session's model and cleaned up to read like a person wrote it, with an executive summary, methodology, findings, and remediation in priority order.
  • Live console. The activity feed, terminals, and the agent's browser stream over WebSockets; the agent graph, findings, loot, attack surface, listeners, and proxy history refresh on a short poll. All of it updates live as the run works.
  • Notifications. In-app toasts, plus browser notifications when the tab is in the background so a question from the agent or a caught shell does not sit unseen.

Architecture

flowchart LR
  UI["Operator console<br/>React + Vite"] -->|REST + WebSocket| API["FastAPI"]
  API --> PG[(PostgreSQL)]
  API --> RS[(Redis<br/>pub/sub + queue)]
  API --> S3[(MinIO<br/>files & reports)]
  RS --> W["Worker (arq)"]
  W --> ENG["Engine<br/>LangGraph + LiteLLM"]
  ENG -->|docker exec| KALI["Kali container<br/>local or remote over SSH"]
  KALI --> TGT["Targets"]
  W -->|events / chat / shell| RS
  RS -->|stream| API

The API does not run agents. It queues a run, the worker executes it, and the worker publishes output onto Redis channels that the API relays to the browser over WebSockets.

Stack

Python 3.12, FastAPI, async SQLAlchemy + asyncpg, Alembic, arq, LangGraph, LiteLLM, ReportLab, PostgreSQL, Redis, MinIO, asyncssh. Frontend: React 18, Vite, TypeScript, Tailwind, TanStack Query, xterm. Tooling: uv for Python, bun for the frontend.

Quickstart

You will need Docker, uv, and bun.

docker compose -f docker-compose.dev.yml up -d

# 2. Python deps, database, and seed data
uv sync --group live
uv run rc db upgrade
uv run rc seed              # admin user, provider catalog, buckets

# 3. copy the env template
cp .env.example .env

# 4. run the three processes (separate terminals)
cd apps/api    && uv run uvicorn app.main:app --host 127.0.0.1 --port 8080
cd apps/worker && uv run arq worker.settings.WorkerSettings
cd apps/web    && bun install && bun run dev

Open http://localhost:5183 and sign in with admin / admin.

Runs execute real tools by default. Add a provider API key in Settings and make sure Docker can pull the Kali image (martian56/kali:latest). To dry-run against canned output instead, set REDCELL_RUN_MODE=sim in .env.

Practice targets

Intentionally vulnerable apps to aim REDCELL at, all local:

docker compose -f docker-compose.targets.yml up -d
# DVWA http://localhost:8081 · Juice Shop http://localhost:3000 · WebGoat http://localhost:8082

Configuration

Backend config is one root .env (see .env.example), read by both the API and the worker. The ones worth knowing:

  • REDCELL_RUN_MODE: live (default) or sim.
  • REDCELL_DATABASE_URL, REDCELL_REDIS_URL, REDCELL_S3_*: infrastructure.
  • REDCELL_SECRET_KEY: Fernet key for encrypting stored credentials. Set a real one before you go to production.

Provider API keys, the execution image, scope guardrails, and report branding live in the Settings page and are stored in the database, encrypted where they need to be.

Project layout

apps/
  api/                 FastAPI: routers, WebSocket streams, auth
  worker/              arq worker: runs engagements and report generation
  web/                 React operator console
packages/
  core/redcell_core/   engine, models, repositories, storage, bus, reporting
  api-client/          the single typed client the UI talks to (mock + HTTP)
docker/                Kali execution image
docker-compose.dev.yml       Postgres + Redis + MinIO
docker-compose.targets.yml   local vulnerable targets

Responsible use

This is defensive and authorized-offensive tooling for security professionals, CTFs, and your own labs. Do not use it against systems you have no written permission to test. The maintainers are not responsible for misuse.