#☠️ HEAVEN: AUTONOMOUS PENETRATION-TESTING FRAMEWORK

---

---

#👾 Authors

#Nisarg Chasmawala · Alias: HEAVEN

---

#📋 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 penetration-testing 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.

It runs three ways from the same engagement dataset:

• CLI: 62 commands for scriptable, CI-friendly workflows.
• Web UI: a 30-page React command centre (scan launcher, live findings, combined risk, kill-chain, reports).
• REST + WebSocket API: 99 RBAC-protected routes for automation and integration.

---

#📊 Project Summary

---

#⚡ Capabilities

---

#⚙️ 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   │ linPEAS · 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.

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

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

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

62 commands. Run heaven <command> --help for full options.

# 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

Stealth levels:

---

#🖥️ 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.

30 pages:

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

99 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>"

---

#📄 Reports & Export

Generate from the CLI or the web UI (Findings → Download report). Identical output, eight formats:

heaven export -o report.sarif --format sarif
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.

---

#🔌 Integrations

---

#📊 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.91) when the finding carries CVSS metrics, and a TF-IDF text model (TfidfVectorizer + Ridge) trained on the real-finding population of the dataset (315,648 CVEs with a non-zero CVSS score) that reads the finding's own vulnerability type and description when it does not. It is measured on the population HEAVEN actually routes to it (findings carrying a real vuln-type signal), where CV R²=0.63, MAE 0.79, and it lands the correct CVSS severity band 99% of the time within one level (the metric that matters, since the same vuln class genuinely spans a wide score range in the NVD data, and R² can only be driven higher by leaking the CVSS formula's own sub-scores). 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

---

#📁 Project Structure

heaven/                   ← Python package (219 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 (99 routes)
└── cli/                  Click CLI - one module per command group (62 commands)

heaven-ui/                React + Vite web console (30 pages)
tests/                    2877 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 (2877 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

---

#⚠️ 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.

---

2877 tests · 219 modules · 62 CLI commands · 99 API routes · 30 UI pages · PostgreSQL + SQLite · MIT