cd /news/ai-agents/raven-recon-an-open-source-security-… · home › topics › ai-agents › article
[ARTICLE · art-172677] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Raven Recon – An open-source security research framework with AI agents

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.

key 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.

read9 min views2 publishedNov 19, 2026
Raven Recon – An open-source security research framework with AI agents
Image: Michielbdejong (auto-discovered)

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):

  1. Download RAVEN-Recon-windows-x64.zip from theReleases page .
  2. Verify it , unzip it, and runRAVEN.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.

  1. 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.
  2. Set your identity — Workbench →Identity : the User-Agent and the researcher header your program asks for (for exampleX-HackerOne-Research: <your handle> ).
  3. 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.
  4. 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.
  5. 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 .
  6. 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.
  7. Record and report — the agent and the labs createcandidate findings; review them inFindings , thenExport workspace report (Markdown) and write your own report.
  8. Stop button —Emergency Stop halts every job, request, agent run and command at once;Resume re-enables them.
  9. 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 andraven-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 on127.0.0.1 only, 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.sh for 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.

── more in #ai-agents 4 stories · sorted by recency
── more on @raven recon 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/raven-recon-an-open-…] indexed:0 read:9min 2026-11-19 · —