{"id":49585180,"url":"https://github.com/juliosuas/vulcan","last_synced_at":"2026-05-03T22:06:09.340Z","repository":{"id":344841760,"uuid":"1182897295","full_name":"juliosuas/vulcan","owner":"juliosuas","description":"🌋 AI-Powered Autonomous Penetration Testing Agent — ReAct loop with Claude/GPT-4, full pipeline from recon to report","archived":false,"fork":false,"pushed_at":"2026-04-20T05:58:51.000Z","size":90,"stargazers_count":0,"open_issues_count":15,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T07:37:15.279Z","etag":null,"topics":["ai","automation","cybersecurity","ethical-hacking","penetration-testing","pentesting","python","security"],"latest_commit_sha":null,"homepage":"https://github.com/juliosuas/vulcan","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juliosuas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T04:11:51.000Z","updated_at":"2026-04-20T05:58:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/juliosuas/vulcan","commit_stats":null,"previous_names":["juliosuas/vulcan"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/juliosuas/vulcan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juliosuas%2Fvulcan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juliosuas%2Fvulcan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juliosuas%2Fvulcan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juliosuas%2Fvulcan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juliosuas","download_url":"https://codeload.github.com/juliosuas/vulcan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juliosuas%2Fvulcan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32586218,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cybersecurity","ethical-hacking","penetration-testing","pentesting","python","security"],"created_at":"2026-05-03T22:05:58.775Z","updated_at":"2026-05-03T22:06:09.334Z","avatar_url":"https://github.com/juliosuas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n ██╗   ██╗██╗   ██╗██╗      ██████╗ █████╗ ███╗   ██╗\n ██║   ██║██║   ██║██║     ██╔════╝██╔══██╗████╗  ██║\n ██║   ██║██║   ██║██║     ██║     ███████║██╔██╗ ██║\n ╚██╗ ██╔╝██║   ██║██║     ██║     ██╔══██║██║╚██╗██║\n  ╚████╔╝ ╚██████╔╝███████╗╚██████╗██║  ██║██║ ╚████║\n   ╚═══╝   ╚═════╝ ╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═══╝\n```\n\n\u003ch1 align=\"center\"\u003e🌋 VULCAN\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eThe Sovereign AI Pentester\u003c/b\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ci\u003eFull-local. Zero API keys. 117 tools. One command.\u003c/i\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=for-the-badge\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/v2.0-BESTIA_MODE-red?style=for-the-badge\" alt=\"v2.0 Bestia Mode\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tools-117+-orange?style=for-the-badge\u0026logo=hackthebox\u0026logoColor=white\" alt=\"117 Tools\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/AI-local_%7C_cloud_%7C_hybrid-purple?style=for-the-badge\u0026logo=openai\u0026logoColor=white\" alt=\"Multi LLM\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/data-sovereign-black?style=for-the-badge\u0026logo=tor\u0026logoColor=white\" alt=\"Data Sovereign\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-why-vulcan\"\u003eWhy Vulcan\u003c/a\u003e •\n  \u003ca href=\"#-60-second-quick-start\"\u003e60-Second Quick Start\u003c/a\u003e •\n  \u003ca href=\"#-three-modes-one-binary\"\u003eThree Modes\u003c/a\u003e •\n  \u003ca href=\"#-how-it-works\"\u003eHow It Works\u003c/a\u003e •\n  \u003ca href=\"#-architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#-how-vulcan-fits-the-landscape\"\u003eLandscape\u003c/a\u003e •\n  \u003ca href=\"#-roadmap\"\u003eRoadmap\u003c/a\u003e •\n  \u003ca href=\"#%EF%B8%8F-disclaimer\"\u003eDisclaimer\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e ### ⚡ **v2.0 — BESTIA Mode just dropped.**\n\u003e One command. Full pentest. **No API keys. No egress. No vendor lock-in.**\n\u003e 117 security tools orchestrated by a ReAct-loop AI agent running entirely on your metal.\n\u003e ```bash\n\u003e ./run-beast.sh scanme.nmap.org\n\u003e ```\n\n---\n\n## 🤔 Why Vulcan?\n\nExisting pentest automation forces you to choose:\n\n- **Cloud AI** (Burp, commercial scanners) → your target data leaves the perimeter.\n- **Scriptable tools** (Metasploit, Nuclei) → powerful, but *you* still plan every step.\n- **LLM wrappers** (Claude Code, Copilot) → great for ideation, useless without tool execution.\n\n**Vulcan fuses all three.** A ReAct-loop agent plans the attack. A 127-tool API executes it. An LLM — cloud *or* local — drives decisions. Everything flows into a professional HTML/PDF report. Assessment-ready in one command.\n\n\u003e The AI thinks. The tools execute. You get the report.\n\n### 🎯 Who this is for\n\n- **Red teamers** who want a force-multiplier, not a replacement.\n- **CTF players** who want autonomous recon → exploit chains on HackTheBox / TryHackMe / VulnHub boxes.\n- **Bug bounty hunters** who need to cover wide scope fast.\n- **Security researchers** who refuse to ship target data to third-party clouds.\n- **Consultants** whose clients demand 100% on-prem tooling.\n\n---\n\n## ⚡ 60-Second Quick Start\n\n```bash\n# Clone\ngit clone https://github.com/juliosuas/vulcan.git \u0026\u0026 cd vulcan\n\n# Install\npython3 -m venv venv \u0026\u0026 source venv/bin/activate\npip install -r requirements.txt\n\n# Run — full autonomous pentest, local-only (no API keys required)\n./run-beast.sh scanme.nmap.org\n```\n\nThat's it. `run-beast.sh` auto-launches the HexStrike API, warms your local LLM, runs the full ReAct pipeline, and opens the HTML report in your browser.\n\n**Want to use Claude instead?**\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\nvulcan scan --target example.com --llm claude --hexstrike\n```\n\n**Want classic subprocess-only mode?**\n```bash\nvulcan scan --target example.com --llm claude\n```\n\n---\n\n## 🔥 Three Modes. One Binary.\n\nVulcan exposes two orthogonal axes — the LLM provider and the execution backend — giving you four deployment profiles:\n\n| Mode | Command | LLM | Tools | API keys | Egress | When to use |\n|------|---------|:---:|:---:|:---:|:---:|---|\n| 🔴 **BESTIA** (full-local) | `./run-beast.sh \u003ctarget\u003e` | smart-llm (Ollama, local) | HexStrike API (117 tools) | ❌ none | ❌ zero | Air-gapped labs · sensitive clients · CTF grind |\n| 🟡 **Hybrid** | `--llm claude --hexstrike` | Claude / GPT-4 | HexStrike API (117 tools) | ✅ LLM only | ⚠️ reasoning only | Best-of-both: heavy iron executing, frontier model thinking |\n| 🟢 **Cloud classic** | `--llm claude` | Claude / GPT-4 | Local subprocess (5 tools) | ✅ LLM only | ⚠️ reasoning only | Laptop, fast iteration, full frontier reasoning |\n| ⚫ **OSS-only** | `--llm openai` + Ollama base URL | Local Ollama model | Local subprocess | ❌ none | ❌ zero | Legacy hosts, minimal install |\n\n**Why this matters:** most \"AI pentest\" tools lock you into one cloud LLM *and* one tool orchestration choice. Vulcan lets you mix them independently — and switch modes with a single flag.\n\n---\n\n## 🧠 How It Works\n\nVulcan runs a **ReAct (Reason → Act → Observe)** loop — the canonical autonomous-agent pattern — across four phases:\n\n```\n                    ┌─────────────────────┐\n                    │     🎯 TARGET       │\n                    │   example.com       │\n                    └─────────┬───────────┘\n                              │\n              ┌───────────────┼───────────────┐\n              ▼               ▼               ▼\n        ┌──────────┐   ┌──────────┐   ┌──────────┐\n        │  RECON   │   │ PLANNING │   │ EXECUTION│\n        │ (auto)   │→ │  (LLM)   │→ │ (ReAct)  │\n        └──────────┘   └──────────┘   └─────┬────┘\n                                            │\n                                            ▼\n                                      ┌──────────┐\n                                      │  REPORT  │\n                                      │ HTML/PDF │\n                                      └──────────┘\n```\n\nInside the execution phase, every iteration:\n\n```\n🧠 REASON  ──►  LLM reads state, picks next action, emits JSON\n⚡  ACT     ──►  Vulcan dispatches to module → Executor → tool\n👁️  OBSERVE ──►  Parse output, extract findings, update conversation\n         ↑                                                    │\n         └────────────────── loop ←─────────────────────────┘\n                     (up to max_iterations=50)\n```\n\nThe LLM decides when to pivot, what to investigate deeper, when to drop a thread, and when the assessment is complete.\n\n---\n\n## ✨ Features\n\n| Feature | Description | v1 | v2 |\n|---|---|:---:|:---:|\n| 🧠 AI-driven attack planning | LLM plans \u0026 re-plans in real time | ✅ | ✅ |\n| 🔄 ReAct (Reason → Act → Observe) loop | Canonical autonomous-agent pattern | ✅ | ✅ |\n| 📡 Full recon pipeline | Subdomains · ports · tech · dirs · DNS | ✅ | ✅ |\n| 🔍 Automated vuln scanning | Nuclei + custom checks | ✅ | ✅ |\n| 💉 Exploitation modules | SQLi · XSS · SSRF · CMD injection | ✅ | ✅ |\n| 📊 Professional reports | HTML (validated) + PDF via weasyprint (optional) | ✅ | ✅ |\n| 🤖 Claude / GPT-4 support | Frontier cloud LLMs | ✅ | ✅ |\n| 🖥️ Rich CLI | Beautiful terminal UI | ✅ | ✅ |\n| 🐳 Docker | Isolated execution | ✅ | ✅ |\n| 🔴 **BESTIA mode** | **Full-local, zero API keys** | — | ✅ |\n| ⚔️ **HexStrike integration** | **5 → 127 security tools** | — | ✅ |\n| 🚀 **smart-llm routing** | **Local Ollama via heuristic router** | — | ✅ |\n| 🛡️ **Data sovereignty** | **Target data never leaves your host** | — | ✅ |\n| 🔀 **Mix-and-match modes** | **LLM × executor independent axes** | — | ✅ |\n| 🧩 **Graceful fallback** | **Auto-fallback to local subprocess if API down** | — | ✅ |\n\n---\n\n## 📊 How Vulcan fits the landscape\n\n| Capability | Vulcan v2 | Metasploit | Burp Pro | Nuclei |\n|---|:---:|:---:|:---:|:---:|\n| AI-driven planning | ✅ | ❌ | ❌ | ❌ |\n| Autonomous ReAct loop | ✅ | ❌ | ❌ | ❌ |\n| Recon → Exploit → Report pipeline | ✅ | ⚠️ Manual | ⚠️ Manual | ❌ Scan only |\n| Multi-tool orchestration | ✅ 117 tools | ❌ Single | ❌ Single | ❌ Single |\n| Runs 100% local (no cloud) | ✅ | ✅ | ❌ | ✅ |\n| **Local LLM reasoning** | ✅ | ❌ | ❌ | ❌ |\n| **Zero egress mode** | ✅ | ✅ | ❌ | ✅ |\n| Auto-generated reports | ✅ HTML (PDF opt.) | ⚠️ Basic | ✅ | ⚠️ JSON |\n| Natural language control | ✅ | ❌ | ❌ | ❌ |\n| Open source | ✅ MIT | ✅ | ❌ | ✅ MIT |\n| Docker ready | ✅ | ✅ | ❌ | ✅ |\n\n\u003e **Vulcan doesn't replace these tools — it orchestrates them.** Nmap, Nuclei, SQLMap, Gobuster, Subfinder, Hydra, NetExec, MSFVenom, Hashcat, FFuf, WPScan, Amass, and 100+ more run underneath, guided by AI.\n\u003e\n\u003e *Other autonomous-pentest projects exist (PentestGPT, Shennina, etc.) — Vulcan's differentiator is the independently swappable LLM × executor axes and the full-local BESTIA mode.*\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        VulcanAgent                               │\n│                    (ReAct Orchestrator)                          │\n├──────────────┬──────────────────┬──────────────┬────────────────┤\n│   Planner    │      LLM         │   Executor   │   Reporter     │\n│  (strategy)  │ ─────────────    │ ─────────────│ (HTML/PDF/JSON)│\n│              │  • Anthropic     │  • Subproc   │                │\n│              │  • OpenAI        │  • HexStrike │                │\n│              │  • smart-llm ⚡  │    API :8888 │                │\n├──────────────┴──────────────────┴──────────────┴────────────────┤\n│                             Modules                              │\n│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐ ┌──────────┐   │\n│  │  Recon  │ │ Scanner  │ │ Exploit  │ │ Web  │ │ Network  │   │\n│  └─────────┘ └──────────┘ └──────────┘ └──────┘ └──────────┘   │\n├──────────────────────────────────────────────────────────────────┤\n│                       Execution Layer                            │\n│   Local subprocess  ◄─────── OR ───────►  HexStrike API :8888   │\n│   (5 tools by default)                     (117 tools, shared)   │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### The key insight\n\nVulcan's executor is **swappable at init time**:\n\n- `Executor` → runs `nmap -sV target` via `asyncio.create_subprocess_shell` on localhost.\n- `HexStrikeExecutor` → parses the same command, POSTs to `/api/tools/nmap` on a remote HexStrike server, returns the same `ExecutionResult`.\n\n**Modules, tool wrappers, and the ReAct loop don't change.** You swap the executor with `--hexstrike` and you're now orchestrating 117 tools instead of 5, with caching, concurrency, and graceful fallback baked in.\n\n---\n\n## 🚀 Installation\n\n### Option 1: Full install (recommended)\n\n```bash\ngit clone https://github.com/juliosuas/vulcan.git\ncd vulcan\npython3 -m venv venv \u0026\u0026 source venv/bin/activate\npip install -r requirements.txt\n```\n\n### Option 2: Docker\n\n```bash\ngit clone https://github.com/juliosuas/vulcan.git\ncd vulcan\ndocker compose up --build\n```\n\n### Option 3: Pip (coming soon)\n\n```bash\npip install vulcan-pentest\n```\n\n### Config\n\n```bash\ncp .env.example .env\n# Edit .env with your keys (optional — BESTIA mode needs none)\n```\n\n```env\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\nVULCAN_LLM_PROVIDER=smartllm        # claude | openai | smartllm\nVULCAN_USE_HEXSTRIKE=1              # route through HexStrike :8888\nVULCAN_HEXSTRIKE_SERVER=http://127.0.0.1:8888\nVULCAN_SMARTLLM_BIN=smart-llm       # or absolute path\n```\n\n### Optional: local LLM stack (for BESTIA mode)\n\nInstall [Ollama](https://ollama.com), pull a model, and install [`smart-llm`](https://github.com/juliosuas/smart-llm) (the heuristic router):\n\n```bash\ncurl -fsSL https://ollama.com/install.sh | sh\nollama pull qwen3:32b        # recommended for reasoning\nollama pull qwen2.5-coder:7b # for code/payload tasks\n```\n\n### Optional: HexStrike AI (for 127-tool mode)\n\n```bash\ngit clone https://github.com/0x4m4/hexstrike-ai.git\ncd hexstrike-ai \u0026\u0026 python3 -m venv hexstrike-env \u0026\u0026 source hexstrike-env/bin/activate\npip install -r requirements.txt\n./hexstrike_server.py   # Flask API on :8888\n```\n\n---\n\n## 📖 Usage\n\n### BESTIA — zero keys, full pipeline\n\n```bash\n./run-beast.sh \u003ctarget\u003e [quick|standard|full]\n```\n\n### Classic scan (cloud LLM)\n\n```bash\nvulcan scan --target example.com --llm claude --mode full\n```\n\n### Hybrid (cloud LLM + HexStrike)\n\n```bash\nvulcan scan --target example.com --llm claude --hexstrike\n```\n\n### Recon only\n\n```bash\nvulcan recon --target example.com --modules subdomains,ports,tech,dirs,dns\n```\n\n### Generate report from existing data\n\n```bash\nvulcan report --input ./vulcan_output/example.com --format html\n# PDF: pip install weasyprint \u0026\u0026 vulcan report --input ./vulcan_output/example.com --format pdf\n```\n\n### All flags\n\n```\nvulcan scan --help\n\n  --target, -t               Target domain or IP              [required]\n  --mode, -m                 quick | standard | full          [standard]\n  --llm                      claude | openai | smartllm       [claude]\n  --local                    Shortcut: --llm smartllm --hexstrike\n  --hexstrike/--no-hexstrike Route tools through HexStrike    [off]\n  --hexstrike-url            HexStrike server URL             [http://127.0.0.1:8888]\n  --report                   html | pdf | json                [html]\n  --output, -o               Output directory                 [./vulcan_output]\n  --config, -c               YAML config path\n  --verbose, -v              Verbose output\n```\n\n---\n\n## 🔬 How BESTIA Mode Works Under the Hood\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  ./run-beast.sh scanme.nmap.org                         │\n└──────────┬──────────────────────────────────────────────┘\n           │\n    ┌──────▼──────────┐        ┌──────────────────────┐\n    │ Preflight       │───────►│ curl :8888/health    │\n    │                 │        │ if down → start      │\n    └──────┬──────────┘        └──────────────────────┘\n           │\n    ┌──────▼──────────┐        ┌──────────────────────┐\n    │ Warm smart-llm  │───────►│ Ollama models → VRAM │\n    │                 │        │ (avoid cold-start)   │\n    └──────┬──────────┘        └──────────────────────┘\n           │\n    ┌──────▼──────────┐\n    │ vulcan scan     │──── ReAct loop ──► smart-llm (qwen3:32b)\n    │   --local       │                         │\n    │                 │                         ▼\n    │                 │                    JSON action\n    │                 │                         │\n    │                 │         ┌───────────────┘\n    │                 ▼         ▼\n    │        ┌────────────────────────┐\n    │        │  HexStrikeExecutor     │──POST /api/tools/nmap──►  HexStrike :8888\n    │        │  (aiohttp + semaphore) │                           │\n    │        │                        │◄───JSON result─────────── ↓\n    │        └────────────────────────┘                      [subprocess · caching · recovery]\n    │                 │\n    │                 ▼\n    │        Finding extracted → Reporter\n    │\n    └──► xdg-open vulcan_output/*.html\n```\n\nEvery component degrades gracefully:\n- **HexStrike down** → `HexStrikeExecutor.fallback_local=True` silently falls back to subprocess.\n- **smart-llm missing** → raises with exact env var to set.\n- **Model cold** → `run-beast.sh --warmup` keeps them hot in VRAM with `keep_alive=24h`.\n\n---\n\n## ✅ Built-in Pentest Verification\n\nEvery Vulcan run includes verification checklists inspired by industry methodology:\n\n### Reconnaissance\n| Check | Criteria | How to confirm |\n|---|---|---|\n| Subdomain coverage | All passive + active sources queried | Compare subfinder/amass/DNS results |\n| Port scan completeness | Top 1000+ on all live hosts | Verify nmap params in output |\n| Service identification | Versions extracted for all open ports | Check `-sV` for \"unknown\" entries |\n| Scope compliance | No out-of-scope targets contacted | Cross-reference scope doc |\n\n### Vulnerability Scanning\n| Check | Criteria | How to confirm |\n|---|---|---|\n| Template coverage | Critical + High executed | Verify nuclei template count |\n| False-positive review | Each critical/high validated | Request/response pairs saved |\n| CVE mapping | Findings mapped to CVE IDs | CVE column populated in report |\n| Remediation guidance | Fix rec per finding | Review report remediation section |\n\n### Exploitation\n| Check | Criteria | How to confirm |\n|---|---|---|\n| Authorization | Explicit written permission | Scope doc reviewed before exploit |\n| Evidence capture | Proof documented | Screenshots / request-response saved |\n| Impact assessment | Business impact described | Impact field populated |\n| Cleanup | All test artifacts removed | Post-exploitation checklist done |\n\n### Report Quality\n| Check | Criteria | How to confirm |\n|---|---|---|\n| Exec summary | Non-technical overview present | Readable by C-suite |\n| Finding accuracy | No dupes/contradictions | Peer review or AI cross-check |\n| Severity distribution | Aligns with CVSS + business context | No Medium with Critical impact |\n| Remediation priority | Ordered by risk, not CVSS alone | Considers exploitability + asset value |\n\n---\n\n## 🖥️ Platform Compatibility\n\n| Platform | Status | Notes |\n|---|:---:|---|\n| Debian 12 | ✅ Tested | Primary dev + validation platform |\n| Kali / Parrot | 🟢 Expected | Derivatives of Debian; most tools pre-installed |\n| Ubuntu 22.04+ | 🟢 Expected | Debian-family; should work out of the box |\n| Arch / Fedora | 🟡 Untested | Python deps portable; tool install paths differ |\n| macOS 13+ (Apple Silicon) | 🟡 Untested | Homebrew for Nmap/Nuclei; Ollama native |\n| Windows 11 (WSL2) | 🟡 Untested | Run inside Ubuntu for best results |\n| Docker | 🟢 Expected | `docker compose up --build` (Dockerfile + compose file shipped, validation pending) |\n\n\u003e **Current validation status (v2.0):** end-to-end pipeline (recon → planning → ReAct → HTML report) validated against `scanme.nmap.org` on Debian 12 in both `--local` (BESTIA) and `--llm claude --hexstrike` (hybrid) modes. PDF export uses `weasyprint` (optional dep, untested this release). Other platforms expected to work but not independently verified yet — PRs confirming are welcome.\n\n### LLM Compatibility\n\n| Provider | Models | BESTIA? | Notes |\n|---|---|:---:|---|\n| Anthropic | Claude Sonnet 4 / Opus | ❌ (cloud) | Recommended for frontier reasoning |\n| OpenAI | GPT-4o / GPT-4 Turbo | ❌ (cloud) | Fully supported |\n| **smart-llm + Ollama** | **qwen3:32b / qwen2.5-coder:7b** | ✅ | **Default in BESTIA mode** |\n| LiteLLM proxy | 100+ models | ⚠️ Experimental | Via OpenAI-compatible base URL |\n\n---\n\n## 🗺️ Roadmap\n\n- [x] Core ReAct loop with Claude/GPT-4\n- [x] Recon · Scanner · Exploit · Web · Network modules\n- [x] HTML/PDF/JSON report generation\n- [x] Rich CLI + beautiful terminal UI\n- [x] Docker support\n- [x] **v2.0 — HexStrike integration (117 tools)**\n- [x] **v2.0 — smart-llm local-only mode**\n- [x] **v2.0 — Graceful subprocess fallback**\n- [x] **v2.0 — Hybrid mode (cloud LLM + local exec)**\n- [ ] 🔜 Plugin system for custom tool integration\n- [ ] 🔜 Multi-target campaign mode\n- [ ] 🔜 API server mode (REST + WebSocket)\n- [ ] 🔜 Collaborative mode (agent swarms)\n- [ ] 🔜 MITRE ATT\u0026CK mapping per finding\n- [ ] 🔜 Evidence chain visualization (graph)\n- [ ] 🔜 OWASP ZAP integration\n- [ ] 🔜 Slack / Discord / Telegram webhooks\n- [ ] 🔜 Cloud deployment templates (AWS/GCP)\n- [ ] 🔜 CTF-specific heuristics (flag sniffing, well-known ports)\n- [ ] 🔜 Replay mode (re-run from cached output, zero tool exec)\n\n---\n\n## 🤝 Contributing\n\nPRs are welcome — especially new tool wrappers, additional LLM providers, and report templates.\n\n1. Fork → `git checkout -b feat/your-feature`\n2. `pip install -e \".[dev]\"`\n3. `python -m pytest tests/`\n4. Open a PR with a clear description\n\n### Guidelines\n- Follow existing code style (Black, 100 char lines)\n- Add tests for new features\n- Keep PRs focused and atomic\n- New tool wrappers must subclass `ToolWrapper` in `tools/wrapper.py`\n- New LLM providers must implement `_call_llm()` in `core/agent.py`\n\n---\n\n## ⚠️ Disclaimer\n\n\u003e **⚠️ AUTHORIZED USE ONLY**\n\u003e\n\u003e Vulcan is designed **exclusively for authorized security testing and educational purposes**.\n\u003e\n\u003e - **Always** obtain **explicit written permission** before testing any system.\n\u003e - **Never** use this tool against systems you do not own or have authorization to test.\n\u003e - Unauthorized access to computer systems is **illegal** in most jurisdictions.\n\u003e - Users are **solely responsible** for ensuring compliance with all applicable laws.\n\u003e - The authors and contributors assume **no liability** for misuse.\n\u003e\n\u003e By using Vulcan, you agree to use it responsibly and legally. When in doubt, **don't run it**.\n\n**Legal testing sandboxes to learn on:** `scanme.nmap.org` · [HackTheBox](https://hackthebox.com) · [TryHackMe](https://tryhackme.com) · [VulnHub](https://vulnhub.com) · [DVWA](https://github.com/digininja/DVWA) · [OWASP Juice Shop](https://owasp.org/www-project-juice-shop/).\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eBuilt with 🌋 by \u003ca href=\"https://github.com/juliosuas\"\u003e@juliosuas\u003c/a\u003e\u003c/b\u003e\u003cbr\u003e\n  \u003csub\u003eIf Vulcan saves you a weekend, consider dropping a ⭐\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/juliosuas/vulcan/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/juliosuas/vulcan?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/juliosuas/vulcan/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/juliosuas/vulcan?style=social\" alt=\"Forks\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/juliosuas/vulcan/watchers\"\u003e\u003cimg src=\"https://img.shields.io/github/watchers/juliosuas/vulcan?style=social\" alt=\"Watchers\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n### 🌱 Also from @juliosuas\n- **[Ghost](https://github.com/juliosuas/ghost)** — AI-powered OSINT platform\n- **[Phantom](https://github.com/juliosuas/phantom)** — LLM red teaming · OWASP Top 10 for LLMs\n- **[Sentinel](https://github.com/juliosuas/sentinel)** — AI-powered SOC · real-time log analysis\n- **[Cerberus](https://github.com/juliosuas/cerberus)** — Security-as-a-Service for SMBs\n- **[AI Garden](https://github.com/juliosuas/ai-garden)** — A pixel-art world built by AI agents. Watch it grow.\n\n### 🙏 Built on top of\n- **[HexStrike AI](https://github.com/0x4m4/hexstrike-ai)** by [@0x4m4](https://github.com/0x4m4) — the 117-tool Flask API that powers BESTIA mode's execution layer.\n- **[Ollama](https://ollama.com)** — the local LLM runtime.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuliosuas%2Fvulcan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuliosuas%2Fvulcan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuliosuas%2Fvulcan/lists"}