Ferret

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

Quick start

Install

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 Ferret

Open:

http://localhost:3000

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

Requirements

• Docker
• Docker Compose
• just

Overview

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.

Features

Screenshots

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.

Using the proxy

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.

Authentication

Ferret requires authentication on every install.

Browser login

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.

Two-factor authentication

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

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

API access

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.

Configuration

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

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

Supported AI providers

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

just commands

Architecture

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.

Resetting Ferret

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

Development

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

Security

Ferret is designed for local security testing workflows and is not hardened for public exposure.

Risks

Before exposing Ferret outside localhost, understand the following:

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

Reporting a vulnerability

Do not open a public issue for security vulnerabilities.

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

Disclosed reports

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

Acknowledgements

Thanks to the following researchers for responsibly disclosing security issues:

Contributing

Ferret is actively being developed.

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

Want to help build it?

Email: [email protected]

License

MIT - see LICENSE.