The collaborative MITM proxy for security testers.

Capture HTTP traffic, annotate requests with AI, run hunt sessions, replay traffic, and track findings from one interface.

Quick start · Features · Screenshots · Configuration · Security · Contributing

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

cp .env.example .env   # optional
just up

Or use Docker Compose directly:

docker compose up --build -d

Open:

http://localhost:3000

The first-run setup wizard will ask you to set a password and choose an AI provider.

• Docker
• Docker Compose
• just

Ferret is an AI-assisted HTTP interception proxy built for security testers.

Point your browser, CLI tool, or testing workflow at:

127.0.0.1:1337

Ferret captures requests and responses, stores them locally, annotates traffic with AI, and gives you tools to replay, modify, test, and turn interesting behaviour into findings.

It is designed for workflows where you want more than a passive proxy: you want something that helps you think, test, and document as you go.

Hunts - AI-assisted hunt sessions that search request history, write and run tests, and create findings.

History - A full proxied request log with AI annotations, timings, status codes, and inline request/response editors.

Findings - A vulnerability tracker with severity, host, type, AI-generated descriptions, and evidence snippets.

Settings - Manage the CA certificate, password, 2FA, AI provider, API keys, and proxy status.

Setup wizard - First-run setup for password creation and AI provider configuration.

Configure your browser, CLI tool, or test client to use:

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

For HTTPS interception, download and install the mitmproxy CA certificate from the Settings page.

Ferret requires authentication on every install.

1. Open the UI for the first time.
2. Set a password in the setup wizard.
3. Complete AI provider setup.
4. Log in at /login.
5. Ferret issues a 24-hour HttpOnly SameSite=Strict session cookie.

TOTP-based 2FA can be enabled from the Settings page.

Once enabled, a valid authenticator code is required at login.

Set a static API key in .env:

FERRET_API_KEY=your-random-secret

Then use it as a Bearer token:

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

Session cookies and Bearer tokens are checked independently.

Copy .env.example to .env to preconfigure Ferret.

Most AI provider settings can also be configured from the setup wizard.

Provider setup can be completed from the first-run wizard.

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

All persistent data is stored under:

${FERRET_DATA_DIR:-./data}

Ferret uses bind mounts rather than named Docker volumes.

To wipe local state and restart the setup wizard:

just reset

This removes the local database, including credentials.

You can also reset setup through the API when authenticated:

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

For local UI development with hot reload:

just dev

This runs the API and lab containers in Docker while serving the UI on the host via npm run dev. Node.js is required on the host for this mode.

Run tests with:

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 is designed for local security testing workflows and is not hardened for public exposure.

Before exposing Ferret outside localhost, understand the following:

Use a strong password and enable 2FA from the Settings page.

Do not open a public issue for security vulnerabilities.

See .github/SECURITY.md for the full disclosure policy and reporting instructions.

Past disclosures are published in security/ once fixes are available.

Thanks to the following researchers for responsibly disclosing security issues:

Ferret is actively being developed.

Ideas, bug reports, feature requests, and contributions are welcome.

Want to help build it?

Email: aidan@synlace.ai

MIT - see LICENSE.