synlace/ferret
GitHub: synlace/ferret
面向安全测试人员的开源 AI 辅助 HTTP 拦截代理，集流量捕获、请求编辑重放、漏洞追踪与 AI 智能分析于一体。
Stars: 40 | Forks: 2
# ferret
**面向安全测试人员的 AI 辅助 HTTP 拦截与分析工具。**
## 截图
## 安装说明
**前置条件：** Docker，Docker Compose，[`just`](https://github.com/casey/just)
```
git clone https://github.com/synlace/ferret.git
cd ferret
cp .env.example .env # set OPENROUTER_PROVISIONING_KEY at minimum
just up
# 或: docker compose up --build -d
```
| 服务 | URL |
|---------|-----|
| UI | http://localhost:3000 |
| API | http://localhost:8000 |
| Proxy | `127.0.0.1:1337` |
将您的浏览器或工具指向 `127.0.0.1:1337`。对于 HTTPS，请从代理设置页面安装 mitmproxy CA 证书。
## 配置
将 `.env.example` 复制为 `.env`：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `OPENROUTER_PROVISIONING_KEY` | — | 主 OpenRouter 密钥（AI 功能必需） |
| `OPENROUTER_MODEL` | `google/gemini-3-flash-preview` | 用于聊天和注释的模型 |
| `PROXY_HOST` | `0.0.0.0` | 代理绑定地址 |
| `PROXY_PORT` | `1337` | 代理端口 |
| `UI_PORT` | `3000` | UI 端口 |
| `FERRET_DATA_DIR` | `./data` | 用于存储所有持久化数据的主机路径 |
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | 浏览器访问的 API URL |
| `NEXT_PUBLIC_SIGINT_URL` | — | 可选的 SIGINT 新闻订阅 JSON URL |
## 功能特性
- **拦截代理** — 运行在 `:1337` 的 mitmproxy，流量存储在 SQLite 中
- **请求历史记录** — 浏览、过滤、重放已捕获的请求
- **AI 聊天** — 通过 OpenRouter 进行多会话聊天；上下文范围限定在单个项目内
- **发现** — 跟踪漏洞，记录其严重程度、状态和主机标签
- **工作区** — 每个会话独立的 `scripts/`、`tests/`、`notes/` 目录，可在实验室容器中编辑和运行
- **Snare** — 实时拦截并修改请求/响应
- **Gnaw** — 带有代理路由的持久化重放器标签页
- **项目** — 按项目隔离请求历史记录、发现、工作区和 API 密钥
## `just` 命令
| 命令 | 描述 |
|--------|-------------|
| `just up` | 构建并启动所有服务 |
| `just down` | 停止所有服务 |
| `just dev` | API/实验室运行在 Docker 中，UI 在主机端热重载（需要 Node.js） |
| `just logs` | 实时查看日志 |
| `just test api` | API 单元测试 |
| `just test ui` | Playwright UI 测试 |
| `just reset` | 清空数据库 |
| `just shell` | 进入实验室容器的 Shell |
## 系统架构
```
Browser / tool → 127.0.0.1:1337
│
ferret-api :8000/:1337 (FastAPI + mitmproxy, SQLite)
│ docker exec
ferret-lab (pytest, ffuf, sqlmap…)
ferret-ui :3000 (Next.js)
```
所有数据通过绑定挂载存储在 `${FERRET_DATA_DIR:-./data}` 目录中 —— 未使用命名的 Docker 卷。
## 开源许可证
MIT — 见 [LICENSE](LICENSE)。
|  **发现** — 包含严重程度、主机、类型和证据的漏洞列表。 |  **历史记录** — 带有 AI 注释、耗时和响应详情的代理请求日志。 |
|  **Gnaw** — 持久化重放器。通过功能完备的请求/响应编辑器编辑并重发请求。 |  **工作区** — 带有脚本运行器的 AI 聊天。在项目级上下文环境中针对目标执行脚本。 |
|  **Snare** — 实时拦截请求。在请求到达服务器之前，对其进行编辑并决定放行或丢弃。 |  **工作区（测试）** — 在工作区中编写并运行 pytest 测试，实时查看内联输出。 |
标签：AI辅助测试, API安全, CISA项目, Docker, HTTPS解密, HTTP代理, JSON输出, LLM, MITM, mitmproxy, pytest, Python, Unmanaged PE, Web安全, 中间人代理, 人工智能, 代码生成, 协同工作, 协同测试, 反取证, 安全测试, 安全规则引擎, 安全评估, 安全防御评估, 密码管理, 抓包工具, 攻击性安全, 无后门, 服务管理, 流量拦截, 渗透测试工具, 渗透测试平台, 漏洞修复, 版权保护, 用户模式Hook绕过, 结构化信息, 网络安全, 网络安全培训, 网络安全测试, 脚本执行, 自动化攻击, 蓝队分析, 请求拦截, 请求重放, 逆向工具, 隐私保护, 黑盒测试