```text
╔══════════════════════════════════════════════════════╗
║  ████████╗██╗  ██╗███████╗███████╗███████╗██╗   ██╗║
║  ╚══██╔══╝██║  ██║██╔════╝██╔════╝██╔════╝██║   ██║║
║     ██║   ███████║█████╗  ███████╗█████╗  ██║   ██║║
║     ██║   ██╔══██║██╔══╝  ╚════██║██╔══╝  ██║   ██║║
║     ██║   ██║  ██║███████╗███████║███████╗╚██████╔╝║
║     ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝ ╚═════╝ ║
╚══════ 渗透测试攻击路径图 ═══════════════════════════╝
```

# Theseus

**大脑记不住整个渗透测试过程，Theseus 记得住。**

[![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)

[English](README.md)

---

## Theseus 是什么

Theseus 是一个渗透测试攻击路径图。它由 Rust CLI、REST API 服务器和交互式浏览器前端三部分组成，把一个多方向推进、信息分散的渗透项目变成一张活的、可查询、可审视、持续生长的攻击图。

你发现的每一个服务都是节点。每一个漏洞、凭据、横向跳板、死胡同，也都是节点。它们之间如何连接、谁引出了谁、还有哪些方向没探索，全由边和分析引擎来呈现。你不再需要事后拼凑零散的笔记、终端滚动回放和 Burp 导出文件；你一边打一边画图。当目标从六个方向同时延伸时，你仍然清楚自己在哪里。

---

## 面向谁

面向那些攻击面不断膨胀的渗透测试工程师。你会先发现一个 web 服务，接着是 SSRF，然后是内网，然后是六台新主机，打到第四个小时你已不记得哪个凭据是从哪台机器上扒出来的。

如果你曾在一个四千行的笔记文件里翻找"周二发现的那个 SQL 注入"，或者在交报告时才意识到两个分散记录的漏洞能串成一条高危攻击链，Theseus 就是为你做的。

---

## 核心能力

### 攻击路径图

用带类型的节点和有向边来建模整个渗透过程。十二种内置节点类型覆盖入口点、服务、信息收集、漏洞、漏洞利用、提权、数据窃取、凭据、网络、目标、过程节点和用户信息。每条边捕获一种关系：一次扫描发现一个服务，一次利用链从一个节点打到下一个节点，一个凭据授予了对某台主机的访问权限。

支持自定义节点类型，名字按你的思路来起。

```bash
# 在已有发现后面添加一个服务节点
theseus node add <PID> "Web服务" -t service --after <NID> --edge-label "发现"

# 将漏洞链接到入口点
theseus node add <PID> "SQL Injection" -t vuln --after <NID> --edge-label "利用"
```

节点携带画布位置、判定状态（pending、success、failed、in_progress）、证据状态（confirmed、unverified、hypothesis）和富文本 Markdown 内容。凭据是独立实体，挂载到节点上，记录类型、用户名、密码和验证状态。

### 自然语言输入

把发现快速录入图的最快方式。用 `theseus tell`，无论什么语言、什么粒度，系统自动将你的笔记解析成节点和边。在渗透中快速敲命令时，不用回忆类型缩写或命令参数。

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

你用中文、日文、韩文、英文思考时，输入语言自动适配。

### 向图提问

用自然语言向当前项目提问。哪些漏洞还没被利用？哪些凭据还没验证？死胡同在哪？

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

### 实时浏览器图

启动服务器，打开嵌入式前端。节点按类型着色渲染，角落图标显示状态，图例可折叠。点击任意节点弹出侧面板，展示完整详情、Markdown 内容、关联凭据和证据文件。随着图增长，自由拖拽、缩放、重排画布。

```bash
theseus serve
# 浏览器打开 http://127.0.0.1:3080
```

<!-- TODO: 图界面截图 -->

图通过 WebSocket 广播实时更新。从 CLI 添加节点，浏览器不作刷新就能出现。

### 项目仪表盘

获取渗透项目的全局视图：高价值目标、未利用漏洞、活跃攻击方向、死路和可能需要重连的孤立节点。

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

### AI 图分析

运行深度分析：BFS 遍历发现攻击路径，列出未利用漏洞，识别死胡同和孤立节点，执行健康检查（入口点隔离、悬空利用链、断裂攻击链、不可达节点）。加上 `--ai` 参数获取 DeepSeek 提供的工具级、命令级下一步建议。

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

### 跨项目搜索

一条命令搜索你创建过的所有项目。匹配节点标签和正文内容，返回带项目上下文的命中结果，浏览器搜索栏支持一键跳转。你记得某个发现但不记得是哪个项目，这就是答案。

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

### 证据管理

将截图、扫描输出、配置文件或其他支撑材料直接挂载到节点。文件以 UUID 安全命名存储在磁盘上，通过 API 提供服务，浏览器面板可直接下载。

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

### 时间线视图

按时间顺序浏览渗透过程。每个节点显示其入边和出边，按创建时间排列，方便你回顾攻击如何一步步推进。

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

### 报告生成

生成 AI 撰写的 Markdown 渗透测试报告。完整叙述、按严重程度组织的发现、攻击链文档。输出到标准输出或保存为文件。

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

### 批量导入

从 JSON 种子数据快速初始化项目。适用于你有结构化扫描结果或想把已有数据迁入 Theseus 的场景。

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

### 短 ID 解析

完整 UUID 拖慢你的速度。Theseus 在所有地方支持 UUID 前缀匹配：CLI、API、浏览器。输入任何 ID 的前六位字符，自动解析到完整匹配。

---

## 快速开始

### 前置条件

Rust 1.75 或更高版本。SQLite 内嵌，不需要额外数据库。

### 从源码安装

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

这会构建 release 二进制文件并复制到 `~/.local/bin`。确保该目录在你的 `PATH` 里。

### 从 crates.io 安装

Theseus 发布在 [crates.io](https://crates.io/crates/theseus) 上。用 cargo 安装最新版本：

```bash
cargo install theseus
```

### 启动服务器

```bash
theseus serve
```

服务器启动在 3080 端口。浏览器打开 `http://127.0.0.1:3080`。数据库文件 `theseus.db` 在当前工作目录自动创建。数据在重启后持久保留。

### 创建你的第一个项目

```bash
theseus project create "示例目标"
```

这会输出一个短项目 ID。后续所有命令都用这个 ID。

### 添加你的第一个发现

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

刷新浏览器，画布上就会出现节点和边。

---

## 主要工作流

一个典型渗透项目的工作流程如下：

```bash
# 1. 渗透开始时创建项目
theseus project create "客户名称"

# 2. 发现入口点时添加
theseus node add <PID> "https://target.example.com" -t entry_point --content "登录入口"

# 3. 记录扫描结果中的服务
theseus node add <PID> "Nginx 1.18" -t service --after <ENTRY_NID> --edge-label "扫描发现"

# 4. 记录发现的漏洞
theseus node add <PID> "CVE-2024-xxxx" -t vuln --verdict pending --after <SVC_NID> --edge-label "存在漏洞"

# 5. 捕获凭据
theseus credential add <PID> "Admin password" -t password -u admin -s "p@ssw0rd" --source-node <NID>

# 6. 标记利用进展
theseus node add <PID> "Webshell" -t exploitation --verdict success --after <VULN_NID> --edge-label "getshell"

# 7. 检查还有哪些方向需要关注
theseus node list <PID> --leaves
theseus ask <PID> "接下来应该攻击哪里？"

# 8. 回顾完整时间线
theseus project timeline <PID>

# 9. 渗透结束时生成报告
theseus project report <PID> --output final-report.md
```

---

## 架构

Theseus 是一个三 crate 的 Rust workspace。所有组件编译为单个二进制文件，除了操作系统之外零外部运行时依赖。

```
theseus/
├── theseus-core          共享类型和 DTO
│   └── src/lib.rs        Node、Edge、Credential、NodeType 以及所有
│                         请求/响应结构体，单文件
│
├── theseus-server        axum REST API + 嵌入式前端
│   ├── src/lib.rs        路由注册、应用状态、WebSocket 广播
│   ├── src/db.rs         SQLite 封装：5 张表、完整 CRUD、
│   │                     BFS 分析、健康检查
│   ├── src/routes/       路由模块（projects、nodes、edges、
│   │                     credentials、evidence、analysis、report 等）
│   └── static/           嵌入式 Cytoscape.js 前端
│       ├── index.html    通过 include_str! 编译进二进制
│       ├── css/style.css 深色主题，30+ CSS 变量
│       └── js/           14 个原生 JS 模块
│
└── theseus               CLI 入口 + 服务器启动器
    └── src/main.rs       完整 CLI：clap derive、HTTP 客户端、
                          UUID 前缀解析、表格格式化
```

```
                    ┌──────────────────┐
                    │   CLI (theseus)   │
                    │  ┌──────────────┐ │
                    │  │ serve 命令    │─┼── 进程内启动服务器
                    │  │ HTTP 客户端   │─┼── 与服务器通信
                    │  └──────────────┘ │
                    └────────┬─────────┘
                             │ HTTP + JSON
                    ┌────────▼─────────┐
                    │  axum REST API    │
                    │  ┌──────────────┐ │
                    │  │ SQLite 存储   │ │
                    │  │ WebSocket tx  │ │
                    │  │ DeepSeek AI   │ │  ← 可选 API key
                    │  │ 静态文件      │ │
                    │  └──────────────┘ │
                    └────────┬─────────┘
                             │ WebSocket
                    ┌────────▼─────────┐
                    │  浏览器 (Cytoscape.js)
                    │  实时图 + 面板
                    └──────────────────┘
```

**技术栈**：axum 0.7、rusqlite（SQLite WAL 模式）、clap 4、Cytoscape.js + dagre 布局、可选 DeepSeek API。

---

## 配置

所有核心图和 CLI 功能无需任何 API key 即可使用。

AI 功能（自然语言 `tell`/`ask`、重复检测、AI 分析、报告生成）需要 DeepSeek API key。启动服务器时传入：

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

或存储在配置文件中。Theseus 按顺序检查两个位置：

1. `./theseus.toml`（项目本地，与数据库同目录）
2. `~/.config/theseus/config.toml`（全局）

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

---

## 节点类型

| 类型 | 说明 |
|------|------|
| `entry_point` | 初始访问点：登录页面、暴露服务、物理访问 |
| `service` | 运行中的服务：Web 服务器、数据库、API |
| `reconnaissance` | 侦察发现：开放端口、子域名、目录列表 |
| `vulnerability` | 发现的漏洞或弱点 |
| `exploitation` | 成功利用步骤 |
| `privilege_escalation` | 提权路径或结果 |
| `exfiltration` | 数据窃取方法或目标 |
| `credential` | 发现的凭据（也通过凭据记录关联） |
| `network` | 网络段、内网主机、子网 |
| `objective` | 行动目标或高价值目标 |
| `process` | 工作流步骤、方法论笔记 |
| `user_info` | 用户账户、角色、权限 |
| `custom` | 任意符合 `[a-z][a-z0-9_]{0,29}` 的类型名 |

节点接受 `--verdict`（pending、success、failed、in_progress）和 `--evidence`（confirmed、unverified、hypothesis）参数。判定和证据状态在图中以颜色和图标体现。

---

## 凭据追踪

Theseus 中凭据是一等实体。每条凭据记录类型（password、SSH key、AK/SK 对、token）、用户名、密码值、关联节点和验证状态（unverified、verified、expired）。浏览器面板支持一键切换密码可见性。

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

---

## API

CLI 中的每一个操作都可以通过 REST API 调用。所有响应使用统一的信封格式：

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

核心端点：

| 方法 | 路径 | 用途 |
|------|------|------|
| `POST` | `/api/v1/projects` | 创建项目 |
| `GET` | `/api/v1/projects` | 列出项目 |
| `GET` | `/api/v1/projects/:pid` | 获取项目 |
| `POST` | `/api/v1/projects/:pid/nodes` | 创建节点 |
| `GET` | `/api/v1/projects/:pid/nodes` | 列出节点（可选 `?node_type=`、`?verdict=`、`?evidence=` 过滤） |
| `PATCH` | `/api/v1/projects/:pid/nodes/:nid` | 更新节点 |
| `DELETE` | `/api/v1/projects/:pid/nodes/:nid` | 删除节点 |
| `POST` | `/api/v1/projects/:pid/edges` | 创建边 |
| `GET` | `/api/v1/projects/:pid/analysis` | 运行分析（加 `?ai=true` 获取 AI 建议） |
| `GET` | `/api/v1/projects/:pid/timeline` | 按时间顺序的时间线 |
| `GET` | `/api/v1/projects/:pid/daily-report?date=` | 每日 Markdown 报告 |
| `GET` | `/api/v1/projects/:pid/report` | AI 生成的完整报告 |
| `POST` | `/api/v1/projects/:pid/import` | 批量 JSON 导入 |
| `GET` | `/api/v1/search?q=` | 跨项目搜索 |
| `POST` | `/api/v1/projects/:pid/tell` | 自然语言创建节点 |
| `POST` | `/api/v1/projects/:pid/ask` | 自然语言向图提问 |
| `WS` | `/ws` | WebSocket 实时图更新 |

短 ID 匹配在所有 `:pid`、`:nid`、`:eid` 路径段中有效。传入完整 UUID 或至少 6 位的唯一前缀即可。

---

## 使用场景

**单人渗透，一个项目。** 本地启动服务器，终端用 CLI 操作，浏览器图放在第二块屏幕上。边打边加节点。一周后导出报告。

**团队协同，共享目标。** 在一台可达的主机上启动服务器。每个队员用自己的 CLI 访问同一个 API，通过 WebSocket 广播看到实时更新。图成为团队的共享思维模型。

**长期红队行动。** 持续数周的渗透积累大量状态信息。时间线视图、跨项目搜索和 AI 分析让积累的信息在数月后依然可访问、可操作。

**行动复盘。** 加载项目，走一遍时间线，运行分析。识别发现了什么、利用了哪些、以及漏掉了什么攻击链。把图当作复盘工具。

---

## 报告

Theseus 生成 Markdown 格式的报告。报告端点将节点内容、边关系、判定、证据状态和 AI 生成的叙述整合为一份可直接交付的文档。

```bash
# 输出到标准输出
theseus project report <PID>

# 保存到文件
theseus project report <PID> --output client-report.md
```

也支持按 CST 时区筛选指定日期的每日报告：

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

---

## 数据安全

数据库是单个 SQLite 文件（`theseus.db`），WAL 模式，启用外键约束。直接复制文件即可备份。证据文件存储在 `data/<PID>/evidence/<NID>/` 磁盘目录下。删除服务器或数据库不会自动清理证据文件，归档项目时请注意这一点。

---

## 许可证

MIT

---

*少花时间考古，多花时间攻击。*
