Ferret

Совместный MITM-прокси для специалистов по безопасности.

Перехватывайте HTTP-трафик, аннотируйте запросы с помощью AI, запускайте сессии охоты, воспроизводите трафик и отслеживайте находки в одном интерфейсе.

Быстрый старт · Возможности · Скриншоты · Конфигурация · Безопасность · Участие в разработке

Быстрый старт

Установка

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

cp .env.example .env   # необязательно
just up

Или используйте Docker Compose напрямую:

docker compose up --build -d

Открыть Ferret

Откройте:

http://localhost:3000

Мастер первоначальной настройки попросит вас установить пароль и выбрать AI-провайдера.

Требования

• Docker
• Docker Compose
• just

Обзор

Ferret — это HTTP-прокси для перехвата трафика с поддержкой AI, созданный для специалистов по безопасности.

Направьте браузер, CLI-инструмент или рабочий процесс тестирования на:

127.0.0.1:1337

Ferret перехватывает запросы и ответы, хранит их локально, аннотирует трафик с помощью AI и предоставляет инструменты для повторной отправки, модификации, тестирования и преобразования интересного поведения в находки.

Он предназначен для рабочих процессов, где вам нужно больше, чем пассивный прокси: инструмент, который помогает думать, тестировать и документировать по ходу дела.

Возможности

Скриншоты

Hunts — AI-ассистированные сессии охоты, которые ищут в истории запросов, пишут и запускают тесты и создают находки.

History — полный журнал проксированных запросов с AI-аннотациями, временем, кодами статуса и встроенными редакторами запросов/ответов.

Findings — трекер уязвимостей с уровнем критичности, хостом, типом, AI-сгенерированными описаниями и фрагментами доказательств.

Settings — управление CA-сертификатом, паролем, 2FA, AI-провайдером, API-ключами и статусом прокси.

Мастер настройки — первоначальная настройка пароля и конфигурация AI-провайдера.

Использование прокси

Настройте браузер, CLI-инструмент или тестовый клиент на использование:

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

Для перехвата HTTPS загрузите и установите CA-сертификат mitmproxy со страницы Настройки.

Аутентификация

Ferret требует аутентификации при каждой установке.

Вход через браузер

1. Откройте интерфейс в первый раз.
2. Установите пароль в мастере настройки.
3. Завершите настройку AI-провайдера.
4. Войдите по адресу /login.
5. Ferret выдаёт 24-часовую сессионную куку с флагами HttpOnly и SameSite=Strict.

Двухфакторная аутентификация

2FA на основе TOTP можно включить на странице Настройки.

После включения при входе требуется действующий код аутентификатора.

Доступ по API

Установите статический API-ключ в файле .env:

FERRET_API_KEY=your-random-secret

Затем используйте его как Bearer-токен:

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

Сессионные куки и Bearer-токены проверяются независимо.

Конфигурация

Скопируйте .env.example в .env для предварительной настройки Ferret.

Большинство настроек AI-провайдеров также можно настроить через мастер установки.

Поддерживаемые AI-провайдеры

Настройка провайдера может быть выполнена через мастер первоначальной настройки.

Команды just

Архитектура

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

Все постоянные данные хранятся в:

${FERRET_DATA_DIR:-./data}

Ferret использует bind-монтирования, а не именованные тома Docker.

Сброс Ferret

Чтобы очистить локальное состояние и перезапустить мастер настройки:

just reset

Это удалит локальную базу данных, включая учётные данные.

Вы также можете сбросить настройки через API при аутентификации:

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

Разработка

Для локальной разработки UI с горячей перезагрузкой:

just dev

Это запускает контейнеры API и lab в Docker, а UI обслуживается на хосте через npm run dev. Для этого режима на хосте требуется Node.js.

Запустите тесты с помощью:

just test api    # Модульные тесты API (внутри работающего контейнера api)
just test ui     # UI-тесты Playwright (автоматически запускает dev-сервер Next.js + мок API)
just test shim   # Модульные тесты docker-shim allow/block (не требуется Docker)
just test all    # Запустить все три набора последовательно

Безопасность

Ferret предназначен для локальных рабочих процессов тестирования безопасности и не защищён для публичного доступа.

Риски

Прежде чем открывать Ferret за пределами localhost, ознакомьтесь со следующим:

Используйте надёжный пароль и включите 2FA на странице Настройки.

Сообщение об уязвимости

Не открывайте публичный issue для уязвимостей безопасности.

См. .github/SECURITY.md для полной политики раскрытия и инструкций по сообщению.

Раскрытые отчёты

Прошлые раскрытия публикуются в security/ после выхода исправлений.

Благодарности

Благодарим следующих исследователей за ответственное раскрытие проблем безопасности:

Участие в разработке

Ferret активно разрабатывается.

Идеи, отчёты об ошибках, предложения по функциям и вклад приветствуются.

Хотите помочь в его создании?

Email: [email protected]

Лицензия

MIT — см. LICENSE.