{"slug": "raven-recon-an-open-source-security-research-framework-with-ai-agents", "title": "Raven Recon – An open-source security research framework with AI agents", "summary": "A developer publishing under the GitHub handle 9illcodelli6-cpp69cve released Raven Recon, an open-source, scope-aware reconnaissance and security-testing workbench for bug-bounty hunters and penetration testers that runs on Windows and Kali Linux as a desktop app, local web UI, or terminal. Raven Recon pairs certificate-transparency subdomain discovery, HTTP probing, endpoint discovery from links, robots.txt, sitemaps and JavaScript, and a request lab with an AI agent powered by Claude Opus 5.5 that plans tasks using the tool's playbooks but requires user approval for every request to a target and every command. The tool blocks out-of-scope and private addresses per workspace and adds an Emergency Stop, per-run budget and rate limits, an offline command sandbox on Linux, and encrypted API keys, with official builds distributed only via the repository's Releases page with SHA256SUMS.txt and a GitHub build-provenance attestation.", "body_md": "**Scope-aware reconnaissance and AI-assisted security-testing workbench** — for bug-bounty\nhunters and penetration testers. Runs on **Windows** and **Kali Linux** as a desktop app,\na local web UI, or in the terminal.\n\n**Authorised testing only.** Use RAVEN Recon only on systems you own or have written\npermission to test. Read [`RESPONSIBLE_USE.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/RESPONSIBLE_USE.md) first.\n**العربية:** [README.ar.md](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/README.ar.md)\n\n⚠️ \n\n| AI Agent — every request and command waits for your approval | Recon Workbench — attack surface, request lab, findings | \n|---|---|\n\n| Area | What you get | \n|---|---|\n| **Scope & workspaces** | One workspace per program: in-scope hosts and wildcards, exclusions, ports. Every request RAVEN sends is checked against it; out-of-scope and private addresses are blocked. | \n| **Recon** | Certificate-transparency subdomains, HTTP probing of every scoped port, endpoint discovery from links, `robots.txt` , sitemaps and JavaScript, change tracking between runs, priority scoring. | \n| **Request lab** | Repeater, Intruder (headers, body, baseline anomaly detection), Decoder, HTTP history. | \n| **Labs** | Access-control lab (compare two identities on the same resource) and XSS lab (reflection-context analysis, no script execution). | \n| **Findings & evidence** | Candidate findings with evidence links, review workflow, Markdown workspace report export. | \n| **AI agent** | Claude Opus 5.5 plans and works through a task with RAVEN's tools — **every request to a target and every command waits for your Approve** . Loads RAVEN's testing playbooks (API recon, API security, recon breadth, code audit, patch diff, PHP LFI, browser testing). | \n| **AI chat & terminal** | Ask questions, get payloads and code ( `raven-sec` in the terminal). | \n| **Safety** | Emergency Stop, per-run budget and rate limits, offline command sandbox on Linux, encrypted API key, local-only data. | \n\n**Option A — ready-to-run app (recommended):**\n\n1. Download `RAVEN-Recon-windows-x64.zip` from the[Releases page](https://github.com/9illcodelli6-cpp69cve/raven-recon/releases/latest) .\n2. [Verify it](#verify-your-download) , unzip it, and run`RAVEN.exe` .\n(Windows 10/11 with the Edge WebView2 runtime, which is built into Windows 11.)\n\n**Option B — from source** (needs [Python 3.11+](https://www.python.org/downloads/) — or\n`winget install -e --id Python.Python.3.12` — and [Git](https://git-scm.com/)), in PowerShell:\n\n```\ngit clone https://github.com/9illcodelli6-cpp69cve/raven-recon.git\ncd raven-recon\npowershell -ExecutionPolicy Bypass -File .\\install.ps1\n```\n\nThis creates a private Python environment, a **Start Menu entry**, and the commands\n`raven-recon`, `raven-recon-web` and `raven-sec` (open a new terminal afterwards).\nUninstall: `.\\install.ps1 -Uninstall` (your data is kept).\n\n**Option A — ready-to-run app:**\n\n```\n# download RAVEN-Recon-linux-x64.tar.gz and SHA256SUMS.txt from the Releases page, then:\nsha256sum -c SHA256SUMS.txt --ignore-missing\ntar -xzf RAVEN-Recon-linux-x64.tar.gz\nsudo apt install -y gir1.2-webkit2-4.1 bubblewrap   # own window + command sandbox\n./RAVEN/RAVEN\n```\n\n**Option B — from source (recommended on Kali):**\n\n```\ngit clone https://github.com/9illcodelli6-cpp69cve/raven-recon.git\ncd raven-recon\n./install.sh\n```\n\nThe installer asks before running `sudo apt install` for the few system packages it needs\n(`python3-venv python3-gi gir1.2-webkit2-4.1 bubblewrap`), creates `.venv`, adds\n**RAVEN Recon** to the applications menu and installs the `raven-recon` and `raven-sec`\ncommands in `~/.local/bin`. Uninstall: `./install.sh --uninstall` (your data is kept).\n\nOfficial builds exist **only** on this repository's Releases page. Each release has\n`SHA256SUMS.txt` and a GitHub **build-provenance attestation** proving the file was built by\nthis repository's workflow:\n\n```\nsha256sum -c SHA256SUMS.txt --ignore-missing\ngh attestation verify RAVEN-Recon-linux-x64.tar.gz --repo 9illcodelli6-cpp69cve/raven-recon\n```\n\nWindows: `Get-FileHash .\\RAVEN-Recon-windows-x64.zip -Algorithm SHA256` and compare with\n`SHA256SUMS.txt`. Copies from anywhere else (\"PRO\", \"cracked\", re-uploads) are not official\nand may be malicious.\n\n|  | Windows | Kali / Linux | \n|---|---|---|\n| **Desktop app** (own window) | Start Menu → RAVEN Recon, or `raven-recon` | Menu → RAVEN Recon, or `raven-recon` | \n| **Local web UI** (your browser,`127.0.0.1` only) | `raven-recon-web` | `raven-recon --browser` | \n| **Terminal assistant** | `raven-sec` | `raven-sec` | \n\nThe web UI listens on the loopback interface only and every API call needs a per-session token, so other machines on your network cannot reach it.\n\n1. **Create a workspace** — RAVEN OS sidebar →**Workspace** (or in the Recon Workbench:\nworkspace menu →*new workspace* ). Enter the program name and**exactly the scope the\nprogram allows** : in-scope hosts or wildcards (`*.example.com` ), exclusions, and ports.\nLeave*allow private addresses* off unless it is your own lab.\n2. **Set your identity** — Workbench →**Identity** : the User-Agent and the researcher header\nyour program asks for (for example`X-HackerOne-Research: <your handle>` ).\n3. **Run a collection** — Workbench →**Run collection** : certificate-transparency names,\nHTTP probes on every scoped port, and endpoint discovery. Watch progress in the terminal\npanel; stop any time.\n4. **Review the surface** —**Surface** (hosts ranked by review priority),**Endpoints** ,**Graph** ,**Changes** (what is new since the last run),**Runs** . A score is a review\npriority, never a vulnerability verdict.\n5. **Test by hand** — open a request in**Repeater** , fuzz a parameter in**Intruder** (with a baseline to spot anomalies), compare two accounts in the**Access-control lab** ,\ncheck a reflection in the**XSS lab** , decode tokens in**Decoder** . Everything is in**HTTP history** .\n6. **Use the AI agent (optional)** — add your Claude key (see below), open**AI Agent** , pick*Claude Opus 5.5* , describe the task (e.g.*\"Check /api/orders/{id} for IDOR using my two\ntest accounts\"* ). Read each proposed request or command and**Approve** or**Deny** it.\n7. **Record and report** — the agent and the labs create**candidate** findings; review them\nin**Findings** , then**Export workspace report** (Markdown) and write your own report.\n8. **Stop button** —**Emergency Stop** halts every job, request, agent run and command at\nonce;**Resume** re-enables them.\n9. **Appearance** —**Settings → Appearance** :**Full** (animated artwork background),**Static** (same artwork, no animation — lighter on older machines) or**Off** (plain dark).\nSystems set to*reduce motion* get Static automatically.\n\nRAVEN works fully without AI. For AI features choose one:\n\n**Claude (recommended, best results).** Create an API key at\n[console.anthropic.com](https://console.anthropic.com) (set a monthly spend limit there), then\nRAVEN → **Settings → Claude (Anthropic API)** → paste the key → **Save & test**.\n\n- The key is stored **encrypted** in your data folder and never shown again; it is never\npassed to commands RAVEN runs.\n- Used by **AI Chat** , the**AI Agent** page and`raven-sec` .\n- Each agent run has a **budget** (default $3) and a**turn limit** (default 40) — change them\nin Settings. The estimated cost is shown next to every run.\n- You pay Anthropic for your own usage and must follow Anthropic's Usage Policy.\n\n**Your own local model (free, offline).** Install [Ollama](https://ollama.com), pull a model\n(for example `ollama pull qwen2.5-coder:7b`), then **Settings → Optional external provider\n(Ollama)** → enable it and enter the model name. It powers **AI Chat**; the agent requires\nClaude. Details and the advanced built-in RAVEN-Sec model: [`docs/LOCAL_AI.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/docs/LOCAL_AI.md).\n\n**Skills** — testing playbooks the agent loads when relevant (`raven/skills/`):\n\n| Skill | Use it for | \n|---|---|\n| `api-recon` | read-only mapping of REST / GraphQL / SOAP / WebSocket APIs | \n| `api-security` | BOLA/IDOR, BFLA, mass assignment, JWT, GraphQL & SOAP issues, low-volume logic checks | \n| `recon-breadth` | subdomains, takeover indicators, archived URLs, parameters | \n| `code-audit` | attacker-first white-box review of source you provide | \n| `patch-diff` | understanding a vendor security fix and checking exposure safely | \n| `php-lfi-rce` | assessing PHP file inclusion; code-execution proof only where allowed / in labs | \n| `browser-testing` | Playwright scripts for DOM XSS, auth flows, SPA crawling | \n\n**Terminal:** `raven-sec` (chat), `raven-sec -q \"question\"`,\n`raven-sec agent \"objective\" --scope app.example.com` (asks y/N before every action;\n`--scope host:port` for other ports, `--allow-private` for your own lab only).\n\n- **Scope enforcement** on every outgoing request (canonical URL, IDNA-correct hostnames,\nresolved address pinned, private/loopback blocked unless enabled, no redirects followed).\n- **Human approval** for every target request, recon job and command the AI agent proposes;\napprovals are bound to the exact action shown.\n- **Offline sandbox** (bubblewrap, Linux) for agent commands: no network, no home directory.\n- **Emergency Stop** , per-workspace request budgets and rate limits, per-run AI budget.\n- **Local API** on`127.0.0.1` only, per-session token, Origin and Host checks.\n- **No offensive extras:** no denial-of-service, malware, persistence, EDR/AV evasion or\ncredential stuffing. AI output is advisory — verify before you report.\n\n- Data lives on your machine: `~/.local/share/raven-recon` (Linux) or`%LOCALAPPDATA%\\RAVEN-Recon` (Windows). Override with`RAVEN_DATA_DIR` .\n- RAVEN contacts only: the targets you approve, `crt.sh` for certificate transparency,\nallow-listed trusted research sources (OWASP, MITRE, NVD, GitHub advisories) when you or the\nagent search, and Anthropic's API if you enabled Claude.\n- No telemetry.\n\n```\npython3 -m venv --system-site-packages .venv\n.venv/bin/pip install -r requirements-linux.txt -r requirements-dev.txt\n.venv/bin/python -m pytest -q          # test suite\n./build-linux.sh                       # standalone app → dist/RAVEN/RAVEN\n```\n\nWindows: `pip install -r requirements-windows.txt -r requirements-dev.txt`, then `build.bat`\n(→ `dist\\RAVEN.exe`). The optional Rust policy bridge (` cargo build --release -p raven-bridge --manifest-path rust/Cargo.toml`) and C++ accelerator (needs `python3-dev`) are built by the\nbuild scripts when the toolchains are present; tests that need them are skipped otherwise.\nRelease builds are produced by GitHub Actions on every `v*` tag (`.github/workflows/release.yml`).\n\n| Problem | Fix | \n|---|---|\n| Opens in the browser instead of its own window (Linux) | `sudo apt install gir1.2-webkit2-4.1 python3-gi` | \n| Agent: \"bubblewrap is not installed\" | `sudo apt install bubblewrap` (Linux only; on Windows the agent cannot run commands) | \n| Claude: key rejected / test failed | Create a new key in the Anthropic console, check billing/spend limit, paste it again | \n| Agent run ends with `REFUSED` | Anthropic's safety system declined a step — state the authorised context (program, scope) more clearly, or do that step by hand | \n| Everything is blocked | Check the workspace scope and ports, and whether Emergency Stop is engaged | \n| The UI feels slow on an old PC or VM | **Settings → Appearance → Static** (or**Off** ) | \n| `raven-recon` /`raven-sec` not found | Add `~/.local/bin` (Linux) or`%LOCALAPPDATA%\\RAVEN-Recon\\bin` (Windows) to`PATH` , open a new terminal | \n\n```\nraven/            application code (API server, recon engine, scope, runtime, AI)\n  claude/         Claude integration (key store, client, agent loop, tools, chat)\n  skills/         testing playbooks loaded by the agent\n  sec_ai/         optional local RAVEN-Sec model, research browser, terminal CLI\nweb/              RAVEN OS UI (index.html) and Recon Workbench (prototype.html)\ntests/            test suite (pytest)\nrust/ native/     optional Rust policy bridge and C++ accelerator\npackaging/        Linux desktop entry and icons\ndocs/             guides, architecture notes, screenshots, development history\ninstall.sh        Kali / Debian / Ubuntu installer\ninstall.ps1       Windows installer\n```\n\nIssues and pull requests are welcome. Security problems in RAVEN itself: please report them\nprivately — see [`SECURITY.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/SECURITY.md). Forks are welcome under the AGPL; per the\nadditional terms in [`NOTICE.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/NOTICE.md), modified versions must be marked as modified and\nmust not present themselves as the official RAVEN Recon.\n\n**RAVEN Recon — Copyright © 2026 mahmoud.**\n\nLicensed under the **GNU Affero General Public License v3.0 or later**\n([`LICENSE`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/LICENSE)), with the additional terms in [`NOTICE.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/NOTICE.md) (keep the\nattribution, mark modified versions, no rights to the RAVEN name and logo). If you run a\nmodified version as a network service, you must offer its source code to its users.\n\nProvided **without any warranty**. You are responsible for using it legally and only with\nauthorisation — see [`RESPONSIBLE_USE.md`](https://github.com/9illcodelli6-cpp69cve/raven-recon/blob/main/RESPONSIBLE_USE.md).", "url": "https://wpnews.pro/news/raven-recon-an-open-source-security-research-framework-with-ai-agents", "canonical_source": "https://github.com/9illcodelli6-cpp69cve/raven-recon", "published_at": "2026-11-19 16:32:50+00:00", "updated_at": "2026-11-19 16:46:34.438565+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Raven Recon", "9illcodelli6-cpp69cve", "Claude Opus 5.5", "GitHub", "Kali Linux", "Windows"], "also_reported_by": [], "takeaway": "Raven Recon gates every AI-agent request and command behind explicit user approval and enforces per-workspace scope rules that block out-of-scope and private addresses, a pattern builders can copy when giving agents network access.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/raven-recon-an-open-source-security-research-framework-with-ai-agents", "markdown": "https://wpnews.pro/news/raven-recon-an-open-source-security-research-framework-with-ai-agents.md", "text": "https://wpnews.pro/news/raven-recon-an-open-source-security-research-framework-with-ai-agents.txt", "jsonld": "https://wpnews.pro/news/raven-recon-an-open-source-security-research-framework-with-ai-agents.jsonld"}}