martian56/redcell

AI red-team platform. Autonomous LLM agents run a penetration test end to end inside a Kali container and write the report. LangGraph plan/act engine, provider-agnostic models via LiteLLM, PDF/JSON/SARIF output. FastAPI + React.

REDCELL – AI‑driven penetration‑testing platform

What it is – REDCELL is a self‑hosted web application that orchestrates a team of LLM‑powered agents to perform a full penetration test and generate a professional report. An orchestrator (built with LangGraph) hands concrete objectives to executor agents that run real security tools inside a Kali Linux Docker container. The operator watches a React console, can chat with the orchestrator, inspect live tool output, take control of a browser or reverse‑shell, and finally export a PDF/JSON/SARIF report.

Core components

Component	Role
Operator console (React + Vite)	Chat UI, live graph, activity feed, terminals, browser view, report download
API (FastAPI)	REST + WebSocket gateway, authentication, stores session metadata in PostgreSQL
Worker (arq)	Pulls queued runs from Redis, runs the LangGraph engine, streams events back
Engine (LangGraph + LiteLLM)	Multi‑agent planner/actor loop; LLMs are interchangeable via LiteLLM (OpenAI, Anthropic, local Ollama, etc.)
Kali container (Docker)	Executes real tools (nmap, nuclei, Metasploit, etc.) and a Chromium browser; can be run locally or over SSH on a remote host
Infrastructure	PostgreSQL (metadata), Redis (pub/sub & queue), MinIO (file storage), optional Caddy reverse‑proxy

Key features (as described in the README)

Multi‑agent engine – LangGraph plan/act loop; orchestrator delegates to executor agents.
Structured tool wrappers – Native integrations for nmap, nuclei, directory/vhost discovery, Metasploit search/run; generic run_command fallback.
Real execution – Tools run inside a Kali Docker image via docker exec; can also target a remote server over SSH.
Agent‑driven browser – Chromium inside the container for JS‑heavy login flows; operator can intervene live.
Reverse‑shell handling – Agent opens listeners, captures shells, and presents an interactive terminal.
Network pivoting – Automatic routing of tool traffic through a captured shell using a chisel SOCKS tunnel.
Chat‑driven control – Natural‑language chat steers the orchestrator, asks questions, or re‑opens finished runs.
Code‑scan mode – Scan a public repo or local folder; findings are linked to file/line numbers.
Per‑session configuration – Choose execution server, LLM provider, optional egress proxy; connection tests verify settings.
Findings triage – Verify/dismiss duplicate findings; only verified items appear in the final report.
Report generation – PDF/JSON/SARIF output, written by the session’s LLM and cleaned for readability.
Live console – Activity feed, terminals, browser view, and agent graph update in real time via WebSockets.
Notifications – In‑app toasts and browser notifications for prompts or caught shells.

Quick‑start workflow (from the README)

Start supporting services – docker compose -f docker-compose.dev.yml up -d (Postgres, Redis, MinIO).
Install Python deps & DB – uv sync --group live; uv run rc db upgrade; uv run rc seed (creates admin user, provider catalog, buckets).
Configure – copy .env.example → .env and edit as needed.
Run the three processes (in separate terminals or via honcho):
- API: uv run uvicorn app.main:app --host 127.0.0.1 --port 8080
- Worker: uv run arq worker.settings.WorkerSettings
- Web UI: bun install && bun run dev
Open http://localhost:5183, log in with admin/admin.
Add an LLM provider key in Settings, ensure the Kali image (martian56/kali:latest) can be pulled, then start a penetration‑test run.
For safe testing, use the supplied vulnerable targets (docker compose -f docker-compose.targets.yml up -d).

Intended use cases

Security researchers or red‑team engineers who want an LLM‑augmented workflow for reconnaissance, exploitation, and reporting.
Training labs / capture‑the‑flag events where participants can experiment with AI‑guided pentesting.
Organizations that need a reproducible, auditable penetration‑test pipeline that can be run on‑premise.

Limitations & cautions (from the repo)

Legal responsibility – The tool is for authorized testing only; misuse is illegal in many jurisdictions (explicit warning about Azerbaijan and other laws).
Run mode – By default tools execute live; a sim mode exists for dry‑run with canned output.
Infrastructure requirement – Requires Docker, a PostgreSQL/Redis/MinIO stack, and a Kali image; not a single‑binary solution.
Model costs – Token usage is tracked and billed according to the chosen LLM provider (see docs/COST.md).
Security of the platform – The README provides hardening docs; the system stores credentials encrypted with a Fernet key and recommends careful deployment behind a reverse proxy.

Legal & responsible‑use notice

The repository includes a detailed legal disclaimer: REDCELL is provided “as is” for education, research, and legally authorized security testing. Users must obtain explicit written permission before testing any system they do not own, and are responsible for complying with local, national, and international laws (e.g., Azerbaijan Criminal Code, Budapest Convention, EU Directive 2013/40/EU, UK Computer Misuse Act, US CFAA).

Bottom line

REDCELL is a genuine, open‑source AI‑agent platform that automates end‑to‑end penetration testing, combines real security tools with LLM reasoning, and offers a live operator UI plus automated reporting. It is a substantial project rather than a simple demo, and it sits squarely in the frontier of AI‑augmented cybersecurity.