```text
╔══════════════════════════════════════════════════════╗
║  ████████╗██╗  ██╗███████╗███████╗███████╗██╗   ██╗║
║  ╚══██╔══╝██║  ██║██╔════╝██╔════╝██╔════╝██║   ██║║
║     ██║   ███████║█████╗  ███████╗█████╗  ██║   ██║║
║     ██║   ██╔══██║██╔══╝  ╚════██║██╔══╝  ██║   ██║║
║     ██║   ██║  ██║███████╗███████║███████╗╚██████╔╝║
║     ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝ ╚═════╝ ║
╚════════════ Attack Path Graph for Pentesters ═══════╝
```

# Theseus

**Your brain can't hold the whole engagement. Theseus can.**

[![Crates.io](https://img.shields.io/crates/v/theseus?style=flat-square&logo=rust)](https://crates.io/crates/theseus)
[![Rust](https://img.shields.io/badge/rust-2021+-ed8225?style=flat-square&logo=rust&logoColor=white)](https://rust-lang.org)
[![License](https://img.shields.io/badge/license-MIT-22C55E?style=flat-square)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS%20·%20Linux-8B5CF6?style=flat-square)]()
[![Build](https://img.shields.io/github/actions/workflow/status/trtyr/theseus/ci.yml?style=flat-square&branch=master)](https://github.com/trtyr/theseus/actions)
[![Downloads](https://img.shields.io/crates/d/theseus?style=flat-square&label=downloads)](https://crates.io/crates/theseus)

[中文文档](README_CN.md)

[🐙 GitHub](https://github.com/trtyr/theseus) · [📦 crates.io](https://crates.io/crates/theseus) · [⚡ Quick Start](#quick-start) · [🏗️ Architecture](#architecture) · [📋 API Reference](#api-reference) · [🤖 Agent](#agent-mode)
---

## What Theseus Is

Theseus is an attack path graph for penetration testing. It is a Rust CLI, a REST API server, and an interactive browser UI that together turn a messy, multi-directional engagement into one living map you can query, inspect, and grow.

Every service you find is a node. Every vulnerability, credential, pivot, or dead end is a node too. How they connect, what led to what, and what still needs attention is all edges and analysis. Instead of stitching together scattered notes, terminal scrollback, and Burp exports after the fact, you build the graph as you work. When the target branches in six directions at once, you still know exactly where you are.

---

## Who It Is For

Penetration testers who run engagements where the attack surface keeps expanding. The kind of test where you find a web service, then an SSRF, then an internal network, then six more hosts, and somewhere around hour four you can't remember which credential you pulled from which box.

If you have ever scrolled through a 4000-line notes file hunting for "that one SQL injection from Tuesday," or realized after a report that two findings you wrote down in separate places combine into a critical attack chain, Theseus is built for you.

---

## 🆚 Why Theseus

| | Dradis | PlexTrac | AttackForge | **Theseus** |
|---|---|---|---|---|
| **Deployment** | Ruby/Rails, heavy | SaaS only | SaaS + on-prem | **✅ Single binary, zero deps** |
| **Graph visualization** | ❌ Flat list | ❌ Flat list | ❌ Flat list | **✅ Interactive Cytoscape.js** |
| **Natural language input** | ❌ | ❌ | ❌ | **✅ `theseus tell/ask`** |
| **AI-powered analysis** | ❌ | ❌ | Limited | **✅ DeepSeek attack path analysis** |
| **Offline-first** | ❌ | ❌ | ❌ | **✅ SQLite, no cloud required** |
| **Real-time sync** | ❌ | ❌ | ❌ | **✅ WebSocket broadcast** |
| **Agent automation** | ❌ | ❌ | ❌ | **✅ LLM agent with tool use** |
| **Free & open source** | ❌ | ❌ | ❌ | **✅ MIT license** |

> **No existing tool turns scattered pentest findings into a live, queryable attack graph that runs locally and thinks with AI.** That is the gap Theseus fills.
---

## Core Capabilities

### Attack Path Graph

Model the entire engagement as typed nodes and directed edges. Twelve built-in node types cover entry points, services, reconnaissance, vulnerabilities, exploitation, privilege escalation, exfiltration, credentials, networks, objectives, process nodes, and user info. Every edge captures a relationship: a scan finding a service, an exploit chaining from one node to the next, a credential granting access to a host.

Custom node types are supported. Pick a name that matches your mental model.

```bash
# Add a service node behind a previous discovery
theseus node add <PID> "Web服务" -t service --after <NID> --edge-label "发现"

# Link a vulnerability to an entry point
theseus node add <PID> "SQL Injection" -t vuln --after <NID> --edge-label "利用"
```

Nodes track position on the canvas, verdict (pending, success, failed, in_progress), evidence status (confirmed, unverified, hypothesis), and rich Markdown content. Credentials attach to nodes and carry type, username, secret, and verification status.

### Natural Language Input

The fastest way to get findings into the graph. Use `theseus tell` with any language, any level of detail, and the system parses your notes into nodes and edges automatically. No need to remember type abbreviations or command flags when you are mid-engagement and typing fast.

```bash
theseus tell <PID> "在 42101 端口发现 SSRF 漏洞，可利用 gopher 协议访问内网"
```

When you are thinking in Chinese, Japanese, Korean, or English, the input language just works.

### Graph Questioning

Ask questions about the current project in plain language. What vulnerabilities haven't been exploited yet? Which credentials are still unverified? Where are the dead ends?

```bash
theseus ask <PID> "哪些漏洞还没被利用？"
theseus ask <PID> "有没有未验证的凭据可以尝试？"
```

### Live Browser Graph

Start the server and open the embedded frontend. Nodes render with color-coded types, corner icons for status, and a collapsible legend. Click any node to open a slide-in panel with full details, Markdown content, attached credentials, and evidence files. Drag, zoom, and rearrange the canvas as the graph grows.

```bash
theseus serve
# Open http://127.0.0.1:3080
```

<!-- TODO: screenshot of the graph UI -->

The graph updates live through WebSocket broadcasts. Add a node from the CLI, and it appears in the browser without reloading.

### Project Dashboard

Get a structured overview of where the engagement stands: high-value targets, unexploited vulnerabilities, active attack directions, dead ends, and isolated nodes that might need reconnection.

```bash
theseus project status <PID>
```

### Graph Analysis with AI

Run deep analysis that finds attack paths through BFS traversal, surfaces unexploited vulnerabilities, identifies dead ends and isolated nodes, and runs health checks (entry isolation, dangling exploits, broken chains, unreachable nodes). Add `--ai` to get tool-level, command-level next-step suggestions from DeepSeek.

```bash
theseus project analysis <PID> --ai
```

### Cross-Project Search

Search every project you have ever created in one command. Matches node labels and body content, returns hits with project context, and supports jump-to from the browser search bar. When you remember a finding but not which engagement it came from, this is the answer.

```bash
theseus search "SQL注入"
```

### Evidence Management

Attach screenshots, scan output, configuration files, or any supporting material directly to nodes. Files are stored with safe UUID-based names on disk, served through the API, and downloadable from the browser panel.

```bash
curl -X POST "http://127.0.0.1:3080/api/v1/projects/<PID>/nodes/<NID>/evidence" \
  -F "file=@screenshot.png"
```

### Timeline View

See the engagement chronologically. Every node appears with its incoming and outgoing edges, ordered by creation time, so you can review how the attack progressed step by step.

```bash
theseus project timeline <PID>
```

### Report Generation

Generate an AI-written penetration test report in Markdown. Full narrative, findings organized by severity, attack chain documentation. Output to stdout or save to a file.

```bash
theseus project report <PID> --output report.md
```

### Bulk Import

Seed a project from JSON. Useful when you have structured scan results or want to migrate existing data into Theseus.

```bash
theseus import <PID> --file data.json
```

### Short ID Resolution

Full UUIDs slow you down. Theseus accepts UUID prefix matching everywhere: the CLI, the API, the browser. Paste the first six characters of any ID and it resolves to the full match.

---

## Quick Start

### Prerequisites

- **Rust** ≥ 1.56 (edition 2021)
- **No C library required** — Theseus is pure Rust with embedded SQLite

### Install From Source

```bash
git clone https://github.com/trtyr/theseus.git
cd theseus
./install.sh
```

This builds the release binary and copies it to `~/.local/bin`. Make sure that directory is on your `PATH`.

### Install From crates.io

Theseus is published on [crates.io](https://crates.io/crates/theseus). Install the latest release with:

```bash
cargo install theseus
```

### Start the Server

```bash
theseus serve
```

The server starts on port 3080. Open `http://127.0.0.1:3080` in your browser. The database file is created automatically at `theseus.db` in the current working directory. Data persists across restarts.

### Create Your First Project

```bash
theseus project create "Example Target"
```

This prints a short project ID. Use it for every subsequent command.

### Add Your First Finding

```bash
theseus tell <PID> "在 42101 端口发现 SSRF 漏洞，可利用 gopher 协议访问内网"
```

Refresh the browser. You now have nodes and edges on the canvas.

---

## Primary Workflow

A typical engagement session flows like this:

```bash
# 1. Create the project at the start of the engagement
theseus project create "Client Name"

# 2. Add entry points as you discover them
theseus node add <PID> "https://target.example.com" -t entry_point --content "登录入口"

# 3. Record services from scan results
theseus node add <PID> "Nginx 1.18" -t service --after <ENTRY_NID> --edge-label "扫描发现"

# 4. Log vulnerabilities as they come
theseus node add <PID> "CVE-2024-xxxx" -t vuln --verdict pending --after <SVC_NID> --edge-label "存在漏洞"

# 5. Capture credentials from any source
theseus credential add <PID> "Admin password" -t password -u admin -s "p@ssw0rd" --source-node <NID>

# 6. Mark exploitation progress
theseus node add <PID> "Webshell" -t exploitation --verdict success --after <VULN_NID> --edge-label "getshell"

# 7. Check what still needs attention
theseus node list <PID> --leaves
theseus ask <PID> "接下来应该攻击哪里？"

# 8. Review the full timeline
theseus project timeline <PID>

# 9. Generate the report when the engagement wraps
theseus project report <PID> --output final-report.md
```

---

## Architecture

Theseus is a three-crate Rust workspace. Every component compiles to a single binary with zero external runtime dependencies beyond the operating system.

```
theseus/
├── theseus-core          Shared types and DTOs
│   └── src/lib.rs        Node, Edge, Credential, NodeType, and all
│                         request/response structs in one file
│
├── theseus-server        axum REST API + embedded frontend
│   ├── src/lib.rs        Route registration, app state, WebSocket broadcast
│   ├── src/db.rs         SQLite wrapper: 5 tables, full CRUD,
│   │                     BFS analysis, health checks
│   ├── src/routes/       Route modules (projects, nodes, edges,
│   │                     credentials, evidence, analysis, report, ...)
│   └── static/           Embedded Cytoscape.js frontend
│       ├── index.html    Compiled into the binary via include_str!
│       ├── css/style.css Dark theme with 30+ CSS variables
│       └── js/           14 vanilla JS modules
│
└── theseus               CLI entry point + server launcher
    └── src/main.rs       Full CLI with clap derive, HTTP client,
                          UUID prefix resolution, table formatting
```

```
                    ┌──────────────────┐
                    │   CLI (theseus)   │
                    │  ┌──────────────┐ │
                    │  │ serve command │─┼── starts server in-process
                    │  │ HTTP client   │─┼── talks to server
                    │  └──────────────┘ │
                    └────────┬─────────┘
                             │ HTTP + JSON
                    ┌────────▼─────────┐
                    │  axum REST API    │
                    │  ┌──────────────┐ │
                    │  │ SQLite store  │ │
                    │  │ WebSocket tx  │ │
                    │  │ DeepSeek AI   │ │  ← optional API key
                    │  │ Static files  │ │
                    │  └──────────────┘ │
                    └────────┬─────────┘
                             │ WebSocket
                    ┌────────▼─────────┐
                    │  Browser (Cytoscape.js)
                    │  Live graph + panels
                    └──────────────────┘
```

**Stack**: axum 0.7, rusqlite (SQLite in WAL mode), clap 4, Cytoscape.js with dagre layout, optional DeepSeek API.

---

## Configuration

All core graph and CLI features work without any API key.

AI features (natural language `tell`/`ask`, duplicate detection, AI analysis, report generation) require a DeepSeek API key. Pass it when starting the server:

```bash
theseus serve --api-key sk-your-key
```

Or store it in a config file. Theseus checks two locations, in order:

1. `./theseus.toml` (project-local, next to the database)
2. `~/.config/theseus/config.toml` (global)

```toml
deepseek_api_key = "sk-your-key"
```

---

## Node Types

| Type | Description |
|------|-------------|
| `entry_point` | Initial access: login pages, exposed services, physical access |
| `service` | Running services: web servers, databases, APIs |
| `reconnaissance` | Recon findings: open ports, subdomains, directory listings |
| `vulnerability` | Discovered vulnerabilities or weaknesses |
| `exploitation` | Successful exploitation steps |
| `privilege_escalation` | Privilege escalation paths or outcomes |
| `exfiltration` | Data exfiltration methods or targets |
| `credential` | Discovered credentials (linked via credential records too) |
| `network` | Network segments, internal hosts, subnets |
| `objective` | Campaign objectives or high-value targets |
| `process` | Workflow steps, methodology notes |
| `user_info` | User accounts, roles, permissions |
| `custom` | Any type name following `[a-z][a-z0-9_]{0,29}` |

Nodes accept `--verdict` (pending, success, failed, in_progress) and `--evidence` (confirmed, unverified, hypothesis) flags. Verdict and evidence are reflected in the graph UI as color and icon hints.

---

## Credential Tracking

Credentials in Theseus are first-class objects. Each one tracks its type (password, SSH key, AK/SK pair, or token), username, secret value, associated node, and verification status (unverified, verified, expired). The browser panel toggles secret visibility with a click.

```bash
theseus credential add <PID> "Admin password" -t password -u admin -s "p@ssw0rd" --source-node <NID>
theseus credential list <PID>
```

---

## API

Every operation available in the CLI is also available through the REST API. All responses wrap data in a standard envelope:

```json
{ "success": true, "data": { ... }, "error": null }
```

Key endpoints:

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/api/v1/projects` | Create project |
| `GET` | `/api/v1/projects` | List projects |
| `GET` | `/api/v1/projects/:pid` | Get project |
| `POST` | `/api/v1/projects/:pid/nodes` | Create node |
| `GET` | `/api/v1/projects/:pid/nodes` | List nodes (with optional `?node_type=`, `?verdict=`, `?evidence=` filters) |
| `PATCH` | `/api/v1/projects/:pid/nodes/:nid` | Update node |
| `DELETE` | `/api/v1/projects/:pid/nodes/:nid` | Delete node |
| `POST` | `/api/v1/projects/:pid/edges` | Create edge |
| `GET` | `/api/v1/projects/:pid/analysis` | Run analysis (add `?ai=true` for AI suggestions) |
| `GET` | `/api/v1/projects/:pid/timeline` | Chronological timeline |
| `GET` | `/api/v1/projects/:pid/daily-report?date=` | Daily Markdown report |
| `GET` | `/api/v1/projects/:pid/report` | AI-generated full report |
| `POST` | `/api/v1/projects/:pid/import` | Bulk JSON import |
| `GET` | `/api/v1/search?q=` | Cross-project search |
| `POST` | `/api/v1/projects/:pid/tell` | Natural language node creation |
| `POST` | `/api/v1/projects/:pid/ask` | Natural language graph query |
| `WS` | `/ws` | WebSocket for live graph updates |

Short ID matching works on all `:pid`, `:nid`, and `:eid` path segments. Pass a full UUID or any unique prefix of at least 6 characters.

---

## Use Cases

**Solo pentester, one engagement.** Start the server locally, use the CLI in your terminal while the browser graph sits on a second monitor. Add nodes as you work. At the end of the week, export a report.

**Team on a shared target.** Run the server on a reachable host. Each team member hits the same API with their own CLI, seeing updates in real time through WebSocket broadcasts. The graph becomes the team's shared mental model.

**Long-running red team.** A multi-week engagement generates a lot of state. The timeline view, cross-project search, and AI analysis keep accumulated information accessible and actionable months later.

**Post-engagement review.** Load the project, walk the timeline, run analysis. Identify what was found, what was exploited, and what attack chains were missed. Use the graph as a debrief tool.

---

## Reporting

Theseus generates reports in Markdown format. The report endpoint compiles node content, edge relationships, verdicts, evidence status, and AI-generated narrative into a single document ready for delivery.

```bash
# Print to stdout
theseus project report <PID>

# Save to file
theseus project report <PID> --output client-report.md
```

Daily reports are also available, filtered to nodes created on a specific date in CST timezone:

```bash
curl "http://127.0.0.1:3080/api/v1/projects/<PID>/daily-report?date=2026-05-20"
```

---

## Data Safety

The database is a single SQLite file (`theseus.db`) in WAL mode with foreign keys enabled. Back it up by copying the file. Evidence files live under `data/<PID>/evidence/<NID>/` on disk. Deleting the server or the database does not automatically clean up evidence files, keep that in mind when archiving engagements.

---

---

⭐ Found this useful? Give it a star on [GitHub](https://github.com/trtyr/theseus).

## License

MIT

---

*Less archaeology. More attack path.*
