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는 보안 테스터를 위해 구축된 AI 지원 HTTP 인터셉션 프록시입니다.

브라우저, CLI 도구 또는 테스트 워크플로를 다음으로 지정하세요:

127.0.0.1:1337

Ferret는 요청과 응답을 캡처하고, 로컬에 저장하며, AI로 트래픽에 주석을 달고, 재생, 수정, 테스트 및 흥미로운 동작을 결과로 전환할 수 있는 도구를 제공합니다.

수동 프록시보다 더 많은 기능을 원하는 워크플로를 위해 설계되었습니다: 생각하고, 테스트하고, 문서화하는 데 도움을 주는 무언가를 원하는 경우에 적합합니다.

기능

스크린샷

헌트 - 요청 기록을 검색하고, 테스트를 작성 및 실행하며, 발견 항목을 생성하는 AI 지원 헌트 세션입니다.

기록 - AI 주석, 타이밍, 상태 코드 및 인라인 요청/응답 편집기가 포함된 전체 프록시 요청 로그입니다.

발견 항목 - 심각도, 호스트, 유형, AI 생성 설명 및 증거 조각이 포함된 취약점 추적기입니다.

설정 - CA 인증서, 비밀번호, 2FA, AI 공급자, API 키 및 프록시 상태를 관리합니다.

설정 마법사 - 비밀번호 생성 및 AI 공급자 구성을 위한 첫 실행 설정입니다.

프록시 사용

브라우저, CLI 도구 또는 테스트 클라이언트를 다음으로 구성하세요:

HTTP 프록시:  127.0.0.1:1337
HTTPS 프록시: 127.0.0.1:1337

HTTPS 인터셉션을 위해 설정 페이지에서 mitmproxy CA 인증서를 다운로드하여 설치하세요.

인증

Ferret는 모든 설치에서 인증을 요구합니다.

브라우저 로그인

1. UI를 처음 엽니다.
2. 설정 마법사에서 비밀번호를 설정합니다.
3. AI 공급자 설정을 완료합니다.
4. /login에서 로그인합니다.
5. Ferret는 24시간 유효한 HttpOnly SameSite=Strict 세션 쿠키를 발급합니다.

이중 인증

TOTP 기반 2FA는 설정 페이지에서 활성화할 수 있습니다.

활성화되면 로그인 시 유효한 인증자 코드가 필요합니다.

API 액세스

.env에 정적 API 키를 설정하세요:

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는 명명된 Docker 볼륨 대신 바인드 마운트를 사용합니다.

Ferret 재설정

로컬 상태를 초기화하고 설정 마법사를 다시 시작하려면:

just reset

이렇게 하면 자격 증명을 포함한 로컬 데이터베이스가 제거됩니다.

인증된 상태에서 API를 통해 설정을 재설정할 수도 있습니다:

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

개발

핫 리로드가 포함된 로컬 UI 개발의 경우:

just dev

이렇게 하면 Docker에서 API 및 랩 컨테이너를 실행하는 동시에 호스트에서 npm run dev를 통해 UI를 제공합니다. 이 모드에서는 호스트에 Node.js가 필요합니다.

다음으로 테스트를 실행하세요:

just test api    # API 단위 테스트 (실행 중인 api 컨테이너 내부)
just test ui     # Playwright UI 테스트 (Next.js 개발 서버 + 모의 API 자동 시작)
just test shim   # docker-shim 허용/차단 단위 테스트 (Docker 불필요)
just test all    # 세 스위트를 모두 순차 실행

보안

Ferret는 로컬 보안 테스트 워크플로를 위해 설계되었으며 공개 노출에 대해 강화되지 않았습니다.

위험

Ferret를 localhost 외부에 노출하기 전에 다음을 이해하십시오:

강력한 비밀번호를 사용하고 설정 페이지에서 2FA를 활성화하세요.

취약점 보고

보안 취약점에 대해 공개 이슈를 열지 마십시오.

전체 공개 정책 및 보고 지침은 .github/SECURITY.md를 참조하세요.

공개된 보고서

과거 공개 사항은 수정 사항이 제공된 후 security/에 게시됩니다.

감사의 말

다음 연구원들이 책임감 있게 보안 문제를 공개해 주셨습니다:

기여

Ferret는 활발히 개발 중입니다.

아이디어, 버그 보고서, 기능 요청 및 기여를 환영합니다.

함께 구축하는 데 도움을 주고 싶으신가요?

이메일: [email protected]

라이선스

MIT - LICENSE를 참조하세요.