[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81378":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":34,"discoverSource":35},81378,"ferret","synlace\u002Fferret","synlace","The collaborative web app pentest suite","https:\u002F\u002Fsynlace.ai",null,"TypeScript",50,2,1,0,10,12,30,67.63,"MIT License",false,"main",true,[25,26,27,28,29,30],"http","http2","man-in-the-middle","mitm-proxy","proxy","security","2026-06-12 04:01:33","# Ferret\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fferret.png\" alt=\"Ferret\" width=\"96\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>The collaborative MITM proxy for security testers.\u003C\u002Fstrong>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  Capture HTTP traffic, annotate requests with AI, run hunt sessions, replay traffic, and track findings from one interface.\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsynlace\u002Fferret\u002Freleases\u002Flatest\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fsynlace\u002Fferret?label=Release&color=brightgreen\" alt=\"Latest Release\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FeF4KQNWKzk\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1504495834266599424?logo=discord&label=Discord&color=5865F2\" alt=\"Discord\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"LICENSE\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fsynlace\u002Fferret?label=License\" alt=\"License: MIT\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsynlace\u002Fferret\u002Factions\u002Fworkflows\u002Fpublish-release.yml\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fsynlace\u002Fferret\u002Fpublish-release.yml?label=Build&logo=github\" alt=\"Build Status\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsynlace\u002Fferret\u002Fpkgs\u002Fcontainer\u002Fferret\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocker-GHCR-2496ED?logo=docker\" alt=\"Docker on GHCR\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fsynlace\u002Fferret\u002Fstargazers\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fsynlace\u002Fferret?style=flat&label=Stars&color=FFD700&logo=github\" alt=\"GitHub Stars\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#quick-start\">Quick start\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#features\">Features\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#screenshots\">Screenshots\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#configuration\">Configuration\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#security\">Security\u003C\u002Fa>\n  ·\n  \u003Ca href=\"#contributing\">Contributing\u003C\u002Fa>\n\u003C\u002Fp>\n\n---\n\n## Quick start\n\n### Install\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fsynlace\u002Fferret.git\ncd ferret\n\ncp .env.example .env   # optional\njust up\n```\n\nOr use Docker Compose directly:\n\n```bash\ndocker compose up --build -d\n```\n\n### Open Ferret\n\n| Service | URL                     |\n| ------- | ----------------------- |\n| UI      | `http:\u002F\u002Flocalhost:3000` |\n| API     | `http:\u002F\u002Flocalhost:8000` |\n| Proxy   | `127.0.0.1:1337`        |\n\nOpen:\n\n```text\nhttp:\u002F\u002Flocalhost:3000\n```\n\nThe first-run setup wizard will ask you to set a password and choose an AI provider.\n\n### Requirements\n\n* Docker\n* Docker Compose\n* [`just`](https:\u002F\u002Fgithub.com\u002Fcasey\u002Fjust)\n\n---\n\n## Overview\n\nFerret is an AI-assisted HTTP interception proxy built for security testers.\n\nPoint your browser, CLI tool, or testing workflow at:\n\n```text\n127.0.0.1:1337\n````\n\nFerret captures requests and responses, stores them locally, annotates traffic with AI, and gives you tools to replay, modify, test, and turn interesting behaviour into findings.\n\nIt is designed for workflows where you want more than a passive proxy: you want something that helps you think, test, and document as you go.\n\n---\n\n## Features\n\n| Feature | Description |\n|---|---|\n| **Intercepting proxy** | Capture HTTP and HTTPS traffic through mitmproxy. |\n| **Request history** | Browse, filter, inspect, and replay captured traffic. |\n| **AI annotations** | Enrich requests with security-relevant context. |\n| **Hunts** | Run AI-assisted hunt sessions across captured traffic. |\n| **Findings** | Track vulnerabilities with severity, host, type, evidence, and status. |\n| **Snare** | Intercept and modify requests or responses in-flight. |\n| **Gnaw** | Repeater-style tabs for editing and resending HTTP requests. |\n| **Workspaces** | Per-session `scripts\u002F`, `tests\u002F`, and `notes\u002F` directories. |\n| **Projects** | Separate request history, findings, workspaces, and API keys. |\n| **Authentication** | Password login, session cookies, optional API key access, and TOTP 2FA. |\n| **Local-first storage** | SQLite-backed data stored in a local bind-mounted directory. |\n\n---\n\n## Screenshots\n\n![Hunts](assets\u002F20260518_hunts.png)\n\n**Hunts** - AI-assisted hunt sessions that search request history, write and run tests, and create findings.\n\n---\n\n![History](assets\u002F20260518_history.png)\n\n**History** - A full proxied request log with AI annotations, timings, status codes, and inline request\u002Fresponse editors.\n\n---\n\n![Findings](assets\u002F20260518_findings.png)\n\n**Findings** - A vulnerability tracker with severity, host, type, AI-generated descriptions, and evidence snippets.\n\n---\n\n![Settings](assets\u002F20260518_settings.png)\n\n**Settings** - Manage the CA certificate, password, 2FA, AI provider, API keys, and proxy status.\n\n---\n\n![Setup](assets\u002F20260518_setup.png)\n\n**Setup wizard** - First-run setup for password creation and AI provider configuration.\n\n---\n\n## Using the proxy\n\nConfigure your browser, CLI tool, or test client to use:\n\n```text\nHTTP proxy:  127.0.0.1:1337\nHTTPS proxy: 127.0.0.1:1337\n```\n\nFor HTTPS interception, download and install the mitmproxy CA certificate from the **Settings** page.\n\n---\n\n## Authentication\n\nFerret requires authentication on every install.\n\n### Browser login\n\n1. Open the UI for the first time.\n2. Set a password in the setup wizard.\n3. Complete AI provider setup.\n4. Log in at `\u002Flogin`.\n5. Ferret issues a 24-hour `HttpOnly` `SameSite=Strict` session cookie.\n\n### Two-factor authentication\n\nTOTP-based 2FA can be enabled from the **Settings** page.\n\nOnce enabled, a valid authenticator code is required at login.\n\n### API access\n\nSet a static API key in `.env`:\n\n```env\nFERRET_API_KEY=your-random-secret\n```\n\nThen use it as a Bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-random-secret\" \\\n  http:\u002F\u002Flocalhost:8000\u002Fapi\u002Frequests\n```\n\nSession cookies and Bearer tokens are checked independently.\n\n---\n\n## Configuration\n\nCopy `.env.example` to `.env` to preconfigure Ferret.\n\nMost AI provider settings can also be configured from the setup wizard.\n\n| Variable                 |                         Default | Description                                     |\n| ------------------------ | ------------------------------: | ----------------------------------------------- |\n| `FERRET_API_KEY`         |                               - | Static Bearer token for programmatic API access |\n| `OPENROUTER_MODEL`       | `google\u002Fgemini-3-flash-preview` | Default OpenRouter model                        |\n| `PROXY_HOST`             |                       `0.0.0.0` | Proxy bind address                              |\n| `PROXY_PORT`             |                          `1337` | Proxy port                                      |\n| `UI_PORT`                |                          `3000` | UI port                                         |\n| `FERRET_DATA_DIR`        |                        `.\u002Fdata` | Persistent data directory                       |\n| `NEXT_PUBLIC_API_URL`    |         `http:\u002F\u002Flocalhost:8000` | API URL used by the browser                     |\n| `NEXT_PUBLIC_SIGINT_URL` |                               - | Optional SIGINT\u002Fnews feed JSON URL              |\n\n---\n\n## Supported AI providers\n\n| Provider | Type |\n|---|---|\n| [OpenRouter](https:\u002F\u002Fopenrouter.ai) | Cloud - unified API across many models |\n| [OpenAI](https:\u002F\u002Fplatform.openai.com) | Cloud - GPT-4o, o1, and others |\n| [Anthropic](https:\u002F\u002Fwww.anthropic.com) | Cloud - Claude models |\n| [Gemini](https:\u002F\u002Fai.google.dev) | Cloud - Google Gemini models |\n| [DeepSeek](https:\u002F\u002Fwww.deepseek.com) | Cloud - DeepSeek models |\n| [Mistral](https:\u002F\u002Fmistral.ai) | Cloud - Mistral models |\n| [Ollama](https:\u002F\u002Follama.com) | Local - run models on your machine |\n| [LM Studio](https:\u002F\u002Flmstudio.ai) | Local - run models on your machine |\n\nProvider setup can be completed from the first-run wizard.\n\n---\n\n## `just` commands\n\n| Command              | Description                                              |\n| -------------------- | -------------------------------------------------------- |\n| `just up`            | Pull pre-built images from GHCR and start all services   |\n| `just down`          | Stop all services                                        |\n| `just dev`           | Run API\u002Flab in Docker and UI hot reload on host (requires Node.js) |\n| `just logs`          | Tail service logs                                        |\n| `just test api`      | Run API unit tests (inside the running api container)    |\n| `just test ui`       | Run Playwright UI tests                                  |\n| `just test shim`     | Run docker-shim allow\u002Fblock unit tests (no Docker needed) |\n| `just test all`      | Run all test suites in sequence                          |\n| `just reset`         | Wipe the local database                                  |\n| `just shell`         | Open a shell in the lab container                        |\n\n---\n\n## Architecture\n\n```text\nBrowser \u002F tool\n      │\n      ▼\n127.0.0.1:1337\n      │\n      ▼\nferret-api :8000 \u002F :1337\nFastAPI + mitmproxy + SQLite\n      │\n      ├── docker exec\n      ▼\nferret-lab\npytest, ffuf, sqlmap, scripts, tests, notes\n      │\n      ▼\nferret-ui :3000\nNext.js\n```\n\nAll persistent data is stored under:\n\n```text\n${FERRET_DATA_DIR:-.\u002Fdata}\n```\n\nFerret uses bind mounts rather than named Docker volumes.\n\n---\n\n## Resetting Ferret\n\nTo wipe local state and restart the setup wizard:\n\n```bash\njust reset\n```\n\nThis removes the local database, including credentials.\n\nYou can also reset setup through the API when authenticated:\n\n```bash\ncurl -X DELETE \\\n  -H \"Authorization: Bearer your-random-secret\" \\\n  http:\u002F\u002Flocalhost:8000\u002Fapi\u002Fsetup\n```\n\n---\n\n## Development\n\nFor local UI development with hot reload:\n\n```bash\njust dev\n```\n\nThis runs the API and lab containers in Docker while serving the UI on the host via `npm run dev`. **Node.js is required on the host** for this mode.\n\nRun tests with:\n\n```bash\njust test api    # API unit tests (inside the running api container)\njust test ui     # Playwright UI tests (auto-starts Next.js dev server + mock API)\njust test shim   # docker-shim allow\u002Fblock unit tests (no Docker needed)\njust test all    # run all three suites in sequence\n```\n\n---\n\n## Security\n\nFerret is designed for local security testing workflows and is not hardened for public exposure.\n\n### Risks\n\nBefore exposing Ferret outside localhost, understand the following:\n\n| Risk | Detail |\n|---|---|\n| Proxy traffic | The proxy captures all HTTP\u002FHTTPS traffic passing through it, including credentials. |\n| API exposure | The API exposes request history, findings, and workspace files. |\n| Lab execution | The lab container can execute testing tools on your behalf. |\n| Credentials | API keys and AI provider credentials are stored locally and should be treated as secrets. |\n\nUse a strong password and enable 2FA from the Settings page.\n\n### Reporting a vulnerability\n\n**Do not open a public issue for security vulnerabilities.**\n\nSee [`.github\u002FSECURITY.md`](.github\u002FSECURITY.md) for the full disclosure policy and reporting instructions.\n\n### Disclosed reports\n\nPast disclosures are published in [`security\u002F`](security\u002FREADME.md) once fixes are available.\n\n### Acknowledgements\n\nThanks to the following researchers for responsibly disclosing security issues:\n\n| Researcher | Issue | Year |\n|---|---|---|\n| Trent ([@AzureADTrent](https:\u002F\u002Fgithub.com\u002FAzureADTrent)) | [DISC-2026-001](security\u002FDISC-2026-001.md) - Unauthenticated RCE via SSRF + docker-socket-proxy misconfiguration | 2026 |\n\n---\n\n## Contributing\n\nFerret is actively being developed.\n\nIdeas, bug reports, feature requests, and contributions are welcome.\n\nWant to help build it?\n\nEmail: [aidan@synlace.ai](mailto:aidan@synlace.ai)\n\n---\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n","Ferret 是一个面向安全测试人员的现代化HTTP代理工具。它能够拦截HTTP和HTTPS流量，利用AI技术对请求进行注释，并提供捕获、重放、修改流量以及记录发现的功能。该工具使用TypeScript编写，支持Docker部署，具有用户友好的界面，方便测试者从单一平台完成多种操作。适用于需要主动分析网络流量以识别潜在安全问题的场景，如渗透测试或应用程序安全审查过程中。","2026-06-11 04:04:50","CREATED_QUERY"]