Ferret

Il proxy MITP collaborativo per i tester di sicurezza.

Cattura il traffico HTTP, annota le richieste con l'IA, esegui sessioni di caccia, riproduci il traffico e tieni traccia dei risultati da un'unica interfaccia.

Avvio rapido · Funzionalità · Screenshot · Configurazione · Sicurezza · Contributi

Avvio rapido

Installazione

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

cp .env.example .env   # opzionale
just up

Oppure usa Docker Compose direttamente:

docker compose up --build -d

Apri Ferret

Apri:

http://localhost:3000

La procedura guidata del primo avvio ti chiederà di impostare una password e scegliere un provider AI.

Requisiti

• Docker
• Docker Compose
• just

Panoramica

Ferret è un proxy di intercettazione HTTP assistito dall'IA, progettato per tester di sicurezza.

Punta il tuo browser, strumento CLI o flusso di test verso:

127.0.0.1:1337

Ferret cattura richieste e risposte, le archivia localmente, annota il traffico con l'IA e ti fornisce strumenti per riprodurre, modificare, testare e trasformare comportamenti interessanti in segnalazioni.

È progettato per flussi di lavoro in cui desideri più di un proxy passivo: vuoi qualcosa che ti aiuti a pensare, testare e documentare mentre procedi.

Funzionalità

Screenshot

Cacce – Sessioni di caccia assistite dall'IA che cercano nella cronologia richieste, scrivono ed eseguono test e creano segnalazioni.

Cronologia – Registro completo delle richieste proxy con annotazioni AI, tempi, codici di stato ed editor inline di richieste/risposte.

Segnalazioni – Tracker delle vulnerabilità con gravità, host, tipo, descrizioni generate dall'IA e frammenti di evidenza.

Impostazioni – Gestisci il certificato CA, la password, il 2FA, il provider AI, le chiavi API e lo stato del proxy.

Procedura guidata di configurazione – Configurazione del primo avvio per la creazione della password e la configurazione del provider AI.

Utilizzo del proxy

Configura il browser, lo strumento CLI o il client di test per usare:

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

Per l'intercettazione HTTPS, scarica e installa il certificato CA di mitmproxy dalla pagina Impostazioni.

Autenticazione

Ferret richiede l'autenticazione su ogni installazione.

Accesso dal browser

1. Apri l'interfaccia utente per la prima volta.
2. Imposta una password nella procedura guidata di configurazione.
3. Completa la configurazione del provider AI.
4. Accedi su /login.
5. Ferret emette un cookie di sessione HttpOnly SameSite=Strict valido 24 ore.

Autenticazione a due fattori

La 2FA basata su TOTP può essere attivata dalla pagina Impostazioni.

Una volta attivata, è richiesto un codice autenticatore valido al login.

Accesso API

Imposta una chiave API statica in .env:

FERRET_API_KEY=la-tua-chiave-segreta

Poi usala come token Bearer:

curl -H "Authorization: Bearer la-tua-chiave-segreta" \
  http://localhost:8000/api/requests

I cookie di sessione e i token Bearer vengono verificati indipendentemente.

Configurazione

Copia .env.example in .env per preconfigurare Ferret.

La maggior parte delle impostazioni del provider AI può essere configurata anche dalla procedura guidata.

Provider AI supportati

La configurazione del provider può essere completata dalla procedura guidata del primo avvio.

Comandi just

Architettura

Browser / strumento
      │
      ▼
127.0.0.1:1337
      │
      ▼
ferret-api :8000 / :1337
FastAPI + mitmproxy + SQLite
      │
      ├── docker exec
      ▼
ferret-lab
pytest, ffuf, sqlmap, script, test, note
      │
      ▼
ferret-ui :3000
Next.js

Tutti i dati persistenti sono archiviati in:

${FERRET_DATA_DIR:-./data}

Ferret utilizza bind mount invece di volumi Docker nominati.

Ripristino di Ferret

Per cancellare lo stato locale e riavviare la procedura guidata:

just reset

Questo rimuove il database locale, incluse le credenziali.

Puoi anche resettare la configurazione tramite API quando autenticato:

curl -X DELETE \
  -H "Authorization: Bearer la-tua-chiave-segreta" \
  http://localhost:8000/api/setup

Sviluppo

Per lo sviluppo locale dell'interfaccia utente con ricarica a caldo:

just dev

Questo esegue i container API e lab in Docker mentre serve l'UI sull'host tramite npm run dev. Node.js è richiesto sull'host per questa modalità.

Esegui i test con:

just test api    # Test unitari API (nel container api in esecuzione)
just test ui     # Test UI Playwright (avvia automaticamente il server dev Next.js + API fittizia)
just test shim   # Test unitari allow/block di docker-shim (senza Docker)
just test all    # esegue tutte e tre le suite in sequenza

Sicurezza

Ferret è progettato per flussi di lavoro di test di sicurezza locali e non è indurito per l'esposizione pubblica.

Rischi

Prima di esporre Ferret al di fuori di localhost, comprendi quanto segue:

Usa una password forte e attiva la 2FA dalla pagina Impostazioni.

Segnalazione di una vulnerabilità

Non aprire un issue pubblico per vulnerabilità di sicurezza.

Vedi .github/SECURITY.md per l'informativa completa sulla divulgazione e le istruzioni per la segnalazione.

Report divulgati

Le divulgazioni passate sono pubblicate in security/ una volta disponibili le correzioni.

Riconoscimenti

Grazie ai seguenti ricercatori per aver segnalato responsabilmente problemi di sicurezza:

Contributi

Ferret è in fase di sviluppo attivo.

Idee, segnalazioni di bug, richieste di funzionalità e contributi sono benvenuti.

Vuoi aiutare a costruirlo?

Email: [email protected]

Licenza

MIT - vedi LICENSE.