Skip to content

v1.6.2

Choose a tag to compare

View all tags
@synlace synlace released this 22 May 10:15
· 89 commits to main since this release
v1.6.2
07c7a92

What's new in v1.6.2

This is the first public release of Ferret - an AI-assisted HTTP interception proxy for security testers.

Ferret runs entirely in Docker. Clone the repo and run just up to get started.

🚀 Quick start

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

Open http://localhost:3000. The setup wizard will guide you through password creation and AI provider configuration.

✨ Features

Intercepting proxy & traffic analysis

  • Full HTTP/HTTPS interception via mitmproxy on 127.0.0.1:1337
  • Request history with filtering, search, and inline CodeMirror editors (HTTP wire format, language detection)
  • AI annotations — enrich captured requests with security-relevant context
  • Gnaw — repeater-style tabs for editing and resending requests
  • Snare — intercept and modify requests or responses in-flight; two-phase hold (request → response); drop kills the TCP connection; rule-based filtering by host, path, method, and body pattern

AI-assisted hunts

  • Agentic hunt sessions powered by LiteLLM — unified routing across OpenRouter, Anthropic, Gemini, Ollama, LM Studio, and 100+ providers
  • Tools: search_requests, get_request_detail, create_finding, write_test, run_test, list_sources, read_source, and more
  • Per-session tool enable/disable with bulk actions; disabled tools are blocked at execution time
  • Model chain-of-thought reasoning extracted and rendered as collapsible "💭 Thinking" sections
  • Token usage (prompt ↑ / completion ↓) and cost displayed in the context panel after each exchange
  • Non-standard tool call parsing for local models (Kimi/Moonshot, Gemma 4) that do not honour the OpenAI function-calling schema
  • Hunt export to JSON including provider, model, and session metadata

Findings

  • Vulnerability tracker with severity (critical/high/medium/low/info), host, type, AI-generated descriptions, and evidence snippets
  • Average cost-per-finding stat in the findings stats bar

Projects & sources

  • Separate request history, findings, workspaces, and API keys per project
  • Sources — attach reference files (API docs, OpenAPI specs, source code, notes) to a project; the AI agent consults them automatically before analysing traffic
  • Per-project model override; falls through to the setup-wizard model when unset

Authentication & security

  • Mandatory password authentication on every install; bcrypt-hashed credentials in SQLite
  • 24-hour HttpOnly SameSite=Lax session cookies
  • TOTP-based 2FA — enable from Settings; QR code for authenticator app; two-phase login flow
  • Optional static FERRET_API_KEY Bearer token for programmatic/CI access
  • Change password from Settings (invalidates all sessions)

Infrastructure

  • Pre-built GHCR images: ferret-api, ferret-ui, ferret-docker-shim, ferret-lab
  • just up pulls images and starts all services — no Node.js or Python required on the host
  • just dev for hot-reload development (API via watchfiles, UI via npm run dev)
  • Docker socket replaced with tecnativa/docker-socket-proxy — only CONTAINERS, EXEC, and POST operations permitted; image pull, volume mount, and privileged container creation are denied
  • extra_hosts: host-gateway on API and lab containers for local AI provider reachability (Ollama, LM Studio)
  • API hot reload in dev via watchfiles with WATCHFILES_FORCE_POLLING=true for reliable bind-mount change detection

Setup wizard

  • First-run wizard: password → AI provider → model → done
  • Supports OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Ollama, LM Studio
  • Model list fetched server-side via POST /api/setup/models (no browser-direct requests to local providers)
  • Re-run wizard at any time from Settings

Testing

  • 142 Playwright UI tests covering all major pages and flows
  • API unit tests: auth, MFA, chat/LiteLLM, tools, projects, workspaces, sources, security, plans
  • Docker-shim allow/block unit tests (no Docker required)
  • just test all runs all three suites in sequence

🔒 Security fixes

  • CORS restricted from wildcard to http://localhost:{UI_PORT} — prevents cross-origin reads of proxy traffic and stored keys
  • WebSocket origin check — closes with code 1008 for any non-localhost origin
  • Path traversal closed in GET/PUT /api/tests/files/{filename} — paths resolved before read/write
  • CSRF guards on DELETE /api/projects/reset and DELETE /api/projects/all via ?confirm=destroy
  • Error detail scrubbing — all except blocks use deps.server_error(e); stack traces, file paths, and DB messages no longer reach the client
  • Docker socket proxy — replaces direct socket mount; image pull, volume create, and network create are blocked

See security/DISC-2026-001.md for the critical unauthenticated RCE disclosure (fixed in this release). Thanks to Trent (@AzureADTrent) for responsible disclosure.

🐳 Docker images

Image Tag
ghcr.io/synlace/ferret-api v1.6.2, latest
ghcr.io/synlace/ferret-ui v1.6.2, latest
ghcr.io/synlace/ferret-docker-shim v1.6.2, latest
ghcr.io/synlace/ferret-lab v1.6.2, latest

📋 Requirements

  • Docker
  • Docker Compose
  • just
Assets 2
Loading