Scope-aware reconnaissance and AI-assisted security-testing workbench — for bug-bounty hunters and penetration testers. Runs on Windows and Kali Linux as a desktop app, a local web UI, or in the terminal.
Authorised testing only. Use RAVEN Recon only on systems you own or have written
permission to test. Read RESPONSIBLE_USE.md first.
العربية: README.ar.md
⚠️
| AI Agent — every request and command waits for your approval | Recon Workbench — attack surface, request lab, findings |
|---|
| Area | What you get |
|---|---|
| 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. |
| 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. |
| Request lab | Repeater, Intruder (headers, body, baseline anomaly detection), Decoder, HTTP history. |
| Labs | Access-control lab (compare two identities on the same resource) and XSS lab (reflection-context analysis, no script execution). |
| Findings & evidence | Candidate findings with evidence links, review workflow, Markdown workspace report export. |
| 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). |
| AI chat & terminal | Ask questions, get payloads and code ( raven-sec in the terminal). |
| Safety | Emergency Stop, per-run budget and rate limits, offline command sandbox on Linux, encrypted API key, local-only data. |
Option A — ready-to-run app (recommended):
- Download
RAVEN-Recon-windows-x64.zipfrom theReleases page . - Verify it , unzip it, and run
RAVEN.exe. (Windows 10/11 with the Edge WebView2 runtime, which is built into Windows 11.)
Option B — from source (needs Python 3.11+ — or
winget install -e --id Python.Python.3.12 — and Git), in PowerShell:
git clone https://github.com/9illcodelli6-cpp69cve/raven-recon.git
cd raven-recon
powershell -ExecutionPolicy Bypass -File .\install.ps1
This creates a private Python environment, a Start Menu entry, and the commands
raven-recon, raven-recon-web and raven-sec (open a new terminal afterwards).
Uninstall: .\install.ps1 -Uninstall (your data is kept).
Option A — ready-to-run app:
sha256sum -c SHA256SUMS.txt --ignore-missing
tar -xzf RAVEN-Recon-linux-x64.tar.gz
sudo apt install -y gir1.2-webkit2-4.1 bubblewrap # own window + command sandbox
./RAVEN/RAVEN
Option B — from source (recommended on Kali):
git clone https://github.com/9illcodelli6-cpp69cve/raven-recon.git
cd raven-recon
./install.sh
The installer asks before running sudo apt install for the few system packages it needs
(python3-venv python3-gi gir1.2-webkit2-4.1 bubblewrap), creates .venv, adds
RAVEN Recon to the applications menu and installs the raven-recon and raven-sec
commands in ~/.local/bin. Uninstall: ./install.sh --uninstall (your data is kept).
Official builds exist only on this repository's Releases page. Each release has
SHA256SUMS.txt and a GitHub build-provenance attestation proving the file was built by
this repository's workflow:
sha256sum -c SHA256SUMS.txt --ignore-missing
gh attestation verify RAVEN-Recon-linux-x64.tar.gz --repo 9illcodelli6-cpp69cve/raven-recon
Windows: Get-FileHash .\RAVEN-Recon-windows-x64.zip -Algorithm SHA256 and compare with
SHA256SUMS.txt. Copies from anywhere else ("PRO", "cracked", re-uploads) are not official
and may be malicious.
| Windows | Kali / Linux | |
|---|---|---|
| Desktop app (own window) | Start Menu → RAVEN Recon, or raven-recon |
Menu → RAVEN Recon, or raven-recon |
Local web UI (your browser,127.0.0.1 only) |
raven-recon-web |
raven-recon --browser |
| Terminal assistant | raven-sec |
raven-sec |
The 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.
- Create a workspace — RAVEN OS sidebar →Workspace (or in the Recon Workbench:
workspace menu →new workspace ). Enter the program name andexactly the scope the
program allows : in-scope hosts or wildcards (
*.example.com), exclusions, and ports. Leaveallow private addresses off unless it is your own lab. - Set your identity — Workbench →Identity : the User-Agent and the researcher header
your program asks for (for example
X-HackerOne-Research: <your handle>). - Run a collection — Workbench →Run collection : certificate-transparency names, HTTP probes on every scoped port, and endpoint discovery. Watch progress in the terminal panel; stop any time.
- 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 priority, never a vulnerability verdict.
- Test by hand — open a request inRepeater , fuzz a parameter inIntruder (with a baseline to spot anomalies), compare two accounts in theAccess-control lab , check a reflection in theXSS lab , decode tokens inDecoder . Everything is inHTTP history .
- Use the AI agent (optional) — add your Claude key (see below), openAI Agent , pickClaude Opus 5.5 , describe the task (e.g."Check /api/orders/{id} for IDOR using my two test accounts" ). Read each proposed request or command andApprove orDeny it.
- Record and report — the agent and the labs createcandidate findings; review them inFindings , thenExport workspace report (Markdown) and write your own report.
- Stop button —Emergency Stop halts every job, request, agent run and command at once;Resume re-enables them.
- Appearance —Settings → Appearance :Full (animated artwork background),Static (same artwork, no animation — lighter on older machines) orOff (plain dark). Systems set toreduce motion get Static automatically.
RAVEN works fully without AI. For AI features choose one:
Claude (recommended, best results). Create an API key at console.anthropic.com (set a monthly spend limit there), then RAVEN → Settings → Claude (Anthropic API) → paste the key → Save & test.
- The key is stored encrypted in your data folder and never shown again; it is never passed to commands RAVEN runs.
- Used by AI Chat , theAI Agent page and
raven-sec. - Each agent run has a budget (default $3) and aturn limit (default 40) — change them in Settings. The estimated cost is shown next to every run.
- You pay Anthropic for your own usage and must follow Anthropic's Usage Policy.
Your own local model (free, offline). Install Ollama, pull a model
(for example ollama pull qwen2.5-coder:7b), then Settings → Optional external provider
(Ollama) → enable it and enter the model name. It powers AI Chat; the agent requires
Claude. Details and the advanced built-in RAVEN-Sec model: docs/LOCAL_AI.md.
Skills — testing playbooks the agent loads when relevant (raven/skills/):
| Skill | Use it for |
|---|---|
api-recon |
read-only mapping of REST / GraphQL / SOAP / WebSocket APIs |
api-security |
BOLA/IDOR, BFLA, mass assignment, JWT, GraphQL & SOAP issues, low-volume logic checks |
recon-breadth |
subdomains, takeover indicators, archived URLs, parameters |
code-audit |
attacker-first white-box review of source you provide |
patch-diff |
understanding a vendor security fix and checking exposure safely |
php-lfi-rce |
assessing PHP file inclusion; code-execution proof only where allowed / in labs |
browser-testing |
Playwright scripts for DOM XSS, auth flows, SPA crawling |
Terminal: raven-sec (chat), raven-sec -q "question",
raven-sec agent "objective" --scope app.example.com (asks y/N before every action;
--scope host:port for other ports, --allow-private for your own lab only).
-
Scope enforcement on every outgoing request (canonical URL, IDNA-correct hostnames, resolved address pinned, private/loopback blocked unless enabled, no redirects followed).
-
Human approval for every target request, recon job and command the AI agent proposes; approvals are bound to the exact action shown.
-
Offline sandbox (bubblewrap, Linux) for agent commands: no network, no home directory.
-
Emergency Stop , per-workspace request budgets and rate limits, per-run AI budget.
-
Local API on
127.0.0.1only, per-session token, Origin and Host checks. -
No offensive extras: no denial-of-service, malware, persistence, EDR/AV evasion or credential stuffing. AI output is advisory — verify before you report.
-
Data lives on your machine:
~/.local/share/raven-recon(Linux) or%LOCALAPPDATA%\RAVEN-Recon(Windows). Override withRAVEN_DATA_DIR. -
RAVEN contacts only: the targets you approve,
crt.shfor certificate transparency, allow-listed trusted research sources (OWASP, MITRE, NVD, GitHub advisories) when you or the agent search, and Anthropic's API if you enabled Claude. -
No telemetry.
python3 -m venv --system-site-packages .venv
.venv/bin/pip install -r requirements-linux.txt -r requirements-dev.txt
.venv/bin/python -m pytest -q # test suite
./build-linux.sh # standalone app → dist/RAVEN/RAVEN
Windows: pip install -r requirements-windows.txt -r requirements-dev.txt, then build.bat
(→ 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
build scripts when the toolchains are present; tests that need them are skipped otherwise.
Release builds are produced by GitHub Actions on every v* tag (.github/workflows/release.yml).
| Problem | Fix |
|---|---|
| Opens in the browser instead of its own window (Linux) | sudo apt install gir1.2-webkit2-4.1 python3-gi |
| Agent: "bubblewrap is not installed" | sudo apt install bubblewrap (Linux only; on Windows the agent cannot run commands) |
| Claude: key rejected / test failed | Create a new key in the Anthropic console, check billing/spend limit, paste it again |
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 |
| Everything is blocked | Check the workspace scope and ports, and whether Emergency Stop is engaged |
| The UI feels slow on an old PC or VM | Settings → Appearance → Static (orOff ) |
raven-recon /raven-sec not found |
Add ~/.local/bin (Linux) or%LOCALAPPDATA%\RAVEN-Recon\bin (Windows) toPATH , open a new terminal |
raven/ application code (API server, recon engine, scope, runtime, AI)
claude/ Claude integration (key store, client, agent loop, tools, chat)
skills/ testing playbooks loaded by the agent
sec_ai/ optional local RAVEN-Sec model, research browser, terminal CLI
web/ RAVEN OS UI (index.html) and Recon Workbench (prototype.html)
tests/ test suite (pytest)
rust/ native/ optional Rust policy bridge and C++ accelerator
packaging/ Linux desktop entry and icons
docs/ guides, architecture notes, screenshots, development history
install.sh Kali / Debian / Ubuntu installer
install.ps1 Windows installer
Issues and pull requests are welcome. Security problems in RAVEN itself: please report them
privately — see SECURITY.md. Forks are welcome under the AGPL; per the
additional terms in NOTICE.md, modified versions must be marked as modified and
must not present themselves as the official RAVEN Recon.
RAVEN Recon — Copyright © 2026 mahmoud.
Licensed under the GNU Affero General Public License v3.0 or later
(LICENSE), with the additional terms in NOTICE.md (keep the
attribution, mark modified versions, no rights to the RAVEN name and logo). If you run a
modified version as a network service, you must offer its source code to its users.
Provided without any warranty. You are responsible for using it legally and only with
authorisation — see RESPONSIBLE_USE.md.