Ferret

Le proxy MITM collaboratif pour les testeurs de sécurité.

Capturez le trafic HTTP, annotez les requêtes avec l'IA, lancez des sessions de chasse, rejouez le trafic et suivez les constatations depuis une seule interface.

Démarrage rapide · Fonctionnalités · Captures d'écran · Configuration · Sécurité · Contribuer

Démarrage rapide

Installation

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

cp .env.example .env   # optional
just up

Ou utilisez Docker Compose directement :

docker compose up --build -d

Ouvrir Ferret

Ouvrez :

http://localhost:3000

L'assistant de configuration initiale vous demandera de définir un mot de passe et de choisir un fournisseur d'IA.

Prérequis

• Docker
• Docker Compose
• just

Présentation

Ferret est un proxy d'interception HTTP assisté par IA conçu pour les testeurs de sécurité.

Pointez votre navigateur, outil CLI ou flux de test vers :

127.0.0.1:1337

Ferret capture les requêtes et réponses, les stocke localement, annote le trafic avec l'IA et vous offre des outils pour rejouer, modifier, tester et transformer les comportements intéressants en constatations.

Il est conçu pour les flux de travail où vous voulez plus qu'un proxy passif : vous voulez quelque chose qui vous aide à réfléchir, tester et documenter au fur et à mesure.

Fonctionnalités

Captures d'écran

Chasses - Sessions de chasse assistées par IA qui recherchent dans l'historique des requêtes, écrivent et exécutent des tests, et créent des constatations.

Historique - Journal complet des requêtes proxy avec annotations IA, temps, codes de statut et éditeurs de requêtes/réponses intégrés.

Constatations - Suivi des vulnérabilités avec sévérité, hôte, type, descriptions générées par IA et extraits de preuves.

Paramètres - Gérez le certificat CA, le mot de passe, la 2FA, le fournisseur d'IA, les clés API et le statut du proxy.

Assistant d'installation - Configuration initiale pour la création du mot de passe et la configuration du fournisseur d'IA.

Utilisation du proxy

Configurez votre navigateur, outil CLI ou client de test pour utiliser :

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

Pour l'interception HTTPS, téléchargez et installez le certificat CA mitmproxy depuis la page Paramètres.

Authentification

Ferret exige une authentification à chaque installation.

Connexion au navigateur

1. Ouvrez l'interface pour la première fois.
2. Définissez un mot de passe dans l'assistant de configuration.
3. Terminez la configuration du fournisseur d'IA.
4. Connectez-vous sur /login.
5. Ferret émet un cookie de session HttpOnly SameSite=Strict d'une durée de 24 heures.

Authentification à deux facteurs

La 2FA basée sur TOTP peut être activée depuis la page Paramètres.

Une fois activée, un code d'authentificateur valide est requis lors de la connexion.

Accès API

Définissez une clé API statique dans .env :

FERRET_API_KEY=your-random-secret

Utilisez-la ensuite comme jeton Bearer :

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

Les cookies de session et les jetons Bearer sont vérifiés indépendamment.

Configuration

Copiez .env.example vers .env pour préconfigurer Ferret.

La plupart des paramètres du fournisseur d'IA peuvent également être configurés depuis l'assistant de configuration.

Fournisseurs d'IA pris en charge

La configuration du fournisseur peut être effectuée depuis l'assistant de première exécution.

Commandes just

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

Toutes les données persistantes sont stockées sous :

${FERRET_DATA_DIR:-./data}

Ferret utilise des montages par liaison plutôt que des volumes Docker nommés.

Réinitialisation de Ferret

Pour effacer l'état local et redémarrer l'assistant de configuration :

just reset

Cela supprime la base de données locale, y compris les identifiants.

Vous pouvez également réinitialiser la configuration via l'API lorsque vous êtes authentifié :

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

Développement

Pour le développement local de l'interface avec rechargement à chaud :

just dev

Cette commande exécute les conteneurs API et lab dans Docker tout en servant l'interface sur l'hôte via npm run dev. Node.js est requis sur l'hôte pour ce mode.

Exécutez les tests avec :

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

Sécurité

Ferret est conçu pour les flux de travail de tests de sécurité locaux et n'est pas durci pour une exposition publique.

Risques

Avant d'exposer Ferret en dehors de localhost, comprenez ce qui suit :

Utilisez un mot de passe fort et activez la 2FA depuis la page Paramètres.

Signaler une vulnérabilité

N'ouvrez pas de ticket public pour les vulnérabilités de sécurité.

Consultez .github/SECURITY.md pour la politique de divulgation complète et les instructions de signalement.

Rapports divulgués

Les divulgations passées sont publiées dans security/ dès que des correctifs sont disponibles.

Remerciements

Merci aux chercheurs suivants pour avoir divulgué de manière responsable des problèmes de sécurité :

Contribuer

Ferret est activement développé.

Les idées, les rapports de bogues, les demandes de fonctionnalités et les contributions sont les bienvenus.

Vous voulez aider à le construire ?

E-mail : [email protected]

Licence

MIT - voir LICENSE.