nishu2402/HEAVEN-Autonomous-Penetration-Testing
nishu2402/HEAVEN-Autonomous-Penetration-Testing has 106 GitHub stars and 26 forks. GitHot measured 0 stars in 24 hours and +2 in 7 days. Last checked 2026-11-18 04:02 UTC. Last push 2026-11-12.
What you can do
- 🔍 Reconnaissance - nmap · web crawling · DNS brute-force · cert transparency · Shodan · AD enumeration · cloud (AWS/GCP/Azure) · containers & Kubernetes (Docker socket / K8s API / RBAC) · IoT/SCADA · Git secrets · email OSINT · honeypot detection · firewall / IDS-IPS / WAF detection + adaptive evasion re-probe (--evade)
- 📱 Offline & Mobile Analysis - heaven analyze / heaven mobile: binary (ELF/PE/Mach-O hardening) · firmware carving · pcap · steganography · documents/archives · audio/video media · hash/crypto · mobile apps: Android APK + iOS IPA scored vs OWASP Mobile Top 10 (embedded secrets · cleartext/ATS · permissions · debuggable/allowBackup · URL schemes)
- 🧬 API Security - OWASP API Top 10: BOLA/IDOR (cross-identity BOLA proven by a reciprocal ground-truth read: A reads B's object and B reads A's, two distinct access-controlled objects, anon denied both) · broken auth · mass assignment · excessive data exposure (REST + GraphQL)
- 🤖 Autonomous AI - LLM observe→plan→act loop · recon agent · attack-chain planner · LLM FP review · AI remediation (heaven remediate) · cross-engagement knowledge graph · provider-agnostic (Anthropic / OpenAI / Gemini / DeepSeek / local) · deterministic fallback needs no API key
Measured star growth
- in 24h
- 0
- in 7 days
- +2
- in 15 days
- Update delayed
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
☠️ Advanced autonomous penetration testing framework. Automates web, network, and cloud vulnerability scanning with contextual CVSS scoring, AI-driven attack planning, and compliance reporting.
SecurityREADME.md
Original☠️ HEAVEN: AUTONOMOUS PENETRATION-TESTING FRAMEWORK
👾 Authors
Nisarg Chasmawala · Alias: HEAVEN
| Detail | |
|---|---|
| linkedin.com/in/nisarg-chasmawala | |
| 🐙 GitHub | github.com/nishu2402 |
| 🎯 Role | Offensive Security Engineer · Penetration Tester |
📋 Table of Contents
- 👾 Authors
- 🧠 What is HEAVEN?
- 📊 Project Summary
- ⚡ Capabilities
- ⚙️ Architecture
- 🚀 Quick Start
- 🔑 API Keys & Configuration
- ⌨️ CLI Reference
- 🖥️ Web UI
- 🌐 REST API
- 📄 Reports & Export
- 🔌 Integrations
- 📊 Risk Scoring (ML)
- 🔒 Security Controls
- 📁 Project Structure
- 🛠️ Development
- 📚 Documentation
- ⚠️ Legal & Disclaimer
🧠 What is HEAVEN?
HEAVEN is a production-grade offensive-security platform that automates the repeatable, time-consuming parts of a professional engagement (reconnaissance, vulnerability detection, exploitation proof, risk triage, and reporting) so the operator can focus on the judgment work only a human can do.
One --profile switch points the same deep engine at either job: pentest (the default) for a full internal/external assessment, or bugbounty for scope-constrained, internet-facing programs · polite adaptive rate limiting, routable HTTP + DNS out-of-band callbacks, program-scope import, active OAuth/SAML flow abuse, single-packet race, reciprocal-proof BOLA, and a submission-ready per-finding report. See 🎯 Bug Bounty Mode.
It runs three ways from the same engagement dataset:
- CLI: 70 commands for scriptable, CI-friendly workflows.
- Web UI: a 32-page React command centre (scan launcher, live findings, combined risk, kill-chain, reports).
- REST + WebSocket API: 107 RBAC-protected routes for automation and integration.
📊 Project Summary
| Metric | Value |
|---|---|
| 🧪 Tests | 3777 tests (pytest matrix: Python 3.11 / 3.12) |
| 📈 Benchmark | Verified against live DVWA: autonomous authenticated SQLi/LFI/cmdi detection → Results |
| 🧩 Modules | 245 |
| ⌨️ CLI Commands | 70 |
| 🌐 API Routes | 107 RBAC-protected routes |
| 🖥️ UI Pages | 32 (React + Vite, dark glassmorphic) |
| 🗄️ Database | PostgreSQL (async, 29-table schema) + zero-config SQLite fallback |
| 🤖 AI / LLM | Observe→plan→act loop · recon agent · attack-chain planner · vuln-hypothesis agent (LLM proposes, real detectors verify) · FP review · knowledge graph |
| 🧠 LLM Providers | Anthropic · OpenAI · Gemini · DeepSeek · local (Ollama / any OpenAI-compatible server) · deterministic fallback (no API key needed) |
| 📊 CVSS Predictor | Hybrid: ExtraTrees vector model (R²=0.99, 13 features, 304k CVEs) + TF-IDF word 1-3 gram text description model trained on 304k real NVD CVEs (a ranking aid for scoreless findings: on the findings it actually scores it orders them by true severity at Spearman ρ=0.81 and lands the right severity band 99% within one level; exact-score R²=0.65) |
| 🗺️ Threat Intel | MITRE ATT&CK mapping · Lockheed Kill Chain · TAXII feed |
| 📄 Report Formats | 10 (PDF · HTML · Markdown · CSV · JSON · SARIF · JUnit XML · Burp XML · proxy-JSONL · bug-bounty submission) |
| 🔒 Security | JWT RBAC · AES-256-GCM vault · HMAC-signed audit log · LLM credential redaction |
| 📦 Install | One command · ./scripts/install.sh (macOS/Linux) · scripts\install.ps1 (Windows) |
| 🐳 Container | docker compose up (bundles PostgreSQL) |
| 🔁 CI | ruff · mypy · pytest · pip-audit · Bandit · self-audit · Docker smoke-test |
⚡ Capabilities
| Area | What It Does |
|---|---|
| 🔍 Reconnaissance | nmap · web crawling · DNS brute-force · cert transparency · Shodan · AD enumeration · cloud (AWS/GCP/Azure) · containers & Kubernetes (Docker socket / K8s API / RBAC) · IoT/SCADA · Git secrets · email OSINT · honeypot detection · firewall / IDS-IPS / WAF detection + adaptive evasion re-probe (--evade) |
| 🎯 Vuln Detection | SQLi (error/boolean/UNION/time-blind) · XSS · LFI/RFI · command injection · SSRF · XXE · CORS (reflected-origin + credentials) · CRLF · open redirect (canary-confirmed) · IDOR · mass assignment · dir/file fuzzing · JWT attacks (alg:none · weak-secret crack) · insecure session cookies · race conditions (incl. true single-packet last-byte-sync limit-overrun, reproduce-first) · business-logic abuse (numeric/quantity tampering · workflow step-skip) · request smuggling · GraphQL introspection · default creds · subdomain takeover · Nuclei templates |
| 🗝️ Active Directory & Identity | authenticated LDAP assessment (Kerberoasting · AS-REP roasting via LDAP and credential-free Kerberos pre-auth · DCSync rights · unconstrained/constrained delegation · SMB-signing / SMBv1 / NTLMv1 · anonymous LDAP) · AD CS certificate-template abuse (ESC1 to ESC4 · ESC8 web-enrolment relay) · NTLM coercion surface (PetitPotam · PrinterBug · DFSCoerce, bind-only, never triggers coercion) · Kerberos pre-auth username enumeration · BloodHound-style path analysis · SSO & OAuth/OIDC/SAML flow abuse (redirect_uri off-origin bypass proven from an observed Location · password-reset host-header poisoning from a reflected marker · implicit-flow / ROPC / PKCE-not-advertised read from OIDC discovery metadata · SAML assertion-signing not enforced · RelayState open redirect) |
| 🌐 Network & Threat | cleartext/legacy protocols · SNMP/IPMI/NFS/VNC exposure · Cisco Smart Install · SMB-signing → NTLM-relay · internet-facing edge/VPN appliance KEV fingerprint (Citrix NetScaler · Ivanti Connect Secure · FortiOS SSL-VPN · PAN GlobalProtect · Exchange · F5 BIG-IP → actively-exploited CVEs) · DoS/DDoS susceptibility: amplification-reflector detection with a measured factor (NTP monlist · open DNS · memcached · SSDP · CLDAP · chargen · RIPv1 · NetBIOS) + Slowloris slow-HTTP (-m dos, one benign probe, never a flood) · sniffing / internal MITM: LLMNR / NBT-NS / mDNS name-poisoning + mitm6 dual-stack susceptibility (-m sniff) · malware / backdoor: Ingreslock/NetBus/Back-Orifice listeners · unauthenticated-shell banners · trojaned vsftpd 2.3.4 / UnrealIRCd / ProFTPD · webshell signature sweep (-m malware) |
| 📱 Offline & Mobile Analysis | heaven analyze / heaven mobile: binary (ELF/PE/Mach-O hardening) · firmware carving · pcap · steganography · documents/archives · audio/video media · hash/crypto · mobile apps: Android APK + iOS IPA scored vs OWASP Mobile Top 10 (embedded secrets · cleartext/ATS · permissions · debuggable/allowBackup · URL schemes) |
| 🧬 API Security | OWASP API Top 10: BOLA/IDOR (cross-identity BOLA proven by a reciprocal ground-truth read: A reads B's object and B reads A's, two distinct access-controlled objects, anon denied both) · broken auth · mass assignment · excessive data exposure (REST + GraphQL) |
| 🧾 CVE Intelligence | Curated offline inline CVE DB (~150 CVEs, version-range matched) + dynamic live fallback: any product/version not in the local DB is looked up in real time against NVD + CIRCL, merged/de-duped, version-confirmed, KEV-flagged, EPSS-scored (real-world exploitation probability) and Exploit-DB-correlated (public PoC link), and disk-cached (7-day TTL) · degrades gracefully offline · heaven cve <product> [version] [--engagement] |
| 💥 Verified Exploitation | Active proof, not guesses: sqlmap SQLi dump · RCE canary file drop/read · in-house HTTP + DNS OAST collaborator proving SSRF · XXE · blind command injection · blind SQLi out-of-band, each requiring an observed callback (zero false positive · no Burp Collaborator / interactsh dependency · run it on a public box with heaven oast so internet targets can call back) |
| 🔓 Post-Exploitation | self-contained privesc engines for Linux and Windows. Linux: GTFOBins-scored SUID/sudo/caps · docker/lxd escape · writable /etc/passwd · cron/PATH hijack; Windows: unquoted service paths · writable service binaries · SeImpersonate/SeBackup token privileges · AlwaysInstallElevated · autologon/registry creds · UAC posture, no linPEAS/WinPEAS download · loot harvester (SSH keys · AWS/GCP/Azure creds · kubeconfig · .env/.netrc/.pgpass/history; secrets redacted, plaintext never persisted) · credential-reuse loop feeding SSH/SMB/PsExec lateral movement + pass-the-hash · ATT&CK-tagged kill-chain · optional LLM path prioritisation · BloodHound AD collection. Run heaven postex {enum,loot,full} (--os windows / auto-detected) |
| ☁️ Cloud Misconfiguration | credential-free public storage-bucket exposure (S3 / GCS / Azure Blob, listable vs private proven from the provider's own response, not guessed) · cloud-metadata SSRF catalog (AWS IMDS / GCP / Azure) that turns an SSRF into confirmed credential theft · plus authenticated account audit (EC2/S3 public ACL & policy & encryption · security-group 0.0.0.0/0 on sensitive ports · public RDS · IAM admin policies) · read-only IAM privilege audit of the authenticated identity: over-privileged principals (*/*) · console users without MFA · stale/unrotated & root access keys · weak password policy (heaven cloud iam, secret never read/logged). Run heaven cloud storage <target> |
| 🤖 Autonomous AI | LLM observe→plan→act loop · recon agent · attack-chain planner · LLM FP review · AI remediation (heaven remediate) · cross-engagement knowledge graph · provider-agnostic (Anthropic / OpenAI / Gemini / DeepSeek / local) · deterministic fallback needs no API key |
| 📊 Risk Scoring | CVSS v4.0 (current standard) scored alongside CVSS v3.1 · the score a client sees is computed exactly from each finding's CVSS vector via the reference formula; the hybrid ML predictor (13-feature ExtraTrees vector model R²=0.99 + TF-IDF word 1-3 gram text description/type model on 304k real NVD CVEs, Spearman ρ=0.81 and right band 99% within one level on the findings it actually scores, exact-score R²=0.65) only ranks findings with no published score · EPSS · CISA KEV · asset-criticality multiplier · empirical Bayesian priors |
| 🗺️ Threat Mapping | Every finding mapped to MITRE ATT&CK techniques + Lockheed Cyber Kill Chain phases · TAXII threat-intel feed |
| 🔗 Combined Risk | Correlates individually-rated findings into materially worse combined issues, then chains them into end-to-end attack paths where each step yields a capability the next one uses · ranks the single "break the chain" fixes that collapse the most paths · OWASP Top 10:2025 crosswalk · rendered in the web UI, the CLI, and the PDF/HTML reports |
| 🔁 DevSecOps | Scheduled re-scans with differential alerts (watch) · Semgrep SAST · SCA: dependency audit against OSV.dev (heaven sca) · CycloneDX SBOM (heaven sbom) · Jira / Linear ticketing · Splunk / Elastic SIEM forwarding |
| 📄 Reporting | 10 formats from CLI and web UI: PDF · HTML · compliance HTML (OWASP/NIST) · Markdown · CSV · JSON · SARIF · JUnit XML · Burp XML · proxy-JSONL · bug-bounty submission (H1/Bugcrowd/Intigriti) |
| 🔇 FP Suppression + Calibration | Two-stage confirmation pass · source-weighted confidence calibration (a validated proof scores high, a version-only CVE match scores honestly low) · a substantiated signal below the finding bar becomes a lead for a human, never a silent drop · optional LLM second opinion |
| 🎯 Bug Bounty Mode | heaven scan --profile bugbounty overlays the same deep core for scope-constrained, internet-facing programs: polite adaptive rate limiting · program-scope import (heaven scope import <file> --program: HackerOne/Bugcrowd JSON, out-of-scope subtraction, *.wildcard entries) feeds the runtime scope guard · routable HTTP + DNS out-of-band collaborator (heaven oast) · active OAuth/OIDC/SAML flow abuse · true single-packet race · business-logic abuse · reciprocal-proof BOLA · submission-ready per-finding report (heaven export --format bugbounty --platform hackerone|bugcrowd|intigriti, also one click in the web UI) |
⚙️ Architecture
┌───────────────────────────────────────────────────────┐
CLI ──────┤ ORCHESTRATOR (async dependency-aware task graph) │
Web UI ───┤ resumable · checkpointed │
REST API ─┤ stealth timing 1-5 │
└───────────────────────────┬───────────────────────────┘
│
┌─────────────┬──────────────┬───────┴──────┬──────────────┬──────────────┐
│ RECON │ VULN DETECT │ EXPLOIT/POST │ AI / ML │ REPORTING │
│ nmap · web │ SQLi/XSS/ │ sqlmap proof │ CVSS model │ PDF · HTML │
│ DNS · cloud │ SSRF/IDOR │ RCE canary │ recon agent │ SARIF · Burp │
│ AD · K8s │ fuzz · API │ privesc · BH │ attack plan │ compliance │
│ IoT · OSINT │ Nuclei · FP │ lateral move │ knowledge gr │ ticketing │
└─────────────┴──────────────┴───────┬──────┴──────────────┴──────────────┘
│
┌────────────────────────────────────┴────────────────────────────────────────┐
│ STORAGE - PostgreSQL (async, 29-table schema, partitioned audit log) │
│ with a zero-config SQLite fallback (same interface, file = one engagement) │
│ SECURITY - JWT RBAC · AES-256-GCM credential vault · HMAC-signed audit log │
└─────────────────────────────────────────────────────────────────────────────┘
🚀 Quick Start
Requirements
- Python 3.11+ (3.11 to 3.13 recommended; the installer prefers a tested line,
because a brand-new major such as 3.14 can leave native security libraries ABI-unstable)
·
git· works on macOS, Linux, and Windows - External scanner binaries (
nmap·nuclei·sqlmap·ffuf·searchsploit·semgrep·docker), installed for you automatically by the one-command installer (see below), using your OS package manager. Each has an in-house fallback, so HEAVEN runs without them; installing them unlocks full power.
Install
One command sets up everything: it clones the repo (if needed), builds a
virtualenv, installs every runtime dependency (full power by default), the
external scanner tools, and the web UI, and writes a ready-to-use .env. Pick
your OS:
# macOS / Linux: one line, no clone needed (git is the only prerequisite)
curl -fsSL https://raw.githubusercontent.com/nishu2402/HEAVEN-Autonomous-Penetration-Testing/main/scripts/install.sh | bash
# Windows (PowerShell, no admin needed)
irm https://raw.githubusercontent.com/nishu2402/HEAVEN-Autonomous-Penetration-Testing/main/scripts/install.ps1 | iex
The one-liner clones into ./HEAVEN-Autonomous-Penetration-Testing (override with
HEAVEN_DIR). Prefer to clone yourself first? That works too:
# macOS / Linux
git clone https://github.com/nishu2402/HEAVEN-Autonomous-Penetration-Testing.git
cd HEAVEN-Autonomous-Penetration-Testing
chmod +x scripts/install.sh && ./scripts/install.sh
# Windows (PowerShell, no admin needed)
git clone https://github.com/nishu2402/HEAVEN-Autonomous-Penetration-Testing.git
cd HEAVEN-Autonomous-Penetration-Testing
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
The installer is fully unattended: the external-tool step never blocks on a
password prompt and every download is bounded by a timeout
(HEAVEN_TOOL_INSTALL_TIMEOUT, default 900s), so it can't hang. Tools install
with your package manager: brew (macOS), apt / dnf / pacman (Linux), or
winget / choco / scoop (Windows), falling back to pip / go. Each has an
in-house fallback, so nothing is mandatory; they just unlock full power.
Env toggles: HEAVEN_SKIP_TOOLS=1 skips the external tools, HEAVEN_CORE_ONLY=1
skips the optional feature packs (-SkipTools / -CoreOnly / -SkipUI on
Windows). To uninstall: ./scripts/uninstall.sh (or scripts\uninstall.ps1).
Updating: once installed, heaven update brings HEAVEN itself up to the
latest released version: a fast-forward git pull (the install is an editable
checkout, so the new code is live on your next command), a pip install -e .
only if dependencies changed, and a web-UI rebuild only if the frontend changed,
then a refresh of the Nuclei/NVD/ExploitDB detection feeds. It never touches
uncommitted local changes (use --force to auto-stash). Check first with
heaven update --check; narrow with --code-only / --data-only. If GitHub is
unreachable (offline, firewall/VPN, or a proxy in the way) it says so in a few
seconds with the cause and what to try, rather than hanging; set HTTPS_PROXY
behind a proxy, or tune the pre-flight budget with HEAVEN_UPDATE_CONNECT_TIMEOUT
(seconds).
Prefer to do it by hand? The base pip install already includes every runtime
capability; only the external binaries are a separate, idempotent step:
pip install -e . # everything runtime: CLI, API, web UI, scanning, recon,
# reports, lateral, cloud, scheduling, ML, AI SDK, SQLite, auth
heaven install-tools # the external scanner binaries (nmap, sqlmap, ffuf, …)
heaven install-tools is idempotent (skips what's already present), can target
specific tools (heaven install-tools sqlmap ffuf) or preview with --dry-run,
and heaven doctor shows what's missing. The only remaining opt-ins are dev
tooling and alternate LLM providers (pip install -e ".[anthropic]" /
".[openai]"). Gemini ships by default. The old feature extras (.[recon],
.[reports], …) still resolve as backward-compatible aliases.
See it in 60 seconds
One command takes a fresh clone to a populated dashboard, and nothing is scanned:
heaven quickstart # ensures .env + loads sample data (a critical→info spread)
heaven serve # opens http://localhost:8443 in your browser · dashboard now populated
# or in one step: heaven quickstart --serve
In the web UI you can also click Load sample data on the dashboard, watch a
Run demo scan play the full loop on the Scans page, and open System
Health (under System) to see which tools and API keys are active, the web
equivalent of heaven doctor.
The animation above is a lightweight SVG cast (it plays on GitHub). To swap in a real screen recording, drop a
docs/assets/demo.gifand point the<img>at it.
Configure
The friendliest path is the interactive wizard: it prompts for the admin
password and any API keys you want, then writes a .env for you:
heaven init
Prefer to do it by hand? Only the admin password is needed to start:
# Web UI login (admin/admin on first run → forced change). Set this to skip that.
export HEAVEN_ADMIN_PASSWORD="your-strong-password"
# Optional: turn on the AI layers (Gemini has a generous free tier). The Gemini
# SDK already ships in the base install, so a key is all you need:
export GEMINI_API_KEY="your-gemini-key" # from https://aistudio.google.com/apikey
No LLM key needed. Every AI feature falls back to a deterministic heuristic, or pass
--no-llm:heaven autonomous -t 10.0.0.5 --no-llm --i-have-authorization
🖥️ Local AI: no API key, no rate limits, private
Prefer a model on your own machine? One command sets it up, with no key, no quotas, and your findings never leaving the host (great under NDA):
heaven ai setup # installs Ollama + pulls qwen2.5:7b, then wires .env
heaven chat # talk to the engagement-grounded AI assistant
Prefer clicking? Settings → AI / LLM → Local AI in the web app is a full point-and-click wizard: detect Ollama, pull a model with a live progress bar, and one click to go live, no terminal needed.
That points HEAVEN's entire AI layer (FP triage, remediation, attack-chain
planning, coverage, the chatbot) at a local model. Any OpenAI-compatible server
works too (LM Studio / llama.cpp / vLLM): set HEAVEN_LLM_PROVIDER=local +
HEAVEN_LLM_BASE_URL. Keep a cloud key as an automatic safety net with
HEAVEN_LLM_FALLBACK_PROVIDER=gemini. Full guide: docs/LOCAL_AI.md.
👉 Full key reference (Gemini / Anthropic / OpenAI / NVD / Shodan, and the three ways to set them) is in API Keys & Configuration below.
Scan
heaven --version
heaven engage init my-engagement
heaven use my-engagement # set it active, no more --engagement
heaven scan -u https://target.example.com -m web --i-have-authorization
heaven scan -t 10.0.0.0/24 -m network --i-have-authorization
heaven serve # opens http://localhost:8443 in your browser
🔑 API Keys & Configuration
HEAVEN runs with zero API keys. Scanning, the web UI, reports, and ML risk scoring all work offline. Keys only unlock optional enrichments, most importantly the AI layers (autonomous mode, AI attack plans, LLM false-positive review). Add only what you want.
Every supported key
| Env var | Unlocks | Required? | Where to get it |
|---|---|---|---|
GEMINI_API_KEY |
AI layers via Google Gemini (free tier) | Optional | https://aistudio.google.com/apikey |
ANTHROPIC_API_KEY |
AI layers via Claude | Optional | https://console.anthropic.com |
OPENAI_API_KEY |
AI layers via GPT | Optional | https://platform.openai.com/api-keys |
DEEPSEEK_API_KEY |
AI layers via DeepSeek (OpenAI-compatible, no SDK) | Optional | https://platform.deepseek.com/api_keys |
NVD_API_KEY |
30× faster CVE-feed ingestion | Optional | https://nvd.nist.gov/developers/request-an-api-key |
SHODAN_API_KEY |
Passive recon (exposed-host intel) | Optional | https://account.shodan.io |
WEBHOOK_URL |
Slack / Teams / Discord alerts | Optional | Your workspace's incoming-webhook URL |
HEAVEN_ADMIN_USERNAME |
Web UI login name (shown in the header badge) | Optional (defaults to admin) |
You choose it |
HEAVEN_ADMIN_PASSWORD |
Web UI login (skips the admin/admin forced-change) | Recommended | You choose it |
You only need one LLM key. HEAVEN auto-detects whichever is set (Anthropic → OpenAI → Gemini → DeepSeek), or pin one with
HEAVEN_LLM_PROVIDER.
Add a Gemini key (free): 3 steps
- Get the key: open https://aistudio.google.com/apikey, sign in with a Google account, click Create API key, and copy it.
- Install the Gemini SDK:
pip install -e ".[gemini]" # or: pip install google-genai - Give it to HEAVEN (pick one):
heaven init # a) wizard, writes .env for you echo 'GEMINI_API_KEY=your-key' >> .env # b) .env file export GEMINI_API_KEY="your-key" # c) shell (this session only)
Confirm it's active:
heaven doctor # shows ✓ LLM gemini (gemini-flash-latest) when working
Five ways to set any key
| Method | How | Best for |
|---|---|---|
| Web UI | Settings page → paste key → Save | Easiest: no terminal; persists to .env, live immediately |
| CLI | heaven config set GEMINI_API_KEY |
Scriptable; same keys as the Settings page |
| Wizard | heaven init |
First-time setup: prompts for everything, writes .env |
.env file |
copy .env.example → .env, edit |
Persistent local / dev |
| Shell export | export GEMINI_API_KEY=… |
One-off / CI |
The Web UI, CLI and wizard all write the same .env, so a key
set in any one is live for the CLI, the API and the web UI at once. Set it
once, it works everywhere and survives a restart. The web UI's Settings
page lists every key with a "how to get it" link and shows which are already
configured (secrets masked). HEAVEN auto-loads .env from the working
directory. Never commit .env: it's already in .gitignore.
Add a DeepSeek key: no SDK needed
DeepSeek is an OpenAI-compatible cloud API, so HEAVEN talks to it over the built-in HTTP client. There is no extra package to install.
- Get the key: open https://platform.deepseek.com/api_keys and create one.
- Give it to HEAVEN (pick one) and select the provider + model:
export HEAVEN_LLM_PROVIDER=deepseek export DEEPSEEK_API_KEY="your-key" export HEAVEN_LLM_MODEL=deepseek-chat # or deepseek-reasoner # optional: point at a proxy/self-hosted gateway # export DEEPSEEK_BASE_URL=https://api.deepseek.com
Pinning a provider / model (optional)
export HEAVEN_LLM_PROVIDER=gemini # force a provider (else auto-detected)
export HEAVEN_LLM_MODEL=gemini-pro-latest # override the default model
Default models: Claude claude-sonnet-5 · OpenAI gpt-4o · Gemini
gemini-flash-latest · DeepSeek deepseek-chat. With no key set anywhere, every
AI feature falls back to a deterministic heuristic (or pass --no-llm).
⌨️ CLI Reference
70 commands. Run heaven <command> --help for full options.
| Command | Purpose |
|---|---|
scan |
Launch a vulnerability scan (-m web|network|full, --profile pentest|bugbounty, --stealth 1-5, --auto-prove, --autonomous) |
serve |
Start the API server + web UI (optional native TLS: --tls-cert/--tls-key serves HTTPS without a reverse proxy) |
engage · scope · use |
Manage engagements · in-scope targets · select the active engagement (stops repeating --engagement) · scope import <file> --program ingests a HackerOne/Bugcrowd program scope (in-scope *.wildcard + out-of-scope subtraction) |
findings · show · mark · remediate |
List findings · full detail · set triage status · AI-assisted remediation |
leads |
Honest leads: substantiated signals that did not reach the finding bar, kept for a human to review · never counted as findings, never given a severity · --promote / --dismiss to triage |
export · report · sbom |
Export findings (10 formats, incl. --format bugbounty --platform) · compliance HTML/PDF · CycloneDX SBOM |
oast |
Run the out-of-band collaborator standalone (HTTP + DNS) on a public box and print callbacks live, so internet targets can prove blind SSRF / XXE / command injection / SQLi |
kill-chain · coverage |
Kill-chain phase coverage · OWASP coverage grade |
autonomous |
LLM-driven observe→plan→act loop (bounded budget) |
fleet |
Agent Fleet: default-on multi-agent engine (a superset of the pipeline; revert a process with HEAVEN_AGENT_FLEET=0) · one lead per scan mode + recon/strategy/hypothesis/FP-critic/coverage roles · agents PROPOSE, real oracles VERIFY (no agent ever writes a finding) · runs at full strength with no API key (-m focuses one mode, --i-have-authorization arms the exploit lead) |
watch |
Continuous monitoring: diffs each run, alerts only on change |
diff |
Compare two scans (new / resolved / regressed / unchanged) |
sast |
Semgrep static analysis + curated OWASP rule pack |
sca |
Software Composition Analysis: dependency manifests vs. OSV.dev advisories |
cve <product> [version] |
Dynamic live CVE lookup: query NVD + CIRCL for any product/version not in the local DB (merged, de-duped, version-confirmed, EPSS-scored, Exploit-DB-correlated; --engagement persists them) |
dns <domain> |
DNS enumeration: A/AAAA/MX/NS/TXT/SOA/CNAME records, resolvable subdomains, mail servers, DNSSEC & wildcard, plus DNS security posture; surfaces in the Assets view and reports (--engagement persists them) |
ssh <host> · vpn <host> |
Direct crypto probes, at parity with dns: ssh audits the SSH transport (weak host-key / KEX / cipher / MAC algorithms) · vpn checks an OpenVPN control channel for missing tls-auth/tls-crypt (--engagement persists them) |
postex enum/loot/full |
Post-exploitation: privesc enumeration (Linux + Windows via --os) · loot harvest · full playbook (kill-chain + AI) |
cloud storage |
Credential-free public S3/GCS/Azure bucket-exposure scan derived from a target domain |
cloud iam |
Read-only IAM privilege audit of the authenticated AWS identity (over-privileged principals · missing MFA · stale/root keys · weak password policy) |
lateral · knowledge |
Lateral movement · cross-engagement knowledge graph |
exploitdb · mitre-report |
Exploit-DB lookup · ATT&CK Navigator layer |
mitre |
Refresh & query live MITRE ATT&CK data (TAXII 2.1): mitre refresh · mitre technique <ID> |
tickets |
Push findings to Jira / Linear |
pause · resume · replay |
Pause · resume · deterministically replay a scan |
download-model · train-model · train-priors |
Fetch the pre-trained CVSS model · retrain it · learn Bayesian priors |
quickstart · demo |
Zero→ready in one command · load sample data to explore |
init · init-db · update |
Setup wizard · PostgreSQL schema · self-update HEAVEN to the latest version + refresh CVE/Nuclei feeds |
config · vault |
Manage API keys & integrations (same keys as the web Settings page) · encrypted AES-256-GCM credential store, an alternative to a plaintext .env |
self-audit · doctor · info |
Security self-audit · deployment health check · platform info |
completion |
Tab-completion for the heaven command, installed automatically by the installer, or one-command heaven completion --install (bash / zsh / fish / PowerShell) |
# Verified exploitation + autonomous LLM loop
heaven scan -u https://app.example.com --auto-prove --i-have-authorization
heaven autonomous -t 10.0.0.5 --engagement test --i-have-authorization
# Fully deterministic, no API key required
heaven autonomous -t 10.0.0.5 --no-llm --i-have-authorization
# Agent Fleet: many role-scoped agents over the whole engagement, zero keys.
# Read-only by default; agents propose, real oracles verify, only confirmed
# findings persist. `--mode` focuses one mode; omit it to run every mode lead.
heaven fleet -t 10.0.0.5 -u https://app.example.com --engagement test
heaven fleet -u https://app.example.com --mode web --engagement test
# Biggest targets: opt into cross-process scale-out (workers share the engagement
# DB). Single-process is the default; --workers N is only for very large surfaces.
heaven fleet -t 10.0.0.0/24 --engagement test --workers 4
Agent Fleet · how it stays honest and keyless. The fleet wraps the existing
pipeline; it does not replace it, so classic heaven scan and the UI are
unchanged. It registers one agent lead per backend scan mode (network · web · api
· cloud · container · iot · ot · ad · email · wireless · dos · sniff · malware ·
exploit · devsecops · ci) plus recon, strategy, hypothesis, FP-critic and coverage
roles. A role only ever proposes a task; the same deterministic detectors that
power heaven scan verify it, and only their confirmed output becomes a
finding · no agent can mint one. The intelligence ladder auto-selects the best
brain that is already present (Tier 0 deterministic → local Ollama → cloud key),
requires none, and never blocks or downloads anything, so the whole fleet runs at
full strength on a fresh install with no keys. Run heaven doctor to see the
active tier. The fleet is on by default: it is a superset of the pipeline (it
runs the same verify oracles as heaven scan, then fans out onto the surface it
discovers), so it can only add coverage, never drop a finding. Classic heaven scan stays byte-for-byte the same, and you can revert the default for a process
with a single flag, HEAVEN_AGENT_FLEET=0. It scales the same way HEAVEN scans do · a single process
by default (bounded async concurrency over the orchestrator's own semaphores),
with an opt-in cross-process worker pool (--workers N / HEAVEN_FLEET_WORKERS)
for the very biggest engagements, where scan tasks fan out across processes that
share one engagement DB and persist the identical findings a single process would.
Stealth levels:
| Level | Description |
|---|---|
| 1 · Ghost | Maximum evasion · randomised timing · slowest |
| 2 · Cautious | Slow · randomised · honeypot avoidance |
| 3 · Normal | Balanced speed/stealth |
| 4 · Aggressive | Faster · minimal evasion |
| 5 · Loud | Full speed · no evasion (lab / CTF only) |
🖥️ Web UI
heaven serve auto-opens http://localhost:8443 in your default browser once the server is up (pass --no-open to skip). A dark, glassmorphic React console (Inter + JetBrains Mono) with a command palette (⌘K), live log streaming, and a 3D network-topology view.
32 pages:
| Page | Description |
|---|---|
| Dashboard | Severity distribution · MITRE ATT&CK heat-map |
| Engagement | Active engagement · in-scope targets · asset criticality |
| Assets | Host & service inventory: open ports · service versions · OS fingerprint · device name · device type · MAC address (same-subnet, when observed) |
| Scans | Launch · history · live progress |
| Findings | Filter · triage · download report |
| Finding Detail | Description · impact · remediation · CWE/OWASP/MITRE · evidence · curl repro |
| Leads | Substantiated signals below the finding bar, kept for a human · never counted as findings, never given a severity · promote / dismiss |
| Reports | Severity snapshot · one-click download in all 10 formats · bug-bounty submission pack (platform-shaped: HackerOne / Bugcrowd / Intigriti) |
| Combined Risk | Correlates two or more findings into a single higher-severity issue · chains them into end-to-end attack paths (each step yields a capability the next uses) · ranks the single "break the chain" fixes with the most leverage · OWASP Top 10:2025 crosswalk |
| Kill Chain | Lockheed phase coverage · attack-path summary |
| Watch | Continuous monitoring · differential alert feed |
| Scan Diff | New / resolved / regressed / unchanged findings |
| SAST | Semgrep results + OWASP rule pack |
| SCA · Deps | Dependency audit vs. OSV.dev: vulnerable packages + fix versions |
| CVE Lookup | Dynamic live CVE search (NVD + CIRCL) for any product/version: version-confirmed, KEV-flagged, EPSS-scored, Exploit-DB PoC links |
| Analyze | Offline artifact analysis: pcap · firmware · binary · documents · archives · audio/video · steganography · mobile apps (Android APK / iOS IPA vs OWASP Mobile Top 10) |
| Autonomous | LLM observe→plan→act loop with bounded budget |
| Agent Fleet | Default-on multi-agent engine: one lead per scan mode + recon/strategy/hypothesis/FP-critic/coverage roles · agents propose, real oracles verify · runs keyless |
| AI Plans | Saved attack plans from autonomous sessions |
| Assistant | Engagement-grounded AI chat assistant (also a floating widget on every page) |
| Coverage | OWASP coverage grade per engagement |
| Compliance | Live control-by-control coverage per framework, downloadable per framework (maps evidence of gaps to controls, not an attestation) |
| Exploit | Authorized active exploitation: confirms RCE with a benign proof command · read-only, no persistence · admin-gated |
| Post-Ex | Self-contained privesc enum (Linux GTFOBins + Windows) · loot harvest · BloodHound AD collection |
| Lateral | SSH/SMB/PsExec lateral movement paths |
| Pivot | Tunnel through an authorized SSH foothold to connect-scan subnets your host cannot route to · double-pivot chaining · read-only |
| Knowledge | Cross-engagement knowledge graph |
| Tickets | Jira / Linear sync status |
| Benchmark | DVWA precision/recall numbers |
| Methodology | Live coverage vs OWASP WSTG · NIST 800-115 · PTES + Cyber Essentials · ISO 27001 · PCI DSS · CIS v8 · NIST CSF · SOC 2 |
| System Health | doctor in the browser: tools / keys / module status + install hints |
| Settings | API keys & integrations: paste keys, masked state, how-to-get links |
![]() Findings: filter · triage · download report |
![]() Kill Chain: phase coverage · chained attack path |
![]() Scans: guided launcher · authorization gate |
![]() Reports: client-ready PDF/HTML · 10 export formats |
First login: ships with
admin/adminand forces a password change on first sign-in. SetHEAVEN_ADMIN_PASSWORD(and optionallyHEAVEN_ADMIN_USERNAME) beforehand to skip the prompt. A password changed in the Web UI is persisted to.env, so it survives a server restart (.envis the source of truth thatheaven servere-reads on boot). JWTs are held in memory only, neverlocalStorage.
🌐 REST API
107 RBAC-protected routes on port 8443. Interactive docs at /docs.
# Health (no auth)
curl http://localhost:8443/api/health
# Login → JWT
curl -X POST http://localhost:8443/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"your-password"}'
# Use the token
curl http://localhost:8443/api/engagement/findings \
-H "Authorization: Bearer <token>"
| Endpoint | Permission | Purpose |
|---|---|---|
POST /api/scans · GET /api/scans |
scan.create / scan.view |
Launch / list scans |
GET /api/engagement/findings |
vuln.view |
Findings (filterable) |
GET /api/engagement/findings/{id}/evidence |
vuln.view |
Full evidence package |
POST /api/findings/{id}/prove |
vuln.validate |
Verified exploitation proof |
POST /api/autonomous/run |
scan.create |
Iterative LLM pen-test loop |
GET /api/scans/{id}/diff?baseline=… |
scan.view |
Differential scan |
POST /api/sast/scan |
scan.create |
Semgrep SAST |
POST /api/sca |
vuln.validate |
Dependency audit vs. OSV.dev |
POST /api/cloud/storage |
vuln.validate |
Credential-free public bucket-exposure scan |
POST /api/cve/lookup |
vuln.view |
Dynamic live CVE lookup (NVD + CIRCL) for products not in the local DB |
POST /api/lateral/run · /api/postex/{module}/run |
admin | Lateral / post-ex modules (enum, win-enum, loot, full, …) |
GET /api/report/export?format=… |
report.view |
Download report (10 formats, incl. format=bugbounty&platform=…) |
POST /api/auth/change-password |
session | Change password |
GET · POST /api/settings |
config.modify |
API keys & integrations (secrets masked) |
GET /api/engagement/top-findings |
vuln.view |
"Fix this first": highest-risk findings + remediation |
GET /api/engagement/leads · PUT …/leads/{id}/status |
vuln.view / vuln.update |
Honest leads: sub-threshold substantiated signals · promote / dismiss (promoting never mints a finding) |
GET /api/system/health |
scan.view |
System health (tools / keys / modules): web doctor |
POST /api/demo/seed · /api/demo/scan |
scan.create |
Load sample data · run an animated demo scan |
GET /api/ws/logs · /api/ws/scan/{id} |
token (query) | WebSocket live streams |
📄 Reports & Export
Generate from the CLI or the web UI (Findings → Download report, or the Reports page). Identical output, ten formats:
| Format | Use Case |
|---|---|
Client / executive deliverable (requires reportlab) |
|
| HTML | Self-contained · compliance-mapped (OWASP Top 10:2025 / NIST CSF) |
| Markdown | Wiki / Git |
| CSV | Spreadsheet / bulk triage |
| JSON | Automation / re-import |
| SARIF | GitHub code scanning |
| JUnit XML | CI build gate (fails the build on --fail-on <severity>) |
| Burp XML | Import into Burp Suite |
| proxy-JSONL | Replay via mitmproxy / Caido |
| Bug-bounty submission | Per-finding H1 / Bugcrowd / Intigriti report: CVSS 3.1 + 4.0, CWE/OWASP, curl + raw request, OAST callback proof, honest Confirmed/Potential (--platform) |
heaven export -o report.sarif --format sarif
heaven export -o submission.md --format bugbounty --platform hackerone
heaven report --framework OWASP_TOP10 -o compliance.html
heaven report --framework NIST_CSF -o nist.html
The PDF and HTML client deliverables also carry a Combined Risk & Attack Paths section: findings that combine into a materially worse issue, the end-to-end attack-path narrative, and the single "break the chain" fixes that collapse the most paths.
Every finding carries a defensible evidence package: request/response, copy-pasteable curl repro, detection rationale, remediation, and CWE/OWASP/MITRE references sourced from the built-in vulnerability knowledge base.
Report footers and the "Generated" timestamp render in the operator's own timezone: a report produced in India reads IST, one in the UK reads GMT/BST, automatically, with no configuration. Pin an explicit zone for a client abroad with HEAVEN_REPORT_TZ=Asia/Kolkata (any IANA name), or HEAVEN_REPORT_TZ=UTC to keep UTC footers. Stored timestamps stay UTC regardless. The web UI clock follows the viewer's own browser zone.
🔌 Integrations
| Tool | How |
|---|---|
| Nuclei | Auto-run when on PATH · nuclei -update-templates |
| sqlmap | Auto-runs on confirmed SQLi candidates |
| searchsploit / Exploit-DB | CVE → PoC · product/version → PoC lookup |
| Shodan | export SHODAN_API_KEY=… → merged into recon |
| Jira / Linear | HEAVEN_JIRA_* / HEAVEN_LINEAR_* env → heaven tickets |
| Splunk / Elastic | SIEM forwarding via HEAVEN_SPLUNK_HEC_* / HEAVEN_ELASTIC_* |
📊 Risk Scoring (ML)
HEAVEN scores every finding with CVSS v4.0, the current standard, and shows its CVSS v3.1 score alongside (the calibrated score that drives the severity band). Published CVE scores come straight from NVD / OSV, preferring v4.0 when the advisory carries it; for a finding with no published score HEAVEN predicts a base score with a hybrid model: a 13-feature ExtraTreesRegressor (5-fold CV R²=0.99 on 304,430 real NVD CVEs, temporal holdout on the unseen newest year R²=0.97) when the finding carries CVSS metrics, and a TF-IDF text model (TfidfVectorizer word 1-3 grams + Ridge) trained on the real-finding population of the dataset (304,356 CVEs with a non-zero CVSS score) that reads the finding's own vulnerability type and description when it does not. The vector model reverse-engineers the CVSS calculator, so a large, dense sample of real CVEs recovers the base-score formula almost exactly. The client-facing badge is still the exact formula, and this model only orders findings. This text model is a ranking aid for scoreless findings and never sets the badge, so the metrics that match its job are how well it orders findings by true severity (Spearman ρ=0.81) and whether it lands the right severity band (99% within one level, 73% exact), both measured on the population HEAVEN actually routes to it (findings carrying a real vuln-type signal). Exact-score cross-validation is R²=0.65, MAE 0.68 (R² is a harsh lens here, since the same vuln class spans a wide score range in the NVD data, and it can only be pushed higher by leaking the CVSS formula's own sub-scores). The ordering even holds on CVEs from a year the model never trained on (temporal holdout: ρ=0.70, 98% within one band). The severity a report shows is always reconciled to the exact CVSS-vector computation; the text model is a secondary ranking signal pinned to that authoritative severity, never the badge. HEAVEN then layers on:
- EPSS exploit-probability and CISA KEV membership
- An asset-criticality multiplier (
scope add --criticality crown_jewel) - Empirical Bayesian priors learned from your past engagements (
heaven train-priors)
The models (~6 MB vector + ~2 MB description) aren't bundled in the wheel or git, so fetch them once (SHA-256 verified) with heaven download-model, or train your own with heaven train-model. Without them, CVSS gracefully falls back to each finding's own base score. Model provenance and caveats are documented in data/models/NVD_model.MODEL_CARD.md.
🔒 Security Controls
| Control | Implementation |
|---|---|
| JWT RBAC | admin / operator / viewer / auditor roles · brute-force lockout with exponential backoff |
| Default-credential protection | admin/admin seed forces password change on first login · self-audit flags it as critical until changed |
| AES-256-GCM vault | All stored secrets encrypted at rest |
| Owner-only on disk | Engagement databases, .env, and the data/ tree are created with restrictive permissions (0600 files · 0700 dirs) so other local users on a shared host can't read captured secrets |
| HMAC-signed audit log | Append-only · every operator action recorded |
| LLM credential redaction | Operator credentials scrubbed before any prompt reaches a third-party LLM endpoint |
| Authorization gate | Destructive actions refuse to run without --i-have-authorization |
| Self-audit | heaven self-audit scores your own installation and surfaces misconfigurations |
📁 Project Structure
heaven/ ← Python package (245 modules)
├── recon/ network · web · DNS · cloud · containers/K8s · AD · IoT · Git · email
├── vulnscan/ injection · IDOR · API · misconfig (CORS/JWT/cookies) · OOB SSRF/XXE · OAST collaborator · SSL · Nuclei · exploit-proof · exploitdb · SAST · FP-suppress
├── postex/ privesc enum engines - Linux (GTFOBins) + Windows (services/privileges/AIE) · loot harvester · session/kill-chain · BloodHound · lateral movement · credential reuse
├── ai/ LLM gateway · recon agent · attack-chain planner · FP review · knowledge graph
├── ml/ CVSS model · feature engine · Bayesian priors · training pipeline
├── mitre/ ATT&CK mapping · kill chain · TAXII threat-intel
├── devsecops/ PDF/compliance reports · vuln KB · SBOM · diff · alerting · ticketing
├── db/ PostgreSQL (async ORM, 29-table schema) + SQLite fallback
├── security/ JWT RBAC · AES-256-GCM vault · HMAC audit log
├── api/ FastAPI server + WebSocket (107 routes)
└── cli/ Click CLI - one module per command group (70 commands)
heaven-ui/ React + Vite web console (32 pages)
tests/ 3777 pytest tests + native & DVWA benchmark suites
docs/ QUICKSTART · methodology (OWASP/NIST/PTES + CE/ISO27001/PCI/CIS/CSF/SOC2)
data/models/ NVD_model.pkl · MODEL_CARD.md
scripts/ install.sh · uninstall.sh · install.ps1 · uninstall.ps1 (Windows)
🛠️ Development
pip install -e ".[dev]"
ruff check heaven/ tests/ # lint
mypy heaven/ # type-check
pytest tests/ # full suite, ~3.5 min (3777 tests)
heaven self-audit # security self-check
CI pipeline (every push to main):
rufflintmypytype-checkpytestmatrix (Python 3.11 / 3.12)pip-auditdependency CVE scanbanditSASTheaven self-audit- Docker image build + smoke-test
See CONTRIBUTING.md · CODE_OF_CONDUCT.md.
📚 Documentation
| Document | Purpose |
|---|---|
docs/QUICKSTART.md |
5-minute end-to-end walkthrough |
docs/FAQ.md |
FAQ & troubleshooting: common fixes |
docs/BENCHMARK_HOWTO.md |
Reproduce DVWA precision/recall numbers |
docs/COMPARISON.md |
Head-to-head vs Burp Suite / ZAP / Nessus / sqlmap |
docs/methodology/ |
Live coverage maps: OWASP WSTG · NIST 800-115 · PTES · Cyber Essentials (+Plus) · ISO 27001 · PCI DSS · CIS v8.1 · NIST CSF 2.0 · SOC 2 |
CHANGELOG.md |
Full version history |
SECURITY.md |
Responsible disclosure policy |
CONTRIBUTING.md |
How to contribute |
CODE_OF_CONDUCT.md |
Community conduct |
⚠️ Legal & Disclaimer
HEAVEN is intended for authorized security testing and education only.
Running it against systems you do not own or lack explicit written permission to test is illegal in most jurisdictions and may carry criminal penalties.
- Every destructive action requires the
--i-have-authorizationflag. - All scan activity is logged to an HMAC-signed, append-only audit trail.
- The authors accept no liability for misuse or damage.
By using HEAVEN you agree you are solely responsible for ensuring you have proper authorization before running any scan. Licensed under MIT.
3777 tests · 245 modules · 70 CLI commands · 107 API routes · 32 UI pages · PostgreSQL + SQLite · MIT



