Skip to content
Projects

nishu2402/HEAVEN-Autonomous-Penetration-Testing

View on GitHub

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.

How these counts are measured

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.

Security

README.md

Original

☠️ HEAVEN: AUTONOMOUS PENETRATION-TESTING FRAMEWORK

HEAVEN: Autonomous Penetration-Testing Framework · Recon → ML Risk Scoring → Verified Exploitation → Reporting · 3777 tests · 70 CLI commands · 107 API routes · 32 UI pages · 15 scan modes · hybrid CVSS ML predictor R²=0.99 · LLM observe→plan→act with deterministic fallback (no API key required)


Python FastAPI Tests LLM License

Modules CLI UI DB CVSS

Stars Forks Issues


👾 Authors

Nisarg Chasmawala · Alias: HEAVEN

Detail
🔗 LinkedIn linkedin.com/in/nisarg-chasmawala
🐙 GitHub github.com/nishu2402
🎯 Role Offensive Security Engineer · Penetration Tester

📋 Table of Contents


🧠 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.
HEAVEN: Autonomous Penetration Testing Platform v4.4.0

📊 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

HEAVEN demo: heaven quickstart loads sample data, heaven serve starts the web UI, and the dashboard shows ranked findings

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.gif and 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

  1. Get the key: open https://aistudio.google.com/apikey, sign in with a Google account, click Create API key, and copy it.
  2. Install the Gemini SDK:
    pip install -e ".[gemini]"        # or:  pip install google-genai
    
  3. 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.

  1. Get the key: open https://platform.deepseek.com/api_keys and create one.
  2. 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.

heaven CLI dashboard: module status + live command reference (v4.4.0)
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.

HEAVEN web UI Dashboard: 3D attack-surface topology, severity distribution, and Fix-This-First priorities

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: triage table with severity, confidence, status and report download
Findings: filter · triage · download report
Kill Chain: Lockheed Martin 7-phase coverage with chained attack path
Kill Chain: phase coverage · chained attack path
Scans page: guided scan launcher with authorization gate + CLI reference
Scans: guided launcher · authorization gate
Reports: client-ready PDF/HTML and 10 export formats incl. bug-bounty submission + CycloneDX SBOM
Reports: client-ready PDF/HTML · 10 export formats

First login: ships with admin/admin and forces a password change on first sign-in. Set HEAVEN_ADMIN_PASSWORD (and optionally HEAVEN_ADMIN_USERNAME) beforehand to skip the prompt. A password changed in the Web UI is persisted to .env, so it survives a server restart (.env is the source of truth that heaven serve re-reads on boot). JWTs are held in memory only, never localStorage.


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

  1. ruff lint
  2. mypy type-check
  3. pytest matrix (Python 3.11 / 3.12)
  4. pip-audit dependency CVE scan
  5. bandit SAST
  6. heaven self-audit
  7. 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-authorization flag.
  • 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

Stars Forks Watchers