Terminal 1: start a lab

<p align="center">
  <img src="assets/medusa.png" alt="Medusa Logo" width="160"/>
</p>
<h1 align="center">Medusa</h1>

<p align="center">
  <img height="20" src="https://img.shields.io/badge/v2.7.0-operators__cli-green?style=flat" alt="Version"/>
  <img height="20" src="https://img.shields.io/badge/LICENSE-MIT-4169A1?style=flat" alt="License"/>
  <img height="20" src="https://img.shields.io/badge/PYTHON-3.10+-306998?style=flat&logo=python&logoColor=white" alt="Python"/>
  <img height="20" src="https://img.shields.io/badge/LangGraph-State%20Machine-FF6B35?style=flat" alt="LangGraph"/>
</p>

Medusa is a dual-mode autonomous security platform: a **Red Team** agent that
chains reconnaissance → exploitation → reporting over a LangGraph state machine,
and a **Blue Team** agent that monitors live HTTP traffic, detects attacks, and
responds with deception, blocking, and source patching. Both modes share one
toolkit, one knowledge base, and one knowledge graph.

> **LEGAL DISCLAIMER**: This tool is intended for **authorized security
> testing**, **educational purposes**, and **research only**. Never use this
> system to scan, probe, or attack any system you do not own or have explicit
> written permission to test. Unauthorized access is **illegal**. By using this
> tool you accept full responsibility for your actions.

---

## Table of Contents

1. [Requirements](#requirements)
2. [Installation](#installation)
3. [CLI Reference](#cli-reference)
4. [First Engagement](#first-engagement)
5. [Configuration](#configuration)
6. [LLM Providers](#llm-providers)
7. [Knowledge Base](#knowledge-base)
8. [Agent Workspace](#agent-workspace)
9. [Architecture](#architecture)
10. [Red Team Reference](#red-team-reference)
11. [Blue Team Reference](#blue-team-reference)
12. [Built-in Labs](#built-in-labs)
13. [Testing](#testing)
14. [Project Layout](#project-layout)
15. [Troubleshooting](#troubleshooting)
16. [Glossary](#glossary)
17. [Contributing & Credits](#contributing--credits)

---

## Requirements

| Requirement | Details |
|:------------|:--------|
| Python | 3.10+ (3.14 tested) |
| OS | macOS, Linux, Windows |
| LLM API key | Optional — heuristic mode works without one |

---

## Installation

### One command (macOS / Linux)

```bash
curl -fsSL https://raw.githubusercontent.com/0xwi11iam/Medusa/main/install.sh | bash
medusa doctor     # verify the environment
medusa selftest   # offline smoke test (no network, no API keys)
medusa            # launch the interface
```

The installer clones into `~/.medusa/repo`, creates an isolated virtualenv, and
drops a `medusa` launcher on your PATH. Environment overrides:
`MEDUSA_INSTALL_DIR`, `MEDUSA_BIN_DIR`, `MEDUSA_REPO`, `MEDUSA_NO_PATH_EDIT`.

### Manual

```bash
git clone https://github.com/0xwi11iam/Medusa.git && cd Medusa
python3 -m venv .venv && source .venv/bin/activate
pip install -r medusa/requirements.txt
python3 medusa/main.py
```

### Docker

```bash
docker build -t medusa .
docker run -it --rm \
  -v $(pwd)/medusa_agent:/app/medusa_agent \
  -e ZAI_API_KEY=$ZAI_API_KEY \
  medusa
```

---

## CLI Reference

`medusa` bare launches the Rich TUI. Every subcommand below is
**non-interactive, offline, and scriptable** (exit 0 = healthy).

| Command | What it does |
|:--------|:-------------|
| `medusa` | Launch the classic Rich TUI (Red / Blue / Settings) |
| `medusa doctor` | Full environment check: python, deps, binaries, config, modules, KB, workspace |
| `medusa selftest` | Offline smoke test: imports, KB gating, workspace anchors, sandbox, boundaries |
| `medusa status` | One-page summary: provider, KB, workspace, modules, lab port |
| `medusa version` | Release, codename, python, platform, package path |
| `medusa env` | API key presence by name — values are never printed |
| `medusa tools` | All 112+ agent tools with availability (missing binaries marked) |
| `medusa modules` | Loaded module packs with tool counts and dependencies |
| `medusa skills` | Agent-editable attack/defense skills |
| `medusa config show` | Effective config (defaults merged), secrets redacted |
| `medusa config validate` | Pydantic validation of `config.json` + `blue_config.json` (exit 1 on failure) |
| `medusa workspace` | Workspace layout, per-directory usage, symlink health |
| `medusa reports` | Engagement reports in `medusa_agent/reports/` (newest first) |
| `medusa sessions` | Saved engagement sessions with objectives |
| `medusa labs` | Built-in labs: list ports / `run` a capability campaign |
| `medusa ui` | Launch the **web dashboard** on `127.0.0.1:7800` (see below) |
| `medusa export` | Chain-of-custody evidence bundle: zip + SHA-256 manifest (`--with-creds`, `--verify <zip>`) |
| `medusa debrief` | Engagement analytics from audit trails (`-v` for per-engagement detail) |
| `medusa replay` | Step through an engagement timeline (`--list`, `--file`, `--export-md`) |
| `medusa eval` | Replay recorded traffic through the blue detector: precision/recall/F1 + threshold sweep |
| `medusa bat

... (truncated)