Ferret

Der kollaborative MITM-Proxy für Sicherheitstester.

HTTP-Traffic erfassen, Anfragen mit KI annotieren, Jagdsitzungen durchführen, Traffic wiedergeben und Ergebnisse aus einer Oberfläche verfolgen.

Schnellstart · Funktionen · Bildschirmfotos · Konfiguration · Sicherheit · Mitwirken

Schnellstart

Installation

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

cp .env.example .env   # optional
just up

Oder direkt Docker Compose verwenden:

docker compose up --build -d

Ferret öffnen

Öffnen:

http://localhost:3000

Der Einrichtungsassistent beim ersten Start fragt Sie nach einem Passwort und einem KI-Anbieter.

Voraussetzungen

• Docker
• Docker Compose
• just

Überblick

Ferret ist ein KI-gestützter HTTP-Interception-Proxy für Sicherheitstester.

Richten Sie Ihren Browser, Ihr CLI-Tool oder Ihren Test-Workflow auf Folgendes aus:

127.0.0.1:1337

Ferret erfasst Anfragen und Antworten, speichert sie lokal, annotiert den Traffic mit KI und bietet Werkzeuge zum Wiederholen, Modifizieren, Testen und Umwandeln interessanten Verhaltens in Ergebnisse.

Es ist für Workflows konzipiert, bei denen Sie mehr als einen passiven Proxy benötigen: etwas, das Ihnen hilft, während der Arbeit zu denken, zu testen und zu dokumentieren.

Funktionen

Bildschirmfotos

Jagden – KI-gestützte Jagdsitzungen, die den Anfrageverlauf durchsuchen, Tests schreiben und ausführen sowie Ergebnisse erstellen.

Verlauf – Ein vollständiges protokolliertes Proxy-Anfragenprotokoll mit KI-Anmerkungen, Zeitangaben, Statuscodes und integrierten Anfrage-/Antwort-Editoren.

Ergebnisse – Ein Schwachstellen-Tracker mit Schweregrad, Host, Typ, KI-generierten Beschreibungen und Beweis-Schnipseln.

Einstellungen – CA-Zertifikat, Passwort, 2FA, KI-Anbieter, API-Schlüssel und Proxy-Status verwalten.

Einrichtungsassistent – Ersteinrichtung für Passworterstellung und KI-Anbieterkonfiguration.

Proxy verwenden

Konfigurieren Sie Ihren Browser, Ihr CLI-Tool oder Ihren Test-Client wie folgt:

HTTP-Proxy:  127.0.0.1:1337
HTTPS-Proxy: 127.0.0.1:1337

Für HTTPS-Interception laden Sie das mitmproxy-CA-Zertifikat von der Seite Einstellungen herunter und installieren Sie es.

Authentifizierung

Ferret erfordert bei jeder Installation eine Authentifizierung.

Browser-Login

1. Öffnen Sie die Oberfläche zum ersten Mal.
2. Legen Sie im Einrichtungsassistenten ein Passwort fest.
3. Schließen Sie die KI-Anbieter-Einrichtung ab.
4. Melden Sie sich unter /login an.
5. Ferret stellt ein 24-stündiges HttpOnly-SameSite=Strict-Sitzungs-Cookie aus.

Zwei-Faktor-Authentifizierung

TOTP-basierte 2FA kann auf der Seite Einstellungen aktiviert werden.

Nach der Aktivierung ist beim Login ein gültiger Authentifikator-Code erforderlich.

API-Zugriff

Legen Sie einen statischen API-Schlüssel in .env fest:

FERRET_API_KEY=your-random-secret

Verwenden Sie ihn dann als Bearer-Token:

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

Sitzungs-Cookies und Bearer-Tokens werden unabhängig voneinander geprüft.

Konfiguration

Kopieren Sie .env.example nach .env, um Ferret vorzukonfigurieren.

Die meisten KI-Anbietereinstellungen können auch über den Einrichtungsassistenten konfiguriert werden.

Unterstützte KI-Anbieter

Die Anbieterkonfiguration kann über den Erststart-Assistenten abgeschlossen werden.

just-Befehle

Architektur

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

Alle persistenten Daten werden unter folgendem Pfad gespeichert:

${FERRET_DATA_DIR:-./data}

Ferret verwendet Bind Mounts anstelle benannter Docker-Volumes.

Ferret zurücksetzen

Um den lokalen Zustand zu löschen und den Einrichtungsassistenten neu zu starten:

just reset

Dies löscht die lokale Datenbank einschließlich der Anmeldedaten.

Sie können die Einrichtung auch über die API zurücksetzen, wenn Sie authentifiziert sind:

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

Entwicklung

Für lokale UI-Entwicklung mit Hot Reload:

just dev

Dies führt die API- und Lab-Container in Docker aus, während die UI auf dem Host über npm run dev bereitgestellt wird. Für diesen Modus wird Node.js auf dem Host benötigt.

Tests ausführen mit:

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

Sicherheit

Ferret ist für lokale Sicherheitstest-Workflows konzipiert und nicht für die öffentliche Exposition gehärtet.

Risiken

Bevor Sie Ferret außerhalb von localhost bereitstellen, beachten Sie Folgendes:

Verwenden Sie ein starkes Passwort und aktivieren Sie 2FA auf der Seite Einstellungen.

Sicherheitslücke melden

Öffnen Sie kein öffentliches Issue für Sicherheitslücken.

Siehe .github/SECURITY.md für die vollständige Offenlegungsrichtlinie und Meldeanweisungen.

Bisherige Meldungen

Vergangene Offenlegungen werden in security/ veröffentlicht, sobald Korrekturen verfügbar sind.

Danksagungen

Dank an die folgenden Forscher für die verantwortungsvolle Offenlegung von Sicherheitsproblemen:

Mitwirken

Ferret wird aktiv weiterentwickelt.

Ideen, Fehlerberichte, Funktionsanfragen und Beiträge sind willkommen.

Möchten Sie beim Bauen helfen?

E-Mail: [email protected]

Lizenz

MIT – siehe LICENSE.