not-narleeek/pi-caido
GitHub: not-narleeek/pi-caido
将 Caido 的 HTTP 代理、Repeater 和 HTTPQL 搜索能力封装为 pi agent 工具，使 AI 代理在渗透测试和 CTF 场景下能统一捕获、检索和重放所有 HTTP 流量。
Stars: 0 | Forks: 0
# pi-caido
`pi-caido` 是一个 [pi 包](https://pi.dev/packages)，它将 Caido 暴露为六个一等 agent 工具，外加一个 `/caido` 命令和一个实时状态页脚。它封装了一个小巧、**无依赖** 的 Python 自动化客户端，直接与 Caido 的 GraphQL API 通信。无需 Burp 扩展，无需浏览器自动化，无需额外的 daemon —— 只需要一个 Python 文件和一个 TypeScript 扩展。
## 目录
- [功能简介](#what-it-does)
- [环境要求](#requirements)
- [安装](#install)
- [首次运行设置](#first-run-setup)
- [快速开始](#quick-start)
- [架构](#architecture)
- [工作原理](#how-it-works)
- [配置](#configuration)
- [HTTPQL 快速参考](#httpql-quick-reference)
- [安全说明](#security-notes)
- [故障排除](#troubleshooting)
- [许可证](#license)
## 功能简介
agent 发出的每一个 HTTP 请求都可以路由经过 Caido，并且随后会：
- 被 Caido 的 HTTP 历史记录**捕获**（可在 GUI 中实时查看），
- 可使用 Caido 的 HTTPQL 过滤语言进行**搜索**，
- 可与其余流量一起**重放**和导出。
具体而言，该包为 agent 提供了以下工具：
| 工具 | agent 用途 |
|------|----------------------------|
| `caido_request` | 通过 Caido 的 Repeater 发送 HTTP 请求，并返回状态、headers 和 body。对于手动构造请求，优先使用此工具而不是 `curl`。 |
| `caido_search` | 使用 HTTPQL 过滤捕获的历史记录，例如 `resp.raw.cont:"flag{"`。 |
| `caido_get_request` | 根据 id 导出完整的原始请求/响应对。 |
| `caido_history` | 列出最近捕获的请求。 |
| `caido_proxy` | 打印代理 URL + CA 证书路径，以及用于将 `curl`、`httpx`、`ffuf`、`feroxbuster` 等工具路由到 Caido 的 `http_proxy` / `SSL_CERT_FILE` 环境变量配置。 |
| `caido_scope` | 列出 scope 或添加新的允许/拒绝 host 通配符。 |
以及一个供您使用的 `/caido` 命令：
```
/caido status (instance · auth · project · request count)
/caido start|stop launch / kill a headless Caido instance
/caido proxy proxy URL + CA cert + export lines
/caido httpql HTTPQL cheatsheet
/caido send -u URL -m POST … fire a request through the Repeater
/caido search 'resp.code.eq:500'
/caido get full raw request+response
/caido history
```
实时的页脚 (🌐 `caido · · 42 reqs`) 可以让您一眼查看就绪状态。
## 环境要求
| 组件 | 版本 | 说明 |
|-----------|---------|-------|
| **pi** | 任意近期版本 | 加载此包的 agent —— `npm i -g @earendil-works/pi-coding-agent` |
| **Caido** | 2024.x+ | 桌面应用程序 (GUI) 或 `caido-cli`。从 安装 |
| **Python** | 3.8+ | **仅使用标准库** —— 无需 `pip install`。`python3` 必须在 `PATH` 中 |
| **Node** | 18+ | 用于 TypeScript 扩展 |
Python 客户端仅使用标准库 (`urllib`, `json`, `base64`, `socket`, `subprocess`, `argparse`)。在 Python 端无需进行任何安装。
## 安装
从三种来源中**选择一种**。默认情况下，`pi install` 会写入用户设置 (`~/.pi/agent/settings.json`)；如果需要写入项目本地设置，请添加 `-l`。
### 1. 从 git 安装（推荐 —— 始终最新）
```
pi install git:github.com/not-narleeek/pi-caido
```
如果需要保证可复现性，可以固定 tag/commit：
```
pi install git:github.com/not-narleeek/pi-caido@v0.1.0
```
### 2. 从 npm 安装（一旦发布）
```
pi install npm:pi-caido
```
### 3. 从本地克隆安装（用于开发）
```
git clone https://github.com/not-narleeek/pi-caido
cd pi-caido
npm install # installs TypeScript peer deps for local type-checking
pi install . # or: pi install ./pi-caido (absolute or relative path)
```
验证是否已加载：
```
pi list # pi-caido should appear under packages
/caido status # inside a pi session
```
在不将其提交到设置的情况下进行尝试：
```
pi -e git:github.com/not-narleeek/pi-caido # ephemeral, current run only
```
## 首次运行设置
Caido 的数据操作（历史记录、搜索、发送）需要一个**激活的项目**，并且只有真实登录的用户才能创建项目。请执行一次以下操作：
1. 打开 **Caido GUI**，使用您的 **免费 Caido 云账号**登录，并创建/打开一个项目。（这会在磁盘上初始化一个用户和项目。）
2. *可选但推荐：* 在 Caido → **Settings → API** 中，创建一个 **API token** 并将其导出：
export CAIDO_API_TOKEN=cai_xxx
设置了 token 后，首次使用时会自动启动一个 headless 实例，您将永远不需要运行 GUI。
从现在开始，agent 可以自动发现您正在运行的 Caido 实例（或启动一个 headless 实例），一切都能“正常运行”。
## 快速开始
在 pi session 内部（您的代码仓库、CTF 目录等任何地方）：
```
# 让 agent 发送请求并查看它如何到达 Caido
> send a GET to http://challenge.ctf.io:8080/ and look for anything juicy
# agent 使用 caido_request（或 caido_proxy + bash 工具）代替普通的 curl。
```
将扫描器路由经过 Caido，以便捕获其流量：
```
> point ffuf at https://target.htb/ and brute /usr/share/wordlists/dirb/common.txt
# agent 调用 caido_proxy，然后运行：
# export http_proxy=http://127.0.0.1:8080 https_proxy=http://127.0.0.1:8080
# export REQUESTS_CA_BUNDLE=/home/.../.pi/caido/ca.crt SSL_CERT_FILE=...
# ffuf -x http://127.0.0.1:8080 -u https://target.htb/FUZZ -w common.txt
# ...并且每次命中都可以通过 caido_search 进行搜索。
```
在捕获的内容中查找 flag：
```
> search captured traffic for the flag format
# agent 运行 caido_search 'resp.raw.cont:"flag{"' 和 caido_get_request 。
```
页脚会实时更新：🌐 `caido · ctf · 318 reqs`。
## 架构
分为三层，没有隐藏的活动部件：
```
┌──────────────────────────────────────────────────────────────────┐
│ pi (the agent) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ extensions/caido.ts ←── this package (TypeScript) │ │
│ │ • 6 tools: caido_request · caido_search · caido_get_* │ │
│ │ caido_history · caido_proxy · caido_scope │ │
│ │ • /caido command • live status footer │ │
│ └───────────────────┬────────────────────────────────────────┘ │
│ │ spawnSync("python3", [scripts/caido.py …])│
│ ┌───────────────────▼────────────────────────────────────────┐ │
│ │ scripts/caido.py ←── this package (stdlib Python) │ │
│ │ • discover / launch headless instance │ │
│ │ • guest-or-API-token auth │ │
│ │ • ensure an active project │ │
│ │ • send via Repeater, search HTTPQL, export, scope, … │ │
│ └───────────────────┬────────────────────────────────────────┘ │
└───────────────────────┼────────────────────────────────────────────┘
│ HTTP + GraphQL (/graphql, /ca.crt)
┌───────────────────────▼────────────────────────────────────────────┐
│ Caido instance (GUI or headless) │
│ Repeater · HTTP history · Scope · Findings · Proxy (e.g. :8080) │
└────────────────────────────────┬───────────────────────────────────┘
│ proxy (http_proxy / https_proxy)
┌─────────▼─────────┐
│ target web app │
└────────────────────┘
```
**为什么要这样拆分？**
- **`caido.ts`** 是 *agent 接口*：它定义了工具（名称、schema、prompt 指导、渲染）、`/caido` 命令和页脚。它**不包含**任何网络逻辑 —— 它只是调用 Python 客户端并格式化 JSON。这使得 TypeScript 层非常轻量，并让 pi 自己的工具 pipeline 来处理渲染、截断和流式传输。
- **`caido.py`** 是 *Caido 接口*：它负责实例生命周期、身份验证、项目引导以及所有的 GraphQL 调用。作为纯标准库 Python，它可以在任何存在 `python3` 的地方运行，**零安装步骤**，您也可以将其作为 CLI 独立使用（见下文）。
- **Caido 实例**是*事实来源*：所有捕获的流量都存储在那里，因此 agent 和盯着 GUI 的人看到的内容始终是一致的。
### 文件布局
```
pi-caido/
├── extensions/
│ └── caido.ts # pi extension: tools, /caido command, footer
├── scripts/
│ └── caido.py # dependency-free GraphQL automation client (+ CLI)
├── docs/
│ ├── ARCHITECTURE.md # deeper dive into lifecycle & data flow
│ └── HTTPQL.md # HTTPQL reference
├── package.json # pi manifest (pi.extensions) + npm metadata
├── tsconfig.json # local type-checking only (pi compiles the extension)
├── README.md
├── CHANGELOG.md
└── LICENSE
```
## 工作原理
### 1. 实例发现与自动启动
当工具运行时，扩展程序首先确保 Caido 实例是可以访问的。`caido.py` 会按顺序尝试：
1. 通过探测本地端口 (`8080, 8180, 8443, 8085, …`) 来**发现**正在运行的实例。如果您的 GUI/CLI 已经启动，它将被重用。
2. **重新附加**到它之前启动的 headless 实例（记录在 `~/.pi/caido/instance.json` 中）。
3. **启动** headless 实例，命令为 `caido-cli --invisible --no-open --allow-guests --listen 127.0.0.1:`，并等待 `/graphql` 响应。该进程是脱离的 (`setsid`)，因此即使 agent 退出，它也能继续运行。
### 2. 身份验证
身份验证优先级（第一个非空的生效）：
1. **`$CAIDO_API_TOKEN`**（或 `~/.pi/caido/token`）→ 拥有完全访问权限，可以创建项目。
2. **访客登录** (`loginAsGuest`) → 只能使用*已存在*的项目，不能创建项目。这就是为什么需要存在一次性 GUI 登录的原因。
如果 API token 无效/过期，会自动回退到访客身份。
### 3. 项目引导
数据调用需要一个*当前项目*。客户端会：
1. 读取 `currentProject`。如果已设置，则完成。
2. 否则列出项目；如果存在任何项目，则选择第一个并将其固定为 `selectOnStart`。
3. 如果不存在任何项目，则尝试执行 `createProject`（仅对真实用户/API token 成功）。如果失败，它将返回一条清晰的“请打开一次 GUI”的消息，而不是崩溃。
### 4. 发送请求 (`caido_request`)
请求通过 Caido 的 **Repeater** 发送，因此它会像其他任何流量一样记录在历史记录中：
1. 解析 URL → `{host, port, isTLS, SNI}` + path。
2. 构建一个原始的 HTTP/1.1 字节 blob (`_build_raw`)，并根据需要添加 `Host`/`Content-Length`。
3. 使用原始请求作为种子执行 `createReplaySession`。
4. 执行 `startReplayTask` 来实际触发它 (异步)。
5. **轮询**重放条目，直到请求 id 准备就绪（或者出错 / 在约 6 秒时超时）。
6. 根据 id 获取完整的请求+响应，并解码 base64 payload。
然后扩展程序会渲染状态/headers/body，进行截断以保持输出较小，同时将完整数据保留在 Caido 中，以便 `caido_get_request` 检索。
### 5. 搜索历史记录 (`caido_search`)
`caido_search` 会将您的 [HTTPQL](docs/HTTPQL.md) 表达式直接传递给 Caido 的 `requests(filter:)` GraphQL 字段，并返回 `id · status · method host path · size` 行。完整的 body 通过 `caido_get_request ` 返回。
### 6. 路由扫描器 (`caido_proxy`)
`caido_proxy` 将 Caido 的 CA 证书 (`/ca.crt`) 获取到磁盘并打印：
```
export http_proxy=http://127.0.0.1:8080 https_proxy=http://127.0.0.1:8080
export REQUESTS_CA_BUNDLE=/home/.../.pi/caido/ca.crt SSL_CERT_FILE=/home/.../.pi/caido/ca.crt
```
agent 会在调用 `curl`/`httpx`/`ffuf`/`feroxbuster` 之前，在 `bash` 工具中应用这些配置，因此这些工具发出的每一个请求都会流经 Caido 并变得可搜索。
### 独立 CLI
`scripts/caido.py` 也是一个可独立使用的 CLI —— 在脚本、CI 或 pi 外部非常方便：
```
python3 scripts/caido.py status
python3 scripts/caido.py send -m POST -u http://localhost:8000/api -H 'Content-Type:application/json' -d '{"k":1}'
python3 scripts/caido.py search 'resp.raw.cont:"flag{"' --limit 5
python3 scripts/caido.py get
python3 scripts/caido.py proxy
python3 scripts/caido.py httpql-help
```
每个子命令都支持 `--json` 以用于机器输出。
## 配置
所有配置均为可选。合理的默认设置意味着大多数配置下需要零配置。
| 环境变量 | 默认值 | 用途 |
|---------|---------|---------|
| `CAIDO_API_TOKEN` | *(未设置 → 使用访客身份)* | Caido API token (完全访问权限；启用自动项目创建 + 仅 headless 运行)。 |
| `CAIDO_PY` | *(内置)* | 覆盖 `caido.py` 的路径 (开发/调试)。依次回退到内置脚本，然后是 `~/.pi/scripts/caido.py`。 |
| `CAIDO_STATE_DIR` | `~/.pi/caido` | 写入实例元数据、CA 证书和 `instance.log` 的位置。 |
状态文件（位于 `$CAIDO_STATE_DIR` 下）：
```
instance.json # pid + port + base_url of a headless instance we started
token # API token if you'd rather store it than export the env var
ca.crt # Caido CA cert, fetched on demand
instance.log # headless instance stdout/stderr
```
## HTTPQL 快速参考
HTTPQL 是 Caido 用于 HTTP 历史记录的过滤语言。形式为：`namespace.field.operator:value`。
```
req.method.eq:"POST"
resp.code.eq:200
resp.raw.cont:"flag{"
req.host.eq:"challenge.ctf.io"
req.path.cont:"/admin" or req.path.regex:/^\/api\/v[0-9]+/
resp.code.gt:400 and resp.raw.cont:"stack"
```
完整参考：[docs/HTTPQL.md](docs/HTTPQL.md)，或者在 pi 内部运行 `/caido httpql`。
## 安全说明
- **以您的权限运行。** 与所有 pi 包一样，此扩展程序会执行代码 (`python3`，并间接执行 `caido-cli`)。在安装前请检查源代码 —— 只有两个文件 (`extensions/caido.ts`, `scripts/caido.py`)。
- **访客身份验证绝大部分情况下是只读的。** 如果没有 API token，客户端将使用访客登录，这可以使用现有项目但不能创建项目。它也无法读取其他用户的数据。
- **Headless 实例仅限回环地址。** 它在 `127.0.0.1:` 上监听并且是脱离的，不向网络暴露。
- **CA 证书**是 Caido 的拦截根证书；请像对待任何代理 CA 一样对待它。它存储在您的状态目录下，具有正常的文件权限。
- **Tokens** 永远不会离开您的机器；它们仅作为 `Bearer` header 发送到您本地的 Caido 实例。
## 故障排除
| 症状 | 修复方法 |
|---------|-----|
| `⚠ Caido not ready: … no active project` | 打开一次 Caido GUI，登录，创建/打开一个项目。或者设置 `CAIDO_API_TOKEN`。 |
| `caido-cli exited early` / 实例无法启动 | 检查 `$CAIDO_STATE_DIR/instance.log`。确保 `caido`/`caido-cli` 已安装并在 `PATH` 中，或者在 `scripts/caido.py` (`CAIDO_CLI`) 中设置路径。 |
| 访客登录被拒绝 | 实例启动时没有带上 `--allow-guests`，或者访客模式被禁用。通过 `/caido start`（此包）启动，或者设置一个 API token。 |
| `python3: not found` | 安装 Python ≥3.8 并确保它在 `PATH` 中。 |
| 扫描器遇到 TLS 错误 | 您忘记了 CA 环境变量 —— `caido_proxy` 会打印它们；当 agent 驱动扫描器时会自动设置它们。 |
| 想要一个全新的实例 | `/caido stop` 然后 `/caido start`，或者删除 `$CAIDO_STATE_DIR/instance.json`。 |
## 许可证
[MIT](LICENSE) — 可自由使用、修改和分发。感谢提及来源，但非必须。
标签：MITM代理, Python, TypeScript, 安全合规, 安全插件, 无后门, 流量捕获, 网络代理, 网络拓扑, 网络调试, 自动化, 逆向工具