Ferret

O proxy MITM colaborativo para testadores de segurança.

Capture o tráfego HTTP, anote requisições com IA, execute sessões de hunt, reproduza tráfego e acompanhe descobertas em uma única interface.

Início rápido · Recursos · Capturas de tela · Configuração · Segurança · Contribuindo

Início rápido

Instalação

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

cp .env.example .env   # opcional
just up

Ou use Docker Compose diretamente:

docker compose up --build -d

Abrir o Ferret

Abra:

http://localhost:3000

O assistente de configuração da primeira execução solicitará que você defina uma senha e escolha um provedor de IA.

Requisitos

• Docker
• Docker Compose
• just

Visão geral

O Ferret é um proxy de interceptação HTTP assistido por IA, criado para testadores de segurança.

Aponte seu navegador, ferramenta de CLI ou fluxo de trabalho de testes para:

127.0.0.1:1337

O Ferret captura requisições e respostas, armazena-as localmente, anota o tráfego com IA e oferece ferramentas para reproduzir, modificar, testar e transformar comportamentos interessantes em descobertas.

Ele foi projetado para fluxos de trabalho em que você deseja mais do que um proxy passivo: você quer algo que ajude a pensar, testar e documentar enquanto avança.

Recursos

Capturas de tela

Hunts - Sessões de hunt assistidas por IA que pesquisam o histórico de requisições, escrevem e executam testes e criam descobertas.

History - Um log completo de requisições com proxy, com anotações de IA, tempos, códigos de status e editores inline de requisição/resposta.

Findings - Um rastreador de vulnerabilidades com severidade, host, tipo, descrições geradas por IA e trechos de evidência.

Settings - Gerencie o certificado da CA, senha, 2FA, provedor de IA, chaves de API e status do proxy.

Setup wizard - Configuração da primeira execução para criação de senha e configuração do provedor de IA.

Usando o proxy

Configure seu navegador, ferramenta de CLI ou cliente de testes para usar:

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

Para interceptação HTTPS, baixe e instale o certificado CA do mitmproxy na página Settings.

Autenticação

O Ferret exige autenticação em todas as instalações.

Login no navegador

1. Abra a interface pela primeira vez.
2. Defina uma senha no assistente de configuração.
3. Conclua a configuração do provedor de IA.
4. Faça login em /login.
5. O Ferret emite um cookie de sessão HttpOnly SameSite=Strict com validade de 24 horas.

Autenticação de dois fatores

A 2FA baseada em TOTP pode ser ativada na página Settings.

Depois de ativada, um código de autenticador válido é exigido no login.

Acesso à API

Defina uma chave de API estática no .env:

FERRET_API_KEY=your-random-secret

Em seguida, use-a como token Bearer:

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

Cookies de sessão e tokens Bearer são verificados de forma independente.

Configuração

Copie .env.example para .env para pré-configurar o Ferret.

A maioria das configurações do provedor de IA também pode ser definida pelo assistente de configuração.

Provedores de IA suportados

A configuração do provedor pode ser concluída pelo assistente da primeira execução.

Comandos do just

Arquitetura

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 os dados persistentes são armazenados em:

${FERRET_DATA_DIR:-./data}

O Ferret usa bind mounts em vez de volumes nomeados do Docker.

Redefinindo o Ferret

Para apagar o estado local e reiniciar o assistente de configuração:

just reset

Isso remove o banco de dados local, incluindo credenciais.

Você também pode redefinir a configuração pela API quando autenticado:

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

Desenvolvimento

Para desenvolvimento local da interface com hot reload:

just dev

Isso executa os containers da API e do lab no Docker enquanto serve a interface no host via npm run dev. Node.js é necessário no host para esse modo.

Execute os testes com:

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

Segurança

O Ferret é projetado para fluxos de trabalho de testes de segurança locais e não é endurecido para exposição pública.

Riscos

Antes de expor o Ferret fora do localhost, entenda o seguinte:

Use uma senha forte e ative a 2FA na página Settings.

Reportando uma vulnerabilidade

Não abra uma issue pública para vulnerabilidades de segurança.

Consulte .github/SECURITY.md para a política de divulgação completa e instruções de reporte.

Relatórios divulgados

Divulgações anteriores são publicadas em security/ assim que as correções estiverem disponíveis.

Agradecimentos

Agradecemos aos seguintes pesquisadores por divulgarem problemas de segurança de forma responsável:

Contribuindo

O Ferret está em desenvolvimento ativo.

Ideias, relatos de bugs, pedidos de recursos e contribuições são bem-vindos.

Quer ajudar a construí-lo?

E-mail: [email protected]

Licença

MIT - consulte LICENSE.