# Theseus - Attack Path Graph for Penetration Testing

Structured external memory for penetration testing, built as a Rust CLI, API server, and browser graph UI.

[![crates.io](https://img.shields.io/crates/v/theseus.svg)](https://crates.io/crates/theseus)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#license)

## What It Does

Theseus helps penetration testers keep findings, hypotheses, pivots, and next steps in one attack path graph. Each discovery becomes a node, each relationship becomes an edge, and the graph becomes a structured external memory for the engagement. You can add data manually, use natural language to turn notes into nodes and edges, or ask questions about the current graph. Theseus also analyzes the graph to surface attack paths, dead ends, unexploited vulnerabilities, and suggested next moves.

## Key Features

- Natural language input with `theseus tell`: describe findings in plain language and let AI create nodes and edges.
- Natural language query with `theseus ask`: ask questions about the current attack graph.
- Graph analysis: attack paths, graph health checks, unexploited vulnerabilities, dead ends, and next-step suggestions.
- AI report generation for Markdown project reports.
- Node dedup detection before creating semantically similar findings.
- Cross-project search across node labels and content.
- CLI plus embedded web UI powered by Cytoscape.js.
- Short ID support through UUID prefix matching.

## Quick Start

```bash
cargo install theseus
theseus serve
```

Open `http://127.0.0.1:3080` in your browser.

## Usage Examples

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

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

theseus ask <PID> "哪些漏洞还没被利用？"

theseus node add <PID> "Web服务" -t service --after <NID> --edge-label "发现"

theseus node list <PID> --leaves

theseus project status <PID>

theseus project analysis <PID> --ai

theseus search "SQL注入"
```

## Architecture

Theseus is a three-crate Rust workspace. `theseus-core` contains shared DTOs and graph types, `theseus-server` provides the axum REST API, SQLite storage, WebSocket updates, AI integration, and embedded web frontend, and `theseus` is the main CLI and server entry point. Data is stored in SQLite through `rusqlite`, while the browser UI renders the attack graph with Cytoscape.js.

## Configuration

Core graph and CLI features work without an AI key. AI features, including `tell`, `ask`, duplicate detection, AI analysis, and report generation, require a DeepSeek API key.

Configure the key in any of these ways:

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

```toml
# ./theseus.toml or ~/.config/theseus/config.toml
deepseek_api_key = "sk-your-key"
```

## License

MIT
