Ferret

面向安全测试人员的协作式 MITM 代理。

从统一界面捕获 HTTP 流量、使用 AI 为请求添加注解、运行 hunt 会话、重放流量并跟踪发现项。

快速开始 · 功能特性 · 截图 · 配置 · 安全 · 参与贡献

快速开始

安装

git clone https://github.com/synlace/ferret.git
cd ferret

cp .env.example .env   # optional
just up

或者直接使用 Docker Compose：

docker compose up --build -d

打开 Ferret

打开：

http://localhost:3000

首次运行的设置向导会要求你设置密码并选择 AI 提供商。

环境要求

• Docker
• Docker Compose
• just

概述

Ferret 是一个面向安全测试人员的 AI 辅助 HTTP 拦截代理。

将浏览器、CLI 工具或测试工作流指向：

127.0.0.1:1337

Ferret 捕获请求和响应，在本地存储，用 AI 为流量添加注解，并提供工具用于重放、修改、测试以及将有趣的行为转化为发现项。

它的设计目标是支持这样的工作流：你想要的不仅仅是被动代理，而是一个能帮助你在过程中思考、测试和记录的工具。

功能特性

截图

Hunts - AI 辅助的 hunt 会话，可搜索请求历史、编写并运行测试、创建发现项。

History - 完整的代理请求日志，包含 AI 注解、耗时、状态码以及内联的请求/响应编辑器。

Findings - 漏洞跟踪器，包含严重性、主机、类型、AI 生成的描述和证据片段。

Settings - 管理 CA 证书、密码、2FA、AI 提供商、API 密钥和代理状态。

设置向导 - 首次运行时创建密码并配置 AI 提供商。

使用代理

将浏览器、CLI 工具或测试客户端配置为使用：

HTTP proxy:  127.0.0.1:1337
HTTPS proxy: 127.0.0.1:1337

对于 HTTPS 拦截，请从 Settings 页面下载并安装 mitmproxy CA 证书。

身份验证

Ferret 在每次安装时都要求进行身份验证。

浏览器登录

1. 首次打开 UI。
2. 在设置向导中设置密码。
3. 完成 AI 提供商设置。
4. 在 /login 登录。
5. Ferret 会签发一个 24 小时的 HttpOnly SameSite=Strict 会话 Cookie。

双因素认证

可在 Settings 页面启用基于 TOTP 的 2FA。

启用后，登录时需要提供有效的验证器验证码。

API 访问

在 .env 中设置静态 API 密钥：

FERRET_API_KEY=your-random-secret

然后将其用作 Bearer 令牌：

curl -H "Authorization: Bearer your-random-secret" \
  http://localhost:8000/api/requests

会话 Cookie 和 Bearer 令牌会被独立检查。

配置

将 .env.example 复制为 .env 以预配置 Ferret。

大多数 AI 提供商设置也可以在设置向导中配置。

支持的 AI 提供商

提供商设置可在首次运行向导中完成。

just 命令

架构

Browser / tool
      │
      ▼
127.0.0.1:1337
      │
      ▼
ferret-api :8000 / :1337
FastAPI + mitmproxy + SQLite
      │
      ├── docker exec
      ▼
ferret-lab
pytest, ffuf, sqlmap, scripts, tests, notes
      │
      ▼
ferret-ui :3000
Next.js

所有持久化数据存储于：

${FERRET_DATA_DIR:-./data}

Ferret 使用绑定挂载，而不是命名 Docker 卷。

重置 Ferret

要清空本地状态并重新启动设置向导：

just reset

这会删除本地数据库，包括凭据。

你还可以在通过身份验证后通过 API 重置设置：

curl -X DELETE \
  -H "Authorization: Bearer your-random-secret" \
  http://localhost:8000/api/setup

开发

如需热重载的本地 UI 开发：

just dev

这会在 Docker 中运行 API 和 lab 容器，同时通过 npm run dev 在宿主机上提供 UI。此模式要求宿主机安装 Node.js。

运行测试：

just test api    # API unit tests (inside the running api container)
just test ui     # Playwright UI tests (auto-starts Next.js dev server + mock API)
just test shim   # docker-shim allow/block unit tests (no Docker needed)
just test all    # run all three suites in sequence

安全

Ferret 专为本地安全测试工作流而设计，并未针对公网暴露进行加固。

风险

在将 Ferret 暴露到 localhost 之外之前，请了解以下内容：

请使用强密码，并在 Settings 页面启用 2FA。

报告漏洞

请勿针对安全漏洞开启公开 issue。

完整披露政策和报告说明请参阅 .github/SECURITY.md。

已披露报告

修复可用后，过去的披露会在 security/ 中发布。

致谢

感谢以下研究人员负责任地披露安全问题：

参与贡献

Ferret 正在积极开发中。

欢迎提供想法、bug 报告、功能请求和贡献。

想帮助构建它吗？

邮箱：[email protected]

许可证

MIT - 请参阅 LICENSE。