Ferret

El proxy MITM colaborativo para testers de seguridad.

Captura tráfico HTTP, anota solicitudes con IA, ejecuta sesiones de caza, reproduce tráfico y realiza un seguimiento de los hallazgos desde una única interfaz.

Inicio rápido · Características · Capturas de pantalla · Configuración · Seguridad · Contribuciones

Inicio rápido

Instalación

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

cp .env.example .env   # optional
just up

O usa Docker Compose directamente:

docker compose up --build -d

Abrir Ferret

Abre:

http://localhost:3000

El asistente de configuración inicial te pedirá establecer una contraseña y elegir un proveedor de IA.

Requisitos

• Docker
• Docker Compose
• just

Resumen

Ferret es un proxy de interceptación HTTP asistido por IA, diseñado para testers de seguridad.

Apunta tu navegador, herramienta CLI o flujo de pruebas a:

127.0.0.1:1337

Ferret captura solicitudes y respuestas, las almacena localmente, anota el tráfico con IA y te ofrece herramientas para reproducir, modificar, probar y convertir comportamientos interesantes en hallazgos.

Está diseñado para flujos de trabajo en los que quieres algo más que un proxy pasivo: quieres algo que te ayude a pensar, probar y documentar mientras avanzas.

Características

Capturas de pantalla

Hunts - Sesiones de caza asistidas por IA que buscan en el historial de solicitudes, escriben y ejecutan pruebas, y crean hallazgos.

History - Registro completo de solicitudes proxyadas con anotaciones de IA, tiempos, códigos de estado y editores de solicitudes/respuestas en línea.

Findings - Rastreador de vulnerabilidades con severidad, host, tipo, descripciones generadas por IA y fragmentos de evidencia.

Settings - Gestiona el certificado CA, la contraseña, la 2FA, el proveedor de IA, las claves de API y el estado del proxy.

Asistente de configuración - Configuración inicial para crear la contraseña y el proveedor de IA.

Uso del proxy

Configura tu navegador, herramienta CLI o cliente de pruebas para usar:

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

Para la interceptación HTTPS, descarga e instala el certificado CA de mitmproxy desde la página de Settings.

Autenticación

Ferret requiere autenticación en cada instalación.

Inicio de sesión en el navegador

1. Abre la interfaz por primera vez.
2. Establece una contraseña en el asistente de configuración.
3. Completa la configuración del proveedor de IA.
4. Inicia sesión en /login.
5. Ferret emite una cookie de sesión HttpOnly SameSite=Strict con una validez de 24 horas.

Autenticación de dos factores

La 2FA basada en TOTP puede habilitarse desde la página de Settings.

Una vez habilitada, se requiere un código de autenticador válido al iniciar sesión.

Acceso a la API

Establece una clave de API estática en .env:

FERRET_API_KEY=your-random-secret

Luego úsala como token Bearer:

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

Las cookies de sesión y los tokens Bearer se verifican de forma independiente.

Configuración

Copia .env.example a .env para preconfigurar Ferret.

La mayoría de los ajustes del proveedor de IA también pueden configurarse desde el asistente de configuración.

Proveedores de IA compatibles

La configuración del proveedor puede completarse desde el asistente de primera ejecución.

Comandos just

Arquitectura

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

Todos los datos persistentes se almacenan en:

${FERRET_DATA_DIR:-./data}

Ferret usa bind mounts en lugar de volúmenes Docker con nombre.

Restablecer Ferret

Para borrar el estado local y reiniciar el asistente de configuración:

just reset

Esto elimina la base de datos local, incluidas las credenciales.

También puedes restablecer la configuración a través de la API cuando estés autenticado:

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

Desarrollo

Para el desarrollo local de la UI con recarga en caliente:

just dev

Esto ejecuta los contenedores de API y lab en Docker mientras sirve la UI en el host mediante npm run dev. Se requiere Node.js en el host para este modo.

Ejecuta las pruebas con:

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

Seguridad

Ferret está diseñado para flujos de trabajo de pruebas de seguridad locales y no está endurecido para exposición pública.

Riesgos

Antes de exponer Ferret fuera de localhost, ten en cuenta lo siguiente:

Usa una contraseña segura y habilita la 2FA desde la página de Settings.

Reportar una vulnerabilidad

No abras un issue público para vulnerabilidades de seguridad.

Consulta .github/SECURITY.md para conocer la política de divulgación completa y las instrucciones para reportar.

Informes divulgados

Las divulgaciones anteriores se publican en security/ una vez que los parches están disponibles.

Agradecimientos

Gracias a los siguientes investigadores por divulgar responsablemente problemas de seguridad:

Contribuciones

Ferret está en desarrollo activo.

Las ideas, informes de errores, solicitudes de funciones y contribuciones son bienvenidos.

¿Quieres ayudar a construirlo?

Correo electrónico: [email protected]

Licencia

MIT - consulta LICENSE.