[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82857":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":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":13,"stars30d":13,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":13,"rankGlobal":10,"rankLanguage":10,"license":14,"archived":15,"fork":15,"defaultBranch":16,"hasWiki":17,"hasPages":15,"topics":18,"createdAt":10,"pushedAt":10,"updatedAt":19,"readmeContent":20,"aiSummary":21,"trendingCount":13,"starSnapshotCount":13,"syncStatus":22,"lastSyncTime":23,"discoverSource":24},82857,"Fennec","Fennec-AI\u002FFennec","Fennec-AI","Open-source, AI-driven penetration testing framework.","https:\u002F\u002Ffenneclabs.ai",null,"Python",52,0,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:04:28","\u003Cp align=\"center\">\n  \u003Cimg src=\"cli\u002Fart\u002Ffennec.png\" alt=\"Fennec — Red Team Fennec\" width=\"600\">\n\u003C\u002Fp>\n\n# Fennec\n\n**Open-source, AI-driven penetration testing. Point it at a target you control, and a fleet of agents will recon, hypothesize, exploit, and report — autonomously.**\n\n[**🌐 Hosted version: fenneclabs.ai**](https:\u002F\u002Ffenneclabs.ai) — managed runner, team features, persistent jobs. Join the waitlist there if you'd rather not self-host.\n\n> **Authorized testing only.** Fennec is built to assist security testing against systems you own or have explicit written permission to assess. Don't point it at anything else.\n\n---\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard.png\" alt=\"Fennec Dashboard — Security Overview\" width=\"100%\">\n  \u003Cbr>\u003Cem>Security Overview — the dashboard's landing page. Composite risk score, severity breakdown, target inventory, time-to-fix, and aging findings, all populated from a real scan.\u003C\u002Fem>\n\u003C\u002Fp>\n\n## Why Fennec\n\nMost automated scanners are noise generators. They emit hundreds of \"potential\" CVE matches that a human has to spend a week triaging — most of which are false positives, version-banner mismatches, or unreachable code paths. Fennec is built differently:\n\n- **Every finding is exploitable.** The pentester agent doesn't ship a result until it has reproducible evidence: a request, a payload, the observed response. If the agent couldn't actually trigger the vulnerability, it gets marked `safe` or `inconclusive`, not added to the findings list. There's no CVSS-based guessing.\n- **Hypothesis-driven, not signature-driven.** Recon maps the attack surface. The analyst forms testable hypotheses (\"the `\u002Fapi\u002Fusers\u002F{id}` endpoint may be vulnerable to IDOR because the auth check looks shallow\"). The pentester picks them one at a time and runs targeted tools — not a 1000-rule template sweep. Fewer dead-ends, deeper coverage.\n- **It thinks like an attacker.** The coder sub-agent can write custom exploit payloads when an off-the-shelf tool doesn't fit (encoded JWTs, unusual content types, application-specific bypasses). Most scanners can't do this.\n- **Minutes, not weeks.** A typical scan runs in 5–30 minutes per target depending on the assessment depth (`turbo` \u002F `balanced` \u002F `deep` presets). Findings appear in the dashboard as the agents confirm them.\n- **You see exactly what it did.** Every tool invocation, every response, every reasoning step is captured. Open any finding to inspect the full chain. No black box.\n- **Your data stays local.** No telemetry. No SaaS callback. The agent runs on your laptop, talks to your LLM provider, scans the targets you specify. Findings are stored in-process and exported as JSON \u002F Markdown.\n\nThere is a [hosted version at fenneclabs.ai](https:\u002F\u002Ffenneclabs.ai) with team features, persistent job history, and a managed runner. This open-source repo is the same agent core, stripped of the multi-tenant infrastructure — designed to run on one laptop with one API key.\n\n## Requirements\n\n- Docker Desktop (or Docker Engine ≥ 20.10)\n- An LLM API key — one of **Anthropic** (recommended), **OpenAI**, or **OpenRouter**\n- ~15 GB free disk for the Kali execution image (built once)\n- Python 3.11+ only if you want to skip Docker for the agent itself and run the CLI directly\n\n## Quickstart (one command, after a one-time build)\n\n```bash\ngit clone git@github.com:NabilAziz99\u002FFennec.git\ncd Fennec\n\n# 1. Drop your API key into .env\ncp .env.example .env\necho \"ANTHROPIC_API_KEY=sk-ant-...\" >> .env\n\n# 2. Build the Kali execution image (one-time, ~5 min, ~14 GB)\ncd linux && make build && cd ..\n\n# 3. Bring up the stack\ndocker compose up --build\n```\n\nOpen **http:\u002F\u002Flocalhost:3000** for the dashboard. Backend API is at **http:\u002F\u002Flocalhost:8000** (try `\u002Fhealth`).\n\n> If you only want the CLI and not the dashboard, see [CLI mode](#cli-mode) below.\n\n## CLI — the same agent, in your terminal\n\nIf you live in `tmux` and don't want a browser tab open, the CLI runs the **identical** agent pipeline with a live terminal dashboard that mirrors the web UI's Live Activity surface. It subscribes to the same event stream the FastAPI server publishes to the browser — every `node_update`, `tool_call`, `tool_execution`, `hypothesis_tree`, and `finding` event lands in the rich-rendered layout below.\n\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fcli-dashboard.png\" alt=\"Fennec CLI — live dashboard during a scan\" width=\"100%\">\u003C\u002Fp>\n\nWhat you're looking at, panel by panel:\n\n- **Header** — target, currently-active agent (with glyph), elapsed clock, assessment method.\n- **Hypotheses** (top-left) — the analyst's full attack tree, parent → child. `◈` = in progress (highlighted on the one the pentester is currently hammering), `✖` = confirmed-vulnerable (severity-coloured), `✓` = safe, `◇` = pending. Subtitle shows total \u002F queued.\n- **Live Activity** (centre) — timestamped event stream colour-coded by agent (orange = orchestrator, cyan = recon, purple = analyst, red = pentester, green = coder). Tool calls render with the actual command being executed, results render with a preview of the output.\n- **Latest Tool** (right) — the full command + bash-highlighted args of the most recent tool call, with the result body underneath. Long output is head\u002Ftail truncated so a runaway `find \u002F` doesn't blow out the panel.\n- **Findings** (bottom-left) — running tally by severity, plus recon-stat counters (discovered paths, fingerprinted services).\n- **Footer** — animated spinner while agents are working; turns into a finished\u002Ffailed banner when the run ends.\n\n### Run it\n\nThree ways, depending on how interactive you want to be:\n\n```bash\n# 1. Fully interactive — prompts for target, objective, and method\npython cli.py\n\n# 2. One-shot with a target (still drops you into the live dashboard)\npython cli.py scan --target https:\u002F\u002Fyour-target.example\n\n# 3. Pick a method without prompting\npython cli.py scan --target https:\u002F\u002Fyour-target.example --method deep\n```\n\n`--method` accepts `turbo` \u002F `balanced` \u002F `deep`. Add `--htli` to pause for operator approval before each hypothesis (Human-In-The-Loop mode).\n\nWhen the run finishes, the live view stops repainting and a static summary block prints below it — a findings-by-severity table, per-vulnerability cards with description + OWASP tag, and the orchestrator's final report. Easy to copy\u002Fpaste into a ticket or scrollback.\n\n### Programmatic interface\n\nFor benchmarking, CI checks, or wrapping Fennec in your own tooling, skip the CLI entirely and call the agent directly:\n\n```python\nimport asyncio\nfrom agent import run_pentest, PentestTask, PentestMode\n\nasync def main():\n    task = PentestTask(\n        target_url=\"http:\u002F\u002Flocalhost:8000\",\n        description=\"Find authentication and injection vulnerabilities\",\n        mode=PentestMode.BLACK_BOX,\n        tags=[\"sqli\", \"auth\"],\n    )\n    result = await run_pentest(task)\n    print(f\"Success: {result.success}\")\n    for v in result.vulnerabilities:\n        print(f\"  - {v}\")\n\nasyncio.run(main())\n```\n\n`run_pentest` accepts an optional `event_sink=async_callback` — the same hook the API server uses to push SSE events and the CLI uses to drive the live dashboard. You can wire it into any downstream system (Slack, PagerDuty, a tracing backend, ...) without forking the agent.\n\n### Legacy markdown reports\n\nThe pre-dashboard CLI is still available behind `--legacy`, in case you want the line-buffered output and the `.\u002Freports\u002F\u003Ctimestamp>_\u003Chost>\u002Fsummary.md` markdown bundle the older release wrote:\n\n```bash\npython cli.py scan --target https:\u002F\u002Fyour-target.example --legacy --output .\u002Freports\n```\n\n## Tour\n\nA walk through every page in the dashboard, in the order you'd use them. All screenshots come from the demo seed (`FENNEC_DEMO_SEED=1 docker compose up`) — flip it on yourself to explore without running a real scan.\n\n### Target Inventory — the SaaS surface you've authorised\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-targets.png\" alt=\"Target Inventory — 12 cards\" width=\"100%\">\u003C\u002Fp>\n\nTwelve targets in the demo: production, staging, the API gateway, customer app, admin console, billing service, docs \u002F blog \u002F status \u002F CDN subdomains, an internal demo app, and a legacy 2021 dashboard. Each card shows the last-scan recency and an at-a-glance findings count. **Add Target** registers a new domain, the pencil icon edits, the trash icon removes. Per-target credentials (the QA test user, in our case) stay local — only injected into the agent's runtime container when a scan starts.\n\n### Assessments — what's running, what ran, what's next\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-status.png\" alt=\"Assessments\" width=\"100%\">\u003C\u002Fp>\n\nLive workflow stages at the top light up as the current scan progresses (Assessment Started → Authentication → Reconnaissance → **Testing (Active)** → Validation). Below: any **Active Assessments** (the row with the spinning Cancel button is a Deep pass on production), scheduled jobs, and a chronological **Historical Assessments** table — green dot = succeeded with findings, red dot = failed, with method, credential, start, and end timestamps.\n\n### Assessment detail — Live Activity\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-assessment.png\" alt=\"Assessment detail — Live Activity\" width=\"100%\">\u003C\u002Fp>\n\nDrill into a single scan. The pipeline timeline shows every stage with its completion state, and the four tabs let you see what the agents actually did. **Live Activity** is the per-tool-call stream: `nmap -sV`, `gobuster dir`, `sqlmap` against the login form, `curl` exfiltration probes, `web_search` for related CVEs — every command, every timestamp, who ran it.\n\n### Assessment detail — Hypotheses\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-hypotheses.png\" alt=\"Assessment detail — Hypotheses\" width=\"100%\">\u003C\u002Fp>\n\nThe analyst agent's full claim tree for this scan. Each row is a testable hypothesis (UNION-based SQL injection on `\u002Fapi\u002Fauth\u002Flogin`, IDOR on `\u002Fapi\u002Fusers\u002F{id}`, stored XSS in the support form, ...) with status, severity badge, priority score, and OWASP category. Confirmed-vulnerable, dead-end, and safe verdicts are all kept — the agent shows its work whether or not the hypothesis paid out.\n\n### Assessment detail — Recon Data\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-recon.png\" alt=\"Assessment detail — Recon Data\" width=\"100%\">\u003C\u002Fp>\n\nThe structured attack-surface map the recon agent built before any exploit ran: detected technologies (Nginx 1.25, FastAPI 0.115, PostgreSQL 15.4, React 18.2, Cloudflare, OpenSSH 9.6), every discovered endpoint with parameter list and auth requirement, identified entry points, observed cookies\u002Fheaders, and free-text notes the agent surfaced (\"CSP is report-only\", \"JWT uses HS256 — verify rotation\"). This is what the analyst chews on to form the hypothesis tree above.\n\n### Findings — Description tab (the marquee shot)\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-findings.png\" alt=\"Findings — Description tab\" width=\"100%\">\u003C\u002Fp>\n\nEvery confirmed vulnerability across all scans, severity-sorted in the sidebar. The selected critical-severity finding here is **UNION-based SQL injection on `\u002Fapi\u002Fauth\u002Flogin`** that the agent confirmed via three injection types (error-based, time-based blind, UNION) and used to exfiltrate the first five rows of the `users` table — including bcrypt hashes — via an unintentional `_debug_result` field the application leaked. The Description tab shows the technical breakdown of how the agent found and confirmed the bug.\n\n### Findings — Impact tab\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-finding-impact.png\" alt=\"Findings — Impact\" width=\"100%\">\u003C\u002Fp>\n\n**Demonstrated Impact**, **Attack Scenarios**, **Business Risk** — written for the engineering manager AND the CISO. From the agent: full read access to `users`, `sessions`, `api_keys`, and `billing_accounts`; four concrete pivots (offline hash crack → login as user, session-token replay → admin takeover, credential stuffing prep, API-key exfil); GDPR Article 33 notification trigger; estimated remediation cost.\n\n### Findings — Evidence tab\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-finding-evidence.png\" alt=\"Findings — Evidence\" width=\"100%\">\u003C\u002Fp>\n\nThe receipts. Every confirmation step the agent took, then **Payloads Used** — the exact strings it sent, ready to copy into Burp or a `curl`. No black-box \"we think there's a problem here\" — the payloads either work for you when you paste them or the finding goes in the false-positive bin.\n\n### Findings — Remediation tab\n\u003Cp align=\"center\">\u003Cimg src=\"docs\u002Fscreenshots\u002Fdashboard-finding-remediation.png\" alt=\"Findings — Remediation\" width=\"100%\">\u003C\u002Fp>\n\n**Primary fix** (parametrise the query, strip the `_debug_result` field), **Implementation pattern** (an actual code diff to apply), and **Additional hardening** (WAF rule for defense-in-depth, DB-user least privilege, CI lint to fail builds on f-string SQL, password rotation policy). This is a hand-off the engineering team can act on without translating from security-speak.\n\n### Demo seed mode\n\nThe screenshots above all come from a built-in synthetic seed. To populate the dashboard yourself without running a real scan, set the env var when bringing up the stack:\n\n```bash\nFENNEC_DEMO_SEED=1 docker compose up --build\n```\n\nThe seed creates 12 targets, 17 scans across the last 28 days (one currently running, the rest completed across all severities, one historical failed scan), the full hypothesis tree + tool-call log for the production scan, and 28 findings spread across critical \u002F high \u002F medium \u002F low — including the deep SQL-injection finding shown in the screenshots. It's idempotent: it skips entirely if you already have real scans in the store, so it never collides with a production run.\n\n## Walkthrough — your first scan\n\nOnce the stack is up:\n\n1. **Open the dashboard** at \u003Chttp:\u002F\u002Flocalhost:3000>. You'll land on the Security Overview — empty at first if you skipped `FENNEC_DEMO_SEED`.\n\n2. **Add a target.** Click **Target Inventory** in the sidebar → **Add Target**. Enter a domain you own or have written permission to test (e.g. `http:\u002F\u002Flocalhost:9000` if you're testing a local app, or your own staging URL). The target gets a verification token; click **Verify** (in OSS mode this is auto-trust).\n\n3. **Optional: add credentials.** If your target has a login wall and you want the agent to authenticate, click **Add Credential** on the target. The agent will use these during recon and exploitation. Plaintext stays only in the local Postgres \u002F in-memory store; nothing is sent to the LLM unless the agent needs to construct an authenticated request.\n\n4. **Start a scan.** Click **+ Create** in the sidebar, pick the target, choose a method:\n   - **`turbo`** — short tool budgets, ~5 min, good for smoke-testing a target\n   - **`balanced`** (default) — ~15–30 min, a normal pentest pass\n   - **`deep`** — generous budgets, ~30–60 min, for thorough engagements\n\n   Click **Start Pentest**.\n\n5. **Watch the agents work.** The Status page streams live events: recon results, hypotheses being formed, tool calls (nmap, curl, sqlmap, custom payloads), and findings as they're confirmed. The hypothesis tree shows what's pending \u002F in-progress \u002F vulnerable \u002F safe.\n\n6. **Review findings.** Open **Findings** in the sidebar to see confirmed vulnerabilities grouped by severity. Click any finding to drill into the evidence: the exact request that triggered it, the response observed, the OWASP category, the suggested fix, and the full reasoning trail.\n\n7. **Export.** Each finding has a JSON export. The agents also dump a Markdown report under `.\u002Freports\u002F\u003Ctimestamp>_\u003Chost>\u002Fsummary.md` for the CLI flow.\n\n## Configuration\n\nEverything is `.env`-driven. The knobs that matter:\n\n| Variable | What it does |\n|---|---|\n| `LLM_PROVIDER` | `anthropic` (default), `openai`, or `openrouter` |\n| `LLM_MODEL` | Model name for the provider (default `claude-sonnet-4-20250514`) |\n| `ANTHROPIC_API_KEY` \u002F `OPENAI_API_KEY` \u002F `OPENROUTER_API_KEY` | One must be set, matching `LLM_PROVIDER` |\n| `DOCKER_IMAGE` | Kali image tag (default `fennec-linux`, built by `linux\u002FMakefile`) |\n| `EXECUTION_MODE` | `docker` (default — spawn a Kali sibling per scan) or `local` (run tools in the agent container directly) |\n| `FENNEC_METHOD` | `turbo` \u002F `balanced` \u002F `deep` |\n| `HTLI` | `true` to pause for operator approval between hypotheses |\n| `RECON_MIN_MODEL_CALLS`, `ANALYST_MODEL_CALL_LIMIT`, `PENTESTER_MODEL_CALL_LIMIT` | Per-agent call-budget caps (cost control) |\n| `TAVILY_API_KEY`, `PERPLEXITY_API_KEY` | Optional — enables enhanced web search during recon |\n\n## How it works\n\n```\n┌─────────────┐     ┌──────────────┐     ┌──────────────┐\n│   Recon     │ ──> │   Analyst    │ ──> │ Orchestrator │\n│ (scan tools)│     │ (hypotheses) │     │  (routing)   │\n└─────────────┘     └──────────────┘     └──────┬───────┘\n                                                │\n                                                ▼\n                                         ┌──────────────┐\n                                         │  Pentester   │\n                                         │  (testing)   │\n                                         └──────────────┘\n                                                │\n                            ┌───────────────────┘\n                            ▼\n                     ┌─────────────┐\n                     │    Coder    │   invoked by pentester when\n                     │ (exploits)  │   custom payload is needed\n                     └─────────────┘\n```\n\n- **Recon** maps the attack surface — endpoints, technologies, auth flows. Built on nmap, curl, gobuster, nuclei, subfinder, httpx, and a browser tool.\n- **Analyst** reads recon data and emits a prioritised queue of testable hypotheses tagged with required skills and OWASP category.\n- **Pentester** picks one hypothesis at a time, runs targeted tool calls, and emits a `PentesterResult` (status, verdict, evidence, suggested remediation). Won't fabricate findings — if it can't trigger the vulnerability, the verdict is `safe` or `inconclusive`.\n- **Coder** writes custom exploit code (Python or shell) when the pentester needs something off-the-shelf tools can't do.\n- **Orchestrator** is **not** an LLM. It's pure routing logic: process the last pentester result, update the hypothesis tree, decide what's next.\n\nSee [docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md) for the deeper breakdown — state schema, LangGraph wiring, middleware chain, method presets.\n\n## Differences from the hosted version\n\n| | OSS (this repo) | [fenneclabs.ai](https:\u002F\u002Ffenneclabs.ai) |\n|---|---|---|\n| Auth | None — single user | Team accounts, OAuth |\n| Job persistence | JSON reports \u002F in-memory | Postgres, full history |\n| Queue | One scan at a time | Managed multi-tenant queue |\n| Dashboard | Local | Hosted with sharing |\n| LLM keys | Yours, in `.env` | Managed |\n| Updates | `git pull` | Continuous |\n\nThe agent code itself is identical. Only the surrounding infrastructure differs.\n\n## Project layout\n\n```\n.\n├── agent.py                # Programmatic API: run_pentest(task) → AgentResult\n├── cli.py \u002F cli\u002Fmain.py    # CLI entrypoint\n├── src\u002F\n│   ├── api\u002F                # FastAPI server (server.py, job_store.py, events.py)\n│   ├── agents\u002F             # recon, analyst, pentester, coder, human_review\n│   ├── graph\u002F              # LangGraph wiring + orchestrator routing\n│   ├── tools\u002F              # terminal, browser, file_read\u002Fwrite, web_search\n│   ├── docker\u002F             # aiodocker wrapper that spawns the Kali container\n│   ├── prompts\u002F            # Per-agent system prompts + section composition\n│   ├── schemas\u002F            # Pydantic models for tool I\u002FO\n│   ├── state\u002F              # FennecState TypedDict + hypothesis\u002Ffinding types\n│   ├── middleware\u002F         # LangChain middleware (budget, truncation, retries)\n│   └── orchestration\u002F      # HypothesisManager\n├── linux\u002F                  # Kali Dockerfile + wordlists (`make build`)\n├── frontend\u002F               # React + Vite dashboard (Apache-licensed)\n└── docker-compose.yml\n```\n\n## Contributing\n\nIssues and PRs welcome. Before submitting:\n\n- `python -m py_compile src\u002F**\u002F*.py` should pass\n- New tools belong in `src\u002Ftools\u002F` with a Pydantic input schema\n- New agents need an entry in `AgentType`, a router branch in `src\u002Fgraph\u002F`, and a prompt in `src\u002Fprompts\u002F`\n- Don't add proprietary services, telemetry, or auth gates — OSS stays vendor-neutral\n\n## License\n\n[Apache License 2.0](LICENSE).\n\n## Acknowledgements\n\nBuilt on [LangGraph](https:\u002F\u002Fgithub.com\u002Flangchain-ai\u002Flanggraph), [LangChain](https:\u002F\u002Fgithub.com\u002Flangchain-ai\u002Flangchain), and the [Kali Linux](https:\u002F\u002Fwww.kali.org\u002F) tools ecosystem.\n","Fennec是一个开源的、基于AI驱动的安全渗透测试框架。其核心功能包括通过智能代理自动执行侦察、假设验证、漏洞利用和报告生成，确保每个发现都是可利用的，并且能够自动生成定制化的攻击载荷以适应特定的应用场景。与传统扫描器相比，Fennec采用假设驱动而非签名匹配的方式进行深度探测，减少了误报率并提高了测试效率。它适用于需要对自有系统或已获得授权的第三方系统进行全面安全评估的场景中，特别适合红队成员和技术安全专家使用。此外，Fennec支持本地部署，保证了数据处理过程中的隐私性和安全性。",2,"2026-06-11 04:09:25","CREATED_QUERY"]