usk6666/yorishiro-proxy
GitHub: usk6666/yorishiro-proxy
面向 AI Agent 的 MITM 代理服务器，通过 MCP 协议让 AI 自主完成流量拦截、重放和模糊测试等安全测试任务
Stars: 0 | Forks: 0
AI 优先的 MITM 代理工具
面向 AI Agent 的网络代理 —— 通过 MCP 拦截、记录和重放流量。
日本語
Yorishiro Proxy 作为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器运行，通过十一个 MCP 工具赋予 AI Agent 对代理操作的完全控制权。该工具专为 Claude Code 和其他兼容 MCP 的 Agent 设计，无需手动操作 UI 即可实现自动化安全测试工作流。同时提供内置 Web UI，用于可视化检查和交互式操作。
## 功能特性
- **流量拦截与记录** -- 具备自动 CA 证书管理的 MITM 代理
- **重发器 (Resender)** -- 重放请求，支持 Header/Body/URL 覆盖、JSON 补丁及原始 HTTP 编辑
- **模糊测试器 (Fuzzer)** -- 自动化 Payload 注入，支持顺序/并行模式及异步执行
- **宏 (Macro)** -- 多步请求序列，支持变量提取和模板替换
- **拦截** -- 实时挂起并检查请求/响应，然后释放、修改或丢弃
- **自动转换** -- 针对匹配流量的自动请求/响应修改规则
- **目标范围** -- 双层安全边界（策略层 + Agent 层）以限制可访问的主机
- **多协议** -- HTTP/1.x, HTTPS (MITM), HTTP/2 (h2c/h2), gRPC, WebSocket, Raw TCP, SOCKS5
- **多监听器** -- 在不同端口上同时运行多个代理监听器
- **Flow 导出/导入** -- 支持 JSONL, HAR 1.2 和 cURL 导出格式
- **SOCKS5 监听器** -- 支持可选用户名/密码认证的 SOCKS5 代理，便于 proxychains 集成
- **上游代理** -- 支持通过 HTTP 或 SOCKS5 代理进行链式代理
- **可流式 HTTP MCP (Streamable HTTP MCP)** -- 支持 Bearer Token 认证的多 Agent 共享访问
- **插件系统** -- 使用 [Starlark](https://github.com/google/starlark-go) 脚本扩展代理行为，可挂载到请求/响应管道中
- **Web UI** -- 内置 React/Vite 仪表盘，用于可视化检查和交互式测试
## 快速开始
### 1. 获取二进制文件
从 [GitHub Releases](https://github.com/usk6666/yorishiro-proxy/releases) 页面下载预编译的二进制文件，或从源码构建：
```
git clone https://github.com/usk6666/yorishiro-proxy.git
cd yorishiro-proxy
make build # outputs bin/yorishiro-proxy
```
### 2. 配置 MCP
添加到你的 MCP 客户端配置中（例如 Claude Code 的 `.mcp.json`）：
```
{
"mcpServers": {
"yorishiro-proxy": {
"command": "/path/to/bin/yorishiro-proxy",
"args": []
}
}
}
```
代理通过 stdin/stdout 作为 MCP 服务器启动。CA 证书会在首次运行时自动生成，并持久化存储到 `~/.yorishiro-proxy/ca/`。
若要同时启用 Web UI：
```
{
"mcpServers": {
"yorishiro-proxy": {
"command": "/path/to/bin/yorishiro-proxy",
"args": ["-mcp-http-addr", "127.0.0.1:3000"]
}
}
}
```
启动时，日志（stderr 或 `-log-file` 指定的文件）会打印包含认证 Token 的访问 URL：
```
WebUI available url=http://127.0.0.1:3000/?token=
```
在浏览器中打开此 URL。Token 每次启动时自动生成；可使用 `-mcp-http-token` 设置固定值。
### 3. 首次捕获
MCP 服务器运行后，AI Agent 即可开始捕获流量：
```
1. Start the proxy -> proxy_start with listen_addr "127.0.0.1:8080"
2. Set HTTP_PROXY -> point your target application at the proxy
3. Install the CA cert -> query ca_cert to get the certificate path
4. Browse / send traffic -> captured flows appear in query flows
5. Inspect & replay -> use resend to replay with modifications
```
## MCP 工具
所有代理操作均通过十一个 MCP 工具暴露：
| 工具 | 用途 |
|------|---------|
| `proxy_start` | 启动代理监听器，配置捕获范围、TLS 透传、拦截规则、自动转换、TCP 转发及协议设置 |
| `proxy_stop` | 优雅关闭一个或所有监听器 |
| `configure` | 运行时配置更改（上游代理、捕获范围、TLS 透传、拦截规则、自动转换、连接限制） |
| `query` | 统一信息检索：Flow、Flow 详情、消息、代理状态、配置、CA 证书、拦截队列、宏、Fuzz 任务/结果 |
| `resend` | 重放已记录的请求，支持变更（Method/URL/Header/Body 覆盖、JSON 补丁、原始字节补丁、Dry-run） |
| `fuzz` | 执行模糊测试任务，支持 Payload 集、位置、并发控制及停止条件 |
| `macro` | 定义并执行多步宏工作流，支持变量提取、守卫条件及钩子 |
| `intercept` | 处理被拦截的请求：释放、修改并转发或丢弃 |
| `manage` | 管理 Flow 数据（删除/导出/导入）及 CA 证书重新生成 |
| `security` | 配置目标范围规则（策略层 + Agent 层）以限制代理访问范围 |
| `plugin` | 在运行时列出、重载、启用和禁用 Starlark 插件 |
## Web UI
当启用可流式 HTTP 模式（`-mcp-http-addr`）时，内置 Web UI 将在同一地址提供服务。
| 页面 | 描述 |
|------|-------------|
| **Flows** | Flow 列表，支持按协议、方法、状态码和 URL 模式过滤 |
| **Dashboard** | Flow 统计概览，提供实时流量摘要 |
| **Intercept** | 实时请求/响应拦截，支持内联编辑 |
| **Resender** | 重放请求，支持覆盖、JSON 补丁、原始 HTTP 编辑及 Dry-run 预览 |
| **Fuzz** | 创建并管理模糊测试任务，包含 Payload 集和结果分析 |
| **Macros** | 多步请求工作流，支持变量提取 |
| **Security** | 目标范围配置（策略层 + Agent 层），支持 URL 测试 |
| **Settings** | 代理控制、TLS 透传、自动转换规则、CA 管理等 |
Web UI 通过可流式 HTTP MCP 与后端通信 —— 即 AI Agent 所使用的同一协议。
## 支持的协议
| 协议 | 检测方式 | 备注 |
|----------|-----------|-------|
| HTTP/1.x | 自动 | 转发代理模式 |
| HTTPS | CONNECT | MITM，支持动态证书签发 |
| HTTP/2 | h2c / ALPN | 明文和 TLS 均支持，支持按流显示 |
| gRPC | HTTP/2 content-type | 服务/方法提取，支持流式传输，结构化元数据显示 |
| WebSocket | HTTP Upgrade | 消息级记录，支持按消息显示 |
| Raw TCP | 回退 | 捕获任何未识别的协议，支持 TCP 转发映射 |
## CLI 标志
| 标志 | 环境变量 | 默认值 | 描述 |
|------|-------------|---------|-------------|
| `-db` | `YP_DB` | `~/.yorishiro-proxy/yorishiro.db` | SQLite 数据库路径或项目名称 |
| `-ca-cert` / `-ca-key` | `YP_CA_CERT` / `YP_CA_KEY` | -- | CA 证书和私钥路径 |
| `-ca-ephemeral` | `YP_CA_EPHEMERAL` | `false` | 使用临时的内存 CA |
| `-insecure` | `YP_INSECURE` | `false` | 跳过上游 TLS 验证 |
| `-config` | `YP_CONFIG` | -- | 代理默认值的 JSON 配置文件路径 |
| `-log-level` | `YP_LOG_LEVEL` | `info` | 日志级别：debug, info, warn, error |
| `-log-format` | `YP_LOG_FORMAT` | `text` | 日志格式：text, json |
| `-log-file` | `YP_LOG_FILE` | stderr | 日志输出文件 |
| `-mcp-http-addr` | `YP_MCP_HTTP_ADDR` | -- | 可流式 HTTP 监听地址（同时提供 Web UI） |
| `-mcp-http-token` | `YP_MCP_HTTP_TOKEN` | 自动生成 | HTTP Bearer 认证 Token |
优先级：CLI 标志 > 环境变量 > 配置文件 > 默认值。
`-db` 标志接受绝对路径、带扩展名的相对路径或纯项目名称。项目名称（例如 `my-project`）会解析为 `~/.yorishiro-proxy/my-project.db`，便于为每次任务维护独立的数据库。
## 架构
```
Layer 4 TCP Listener
-> Protocol Detection (peek bytes)
-> Protocol Handler (HTTP/S, HTTP/2, gRPC, WebSocket, Raw TCP)
-> Flow Recording (Request/Response)
-> MCP Tool (Intercept / Replay / Search)
```
- 在第 4 层（TCP）接受连接，并路由到模块化协议处理器
- 无外部代理库 —— 基于 Go 标准库构建
- MCP 优先：所有操作均作为 MCP 工具独占暴露
- 内置 Web UI 采用 React/Vite 构建，通过可流式 HTTP 提供服务
## 文档
- [入门指南](docs/getting-started.md) -- 详细的安装和使用演练
- [插件开发指南](docs/plugins.md) -- 编写 Starlark 插件以扩展代理行为
## 贡献
欢迎贡献！请先开 Issue 讨论你希望更改的内容。
## 许可证
根据 Apache License 2.0 授权。详见 [LICENSE](LICENSE)。标签：CA证书管理, Claude Code, EVTX分析, Go语言, HTTP代理, IP 地址批量处理, MCP服务器, Model Context Protocol, Python工具, Web安全, 中间人攻击, 人工智能原生, 安全测试, 攻击性安全, 数据包篡改, 日志审计, 流量录制与回放, 流量拦截, 程序破解, 网络协议分析, 自动化渗透测试, 蓝队分析, 请求重发