Aethena-Lab/Z3r0

Z3r0 – AI‑native Red‑Team Workbench

What it is – Z3r0 is a platform that lets authorized security teams run penetration‑testing and vulnerability‑research projects with the help of AI agents. It combines a React‑based operator console, a FastAPI control plane, and a multi‑agent runtime that can retrieve context from a lightweight RAG (LightRAG) engine. All actions happen inside sandboxed Docker containers, and every step is recorded as immutable evidence that can be replayed later.

Why it matters – Traditional red‑team tooling is a collection of separate scripts and manual notes. Z3r0 ties together:

• Agent orchestration – a lead AI agent coordinates specialist agents (e.g., code‑audit, intel‑gathering, cryptanalysis).
• Graph‑driven workflow – assets, relations, work items and findings are stored in a project‑scoped graph, making it easy to see coverage and dependencies.
• Replayable timelines – every command, tool output, and decision is streamed as a timeline event and persisted in PostgreSQL, enabling full post‑mortem reviews.
• Secure sandboxes – Docker hosts provide isolated execution environments with a pre‑loaded security toolchain (nmap, curl, Ghidra, pwntools, etc.) and a controllable egress proxy (direct, HTTP/HTTPS, SOCKS5).

Core components

Plane	Role
Control plane	React UI ↔ FastAPI API; manages users, projects, agents, Docker hosts, sandbox images, and optional FOFA asset search.
Runtime plane	Session‑based multi‑agent execution; LightRAG retrieval; live event streaming; timeline generation and replay.
Evidence plane	Stores authorized scope, asset graph, work items, immutable evidence, findings, and attack‑path mappings.
Execution plane	Managed Docker hosts and containers; shell/file/noVNC access; sandbox‑local skills; outbound egress policy.

Typical workflow

1. Create a work project – define the authorized scope and bind it to one or more sandbox containers.
2. Submit a message from the UI (e.g., “enumerate subdomains for target.com”).
3. The FastAPI control plane starts or resumes a session and asks LightRAG for relevant context.
4. The lead AI agent delegates the task to a specialist agent, which invokes the appropriate sandbox tool.
5. Results, command output, and any generated artifacts are stored as Evidence linked to the work item.
6. Findings are recorded, optionally scored with CVSS, and mapped to ATT&CK steps.
7. All events are streamed to the UI and persisted as a Timeline that can be replayed for audits or training.

Key technical highlights

• Multi‑agent orchestration – lead + specialist agents for intelligence gathering, code audit, reverse engineering, cryptanalysis, etc.
• LightRAG Core – provides semantic retrieval of document chunks and graph context to inform agent decisions.
• Distributed sandbox pool – Docker hosts can be added or removed; containers are assigned per project and controlled via a proxy.
• Unified egress layer – container traffic is forced through a configurable proxy, supporting direct, HTTP/HTTPS, or SOCKS5 routes.
• Replayable event timeline – normalized events are stored in PostgreSQL and can be streamed live or loaded later.

Getting started (quick)

1. Clone the repo and run docker compose up -d (the repo includes a Docker‑Compose file that starts the FastAPI service, PostgreSQL, and the React UI).
2. Open the UI at http://localhost:3000, create a new Work Project, and bind it to an available sandbox container.
3. Use the chat‑style console to issue a test command (e.g., nmap -sV target.example.com).
4. Observe the agent‑driven workflow, evidence record, and timeline updates in real time.

Who should use it – Security teams that need a structured, auditable environment for authorized red‑team engagements; researchers exploring AI‑augmented penetration testing; organizations that want to keep a tamper‑proof record of all testing activities.

License – MIT (see LICENSE).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.