https://github.com/jayelbotvibe-web/hermes-pentest-lab
Production-grade pentesting lab — Docker Compose tool isolation, AI agent orchestration, WireGuard OPSEC, LUKS encryption, automated PDF reports
https://github.com/jayelbotvibe-web/hermes-pentest-lab
ai-agent cybersecurity docker hermes-agent pentesting report-generation security-tools vulnerability-assessment
Last synced: about 18 hours ago
JSON representation
Production-grade pentesting lab — Docker Compose tool isolation, AI agent orchestration, WireGuard OPSEC, LUKS encryption, automated PDF reports
- Host: GitHub
- URL: https://github.com/jayelbotvibe-web/hermes-pentest-lab
- Owner: jayelbotvibe-web
- License: mit
- Created: 2026-06-22T05:57:17.000Z (14 days ago)
- Default Branch: master
- Last Pushed: 2026-06-30T05:33:34.000Z (6 days ago)
- Last Synced: 2026-06-30T07:16:50.839Z (6 days ago)
- Topics: ai-agent, cybersecurity, docker, hermes-agent, pentesting, report-generation, security-tools, vulnerability-assessment
- Language: HTML
- Homepage: https://jayelbotvibe-web.github.io/hermes-pentest-lab/
- Size: 3.73 MB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Hermes Pentest Lab
> **Turn any Linux laptop into a production-grade pentesting workstation — with AI agent orchestration, Docker tool isolation, VPN OPSEC, encrypted storage, and automated report generation.**
>
> **⚠️ Requires host networking** — nmap raw sockets, crackmapexec SMB, and responder need `network_mode: host`. Docker Desktop users: set up a Linux VM with bridged networking.
[](LICENSE)
[](https://github.com/NousResearch/hermes-agent)
[](docker/docker-compose.yml)
[](skills/)
[](#-finding-knowledge-base-new)
[](https://jayelbotvibe-web.github.io/hermes-pentest-lab/)
[](#-tools-included)
[](scripts/pentest-canary.sh)
[](reports/templates/)
---
## What It Looks Like
```text
$ hermes
/skill pentest-engage
Agent: Validating scope... ✓ 192.168.1.0/24 authorized
VPN check... ✓ wg0 UP
LUKS check... ✓ /dev/mapper/pentest mounted
Pre-flight checks complete. 6/6 subagents ready.
Agent: OSINT agent → 12 subdomains, 47 email addresses found
Recon agent → 14 live hosts, 3 high-value services
Web agent → SQLi confirmed on /login (CVSS 9.8)
Network agent → Kerberoastable account: svc_sql
Agent: Building report...
Findings: 2 Critical, 1 High, 4 Medium, 3 Low
Risk level: Critical
Report saved: reports/acme-corp-2026-07/report-2026-07-01.pdf
Engagement complete. All actions logged to audit trail.
```
---
## 📊 Sample Reports
Two reports from live assessments — one vulnerable target, one hardened production site.
| | Juice Shop Benchmark | ZeroDayBrief Blog |
|---|---|---|
| **Risk** | 🔴 High (38/100) | 🟢 Low (94/100) |
| **Findings** | 14 (0C/1H/8M/5L) | 1 (Info) |
| **Controls** | 6 Pass / 3 Warn / 7 Fail | 15 Pass / 0 Warn / 1 Fail |
| **Target** | OWASP Juice Shop v20.0.0 | zerodaybrief.blog |
| **PDF** | [juice-shop-benchmark-report.pdf](docs/reports/samples/juice-shop-benchmark-report.pdf) (337KB) | [zerodaybrief-report.pdf](docs/reports/samples/zerodaybrief-report.pdf) (43KB) |
| **HTML** | [View](https://jayelbotvibe-web.github.io/hermes-pentest-lab/reports/samples/juice-shop-benchmark-report.html) | [View](https://jayelbotvibe-web.github.io/hermes-pentest-lab/reports/samples/zerodaybrief-report.html) |
**Design:** Dark gradient cover · 4-category scorecards · findings heatmap · inline evidence screenshots · business-first descriptions · observed controls with values · remediation checklist · A4 portrait print-native
*Generated by `build-report.py` v2 — automated CVSS impact generation, per-finding screenshot embedding, findings heatmap, 5-phase methodology.*
---
## 🚀 Quick Start
### What You Need
- **Linux with Docker + Docker Compose v2** (Ubuntu 24.04+, Debian, Kali recommended)
- **30GB free disk, 8GB RAM**
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** (for AI orchestration)
### 1. Clone and install dependencies
```bash
git clone https://github.com/jayelbotvibe-web/hermes-pentest-lab.git
cd hermes-pentest-lab
sudo apt install -y docker.io docker-compose-v2 wireguard-tools age cryptsetup pandoc
```
### 2. Build Docker images
```bash
docker build -t hermes-kali-web:latest -f docker/Dockerfile.kali-web .
docker build -t hermes-kali-net:latest -f docker/Dockerfile.kali-net .
docker build -t hermes-osint-tools:latest -f docker/Dockerfile.osint-tools .
```
### 3. Start the tools
```bash
docker compose -f docker/docker-compose.yml --profile web --profile net --profile osint up -d
docker compose -f docker/docker-compose.yml exec kali-web apt update && apt install -y ffuf nuclei sqlmap gobuster wpscan
docker compose -f docker/docker-compose.yml exec kali-net apt update && apt install -y nmap metasploit-framework crackmapexec bloodhound certipy-ad
docker compose -f docker/docker-compose.yml exec osint-tools pip install theHarvester shodan censys
```
### 4. Run your first engagement
```bash
./scripts/init-engagement.sh my-first-test
docker compose -f docker/docker-compose.yml exec kali-net nmap -sV -p1-1000 127.0.0.1
./scripts/build-report.py my-first-test
```
You'll get a professional PDF report at `reports/my-first-test/report-*.pdf`.
### 5. Use the AI orchestrator
In a Hermes Agent session:
```
/skill pentest-engage
```
Then describe what you want to test — Hermes handles the rest.
### 6. Practice on lab targets
```bash
docker compose -f docker/docker-compose.yml --profile lab up -d
# Juice Shop: http://127.0.0.1:3000
# DVWA: http://127.0.0.1:8080 (admin/password)
```
---
## Architecture
```mermaid
flowchart TB
classDef external fill:#1e293b,stroke:#94a3b8,color:#fff
classDef orchestrator fill:#083344,stroke:#22d3ee,color:#fff
classDef agent fill:#064e3b,stroke:#34d399,color:#fff
classDef docker fill:#78350f,stroke:#fbbf24,color:#fff
classDef crypto fill:#2e1065,stroke:#a78bfa,color:#fff
classDef security fill:#881337,stroke:#fb7185,color:#fff
classDef native fill:#0f172a,stroke:#64748b,color:#fff
P["🧑💻 Pentester (You)"]:::external
C["🏢 Client"]:::external
H["⚡ Hermes Agent
Orchestrator
pentest-engage skill"]:::orchestrator
OS["🔍 OSINT Agent
Passive — zero packets
theHarvester · crt.sh"]:::agent
RC["📡 Recon Agent
Active — T3/500pps
nmap · masscan"]:::agent
WB["🌐 Web Agent
Active — safe mode
ffuf · nuclei · sqlmap"]:::agent
NW["🖥️ Network Agent
Active — user approved
bloodhound · certipy"]:::agent
RP["📄 Report Agent
Output — read-only
CVSS 3.1 · Jinja2 → PDF"]:::agent
SC["🛡️ Scope Agent
Guard — always first
validate · audit.jsonl"]:::agent
DW["🐳 Docker: web"]:::docker
DN["🐳 Docker: net"]:::docker
DO["🐳 Docker: osint"]:::docker
DC["🐳 Docker: cloud"]:::docker
DF["🐳 Docker: full"]:::docker
DL["🐳 Docker: lab"]:::docker
DB["🗄️ Findings DB v2
SQLite · 6 tables"]:::crypto
GI["📦 Engagement Git
audit trail"]:::crypto
N4["🧬 Neo4j 5.26
BloodHound CE"]:::docker
VP["🔐 WireGuard VPN
wg0"]:::security
KS["🚫 Kill Switch
iptables DROP"]:::security
LK["🔒 LUKS 10GB
dm-crypt encrypted"]:::crypto
PS["🔑 pass + age
GPG credential vault"]:::crypto
BU["🪲 Burp Suite CE"]:::native
WS["🦈 Wireshark 4.6"]:::native
HC["🔨 hashcat 7.1
GPU CUDA"]:::native
FX["🦊 Firefox
FoxyProxy"]:::native
RB["📝 Report Builder
WeasyPrint → PDF"]:::native
P --> H
H --> OS & RC & WB & NW & RP & SC
OS --> DO
RC --> DW & DN
WB --> DW
NW --> DN
RP --> RB
SC --> GI
RP --> C
H --> PS
DW & DN & DO --> VP
VP --> KS
DB --- GI
N4 --- DN
BU & WS & HC & FX --- DW & DN
```
> **Open `pentest-architecture-complete.html`** in any browser for the full interactive diagram with color-coded layers.
### How It Works
1. **You** tell Hermes what to test (e.g., "Scan 192.168.1.0/24")
2. **Hermes** checks the scope, starts the VPN, and dispatches subagents in parallel
3. **Each subagent** runs tools inside isolated Docker containers
4. **Findings** flow into a shared SQLite database
5. **Report agent** generates a professional PDF with CVSS scores
6. **Audit trail** logs every action
---
## 🛠️ Tools Included
> 💻 = Host 🐳 = Docker container `:port` = web access
### Web Application Testing
| Tool | Container | Purpose |
|------|-----------|---------|
| ffuf | 🐳 web | Directory/file brute-force, virtual host discovery |
| nuclei | 🐳 web | CVE and misconfiguration scanning (6,683 templates) |
| sqlmap | 🐳 web | Automated SQL injection detection |
| gobuster | 🐳 web | Directory, DNS, and VHOST enumeration |
| wpscan | 🐳 web | WordPress vulnerability scanner |
| whatweb | 🐳 web | Technology fingerprinting |
### Network & Active Directory
| Tool | Container | Purpose |
|------|-----------|---------|
| nmap | 🐳 net | Port scanning, service detection, OS fingerprinting |
| metasploit | 🐳 net | Exploitation framework (6.4) — gated |
| crackmapexec / nxc | 🐳 net | SMB/LDAP/WinRM enumeration and authentication |
| bloodhound-python | 🐳 net | Active Directory attack path analysis |
| certipy-ad | 🐳 net | AD Certificate Services exploitation |
| kerbrute | 🐳 net | Kerberos user enumeration and password spraying |
| impacket | 🐳 net | Windows protocol tools (secretsdump, GetUserSPNs) |
| responder | 🐳 net | LLMNR/NBT-NS/mDNS poisoning — gated |
| evil-winrm | 🐳 net | Windows Remote Management shell |
| enum4linux | 🐳 net | SMB enumeration |
| hydra | 🐳 net | Online brute-force (user-approved only) |
| john / hashcat | 🐳 net | Password hash cracking |
### OSINT & Passive Recon
| Tool | Container | Purpose |
|------|-----------|---------|
| theHarvester | 🐳 osint | Email, subdomain, and name enumeration |
| holehe | 🐳 osint | Check if email is registered on services |
| sherlock | 🐳 osint | Username search across 300+ social networks |
| crt.sh | 🐳 osint | Certificate transparency log subdomain discovery |
| shodan | 🐳 net | Internet-connected device search engine |
### Infrastructure
| Service | Access | Purpose |
|---------|--------|---------|
| Neo4j 5.26 | 🐳 net `:7474` `:7687` | BloodHound CE graph database |
| Juice Shop | 🐳 lab `:3000` | OWASP vulnerable web app (practice) |
| DVWA | 🐳 lab `:8080` | Damn Vulnerable Web App (practice) |
### Native Tools
| Tool | Runtime | Purpose |
|------|---------|---------|
| Burp Suite CE | 💻 Host | Intercepting proxy (653MB .jar) |
| Wireshark 4.6 | 💻 Host | Packet capture analysis |
| hashcat 7.1 | 💻 Host | GPU password cracking |
| Firefox + FoxyProxy | 💻 Host | Manual web testing |
| Report Builder | 💻 Host | Jinja2 → WeasyPrint → PDF → DOCX |
---
## 🤖 AI Subagents
7 specialized agents — each with deep domain knowledge, Pre-flight checks, and rate limiting.
| Agent | Phase | Tier | What It Does | Output |
|-------|-------|------|-------------|--------|
| Scope | 1️⃣ Guard | 🛡️ Always first | Validates every target against scope, logs audit trail | `{allowed, reason}` |
| OSINT | 2️⃣ Passive | 🟢 Zero packets | Gathers intel without touching target | `{subdomains, emails, tech}` |
| Recon | 3️⃣ Active | 🟡 Rate-limited | Port scans, service detection, OS fingerprinting | `{hosts, ports, services}` |
| Web | 4️⃣ Active | 🟡 Rate-limited | Directory brute, CVE scan, SQLi testing | `{vulns, endpoints, confidence}` |
| Network | 5️⃣ Active | 🔴 Needs approval | SMB, LDAP, Kerberos, BloodHound, AD CS | `{shares, users, paths}` |
| Report | 6️⃣ Output | ⚪ Read-only | CVSS 3.1, finding docs, PDF generation | `{report.md, report.pdf}` |
| **Findings KB** | 🆕 Support | 📖 Load anytime | Maps tool output → severity + CVSS + report language | 14 interpretations, 5 categories |
| Guard | How |
|-------|-----|
| Pre-flight checks | VPN up? Target in scope? LUKS mounted? Canary passed? — every run |
| Rate limiting | 500 pps (nmap), 50 req/s (web), 3 tiers (safe/normal/fast) |
| Destructive test gating | Exploits, credential spraying, responder → explicit user approval |
| Hard refusal list | 13 items — DoS, mass scan, autonomous exploit, false-flag, etc. |
| Audit trail | Every action logged: timestamp, tool, target, scope validated |
| Finding sovereignty | Tool + version + command on every finding, DRAFT until approved |
| Cross-validation | Critical findings (CVSS ≥ 9.0) require second-tool confirmation |
| Confidence levels | HIGH (multi-tool) / MEDIUM (single) / LOW (auto-only) / TENTATIVE (degraded) |
---
## 📊 Report Pipeline
```
Findings DB (SQLite) → Jinja2 Templates → WeasyPrint → PDF
↓
Pandoc → DOCX (editable reports)
```
### What's in the report
| Section | Audience | Contents |
|---------|----------|----------|
| Executive Summary | C-suite | Risk level, finding counts, top 3 recommendations |
| Methodology | Technical leads | PTES phases, tools used, timeline |
| Technical Findings | Developers | CVSS 3.1 vectors, PoC steps, evidence, remediation |
| Remediation Roadmap | IT team | Prioritized fix list with effort estimates |
| Appendix | Auditors | Raw scan data, scope document, audit trail, glossary |
---
## 🔐 OPSEC & Encryption
| Layer | Technology | What It Protects |
|-------|-----------|-----------------|
| VPN | WireGuard (commercial VPN provider) | Hides your home IP from targets |
| Kill Switch | iptables DROP | Blocks ALL traffic if VPN drops |
| DNS | VPN provider DNS | Prevents DNS leak to ISP |
| Disk | LUKS dm-crypt (10GB) | Engagement data encrypted at rest |
| Credentials | pass (GPG-encrypted git) | Client passwords, API keys, VPN configs |
| Archives | age encryption | Post-engagement legal hold archives |
| Audit | audit.jsonl | Every tool run logged with scope validation |
| Backup | USB (age-encrypted) | Disaster recovery — all keys in one file |
---
## 📁 Repo Structure
```
hermes-pentest-lab/
├── README.md
├── .gitignore
├── docs/
│ ├── index.html ← GitHub Pages landing page
│ ├── pentest-architecture-complete.html ← interactive system diagram
│ ├── pentest-architecture.html
│ ├── pentest-ops-architecture.html
│ ├── TROUBLESHOOTING.md
│ ├── WORKFLOW.md
│ └── reports/samples/
│ ├── juice-shop-benchmark-report.{html,pdf} ← 14 findings, 38/100
│ ├── zerodaybrief-report.{html,pdf} ← 1 finding, 94/100
│ ├── report-preview.png
│ └── screenshots/ ← evidence screenshots (F-XXX-*.png)
├── docker/
│ ├── docker-compose.yml ← 7 services, 6 profiles
│ ├── Dockerfile.kali-web ← kalilinux/kali-rolling + nuclei, ffuf, gobuster
│ ├── Dockerfile.kali-net ← kalilinux/kali-rolling + nmap, crackmapexec, impacket
│ └── Dockerfile.osint-tools ← python:3.12-slim + theHarvester, holehe, sherlock
├── scripts/
│ ├── pentest-canary.sh ← validates all tools before session
│ ├── pentest-up.sh ← starts containers + LUKS mount
│ ├── pentest-down.sh ← graceful shutdown + cleanup
│ ├── pentest-verify.sh ← post-startup verification
│ ├── init-engagement.sh ← creates forensics-style engagement dir
│ ├── init-engagement-db.py ← SQLite schema (6 tables)
│ ├── build-report.py ← findings → Jinja2 → HTML + PDF
│ ├── audit-log.sh ← scope-validated audit entries
│ ├── preflight.sh ← VPN + LUKS + DNS + scope checks
│ ├── wipe-engagement.sh ← encrypted archive + destruction cert
│ ├── capture-evidence.sh ← headless Chromium screenshots
│ └── convert-docs.py ← MarkItDown: PDF/DOCX → markdown
├── reports/templates/report.html ← unified Jinja2 template (v2)
├── tools/
│ └── tool-catalog.yaml ← 18 tools with version, fallback, rate limits
├── skills/
│ ├── pentest-context.md ← system map — loaded every session
│ ├── pentest-engage.md ← orchestrator — dispatches subagents
│ ├── pentest-ops.md ← startup/shutdown/repair/troubleshooting
│ ├── pentest-findings/SKILL.md ← 🆕 finding encyclopedia — 14 interpretations
│ ├── subagent-{osint,recon,web,net,report,scope}.md
│ └── safety-guards.md ← 13-item refusal list + rate limits
└── scope/
├── _template.json ← scope template (copied into engagements)
└── contract-template.md ← rules of engagement
```
### Engagement Directory (created by `init-engagement.sh`)
```
engagements//
├── ENGAGEMENT.yaml ← client, dates, status, assessor
├── scope.json ← scope definition (IPs, domains, signed)
├── findings.db ← SQLite database (6 tables)
├── findings.json ← machine-readable findings export
├── metadata.json ← controls, observations, methodology
├── audit/
│ └── actions.jsonl ← every tool run, scope-validated
├── evidence/ ← client documents (auto-converted via MarkItDown)
├── screenshots/ ← tool evidence (F-XXX-*.png auto-attach in report)
├── raw/scans/ ← nmap XML, nuclei JSON, tool output
└── reports/ ← generated HTML + PDF reports
```
---
## 🆚 How It Compares
> *Based on publicly available documentation as of June 2026. Features may have changed. Verify independently.*
| Feature | Hermes Pentest Lab | Tool A | Tool B |
|---------|-------------------|--------|--------|
| Agent runtime | Hermes Agent | LLM + MCP | Workflow engine |
| Subagents | 7 (customizable) | ~15 specialist | 0 |
| **Finding KB** | **14-entry encyclopedia** | None | None |
| Tool isolation | Docker Compose profiles | pip packages | Docker |
| Report generation | Jinja2 + WeasyPrint → PDF | Built-in | Manual |
| VPN / OPSEC | WireGuard + kill switch + DNS leak | None | None |
| Encryption | LUKS + pass + age | None | None |
| Scope guard | 13-item refusal list | Scope file | Check only |
| Findings DB | SQLite v2 (6 tables, versioned) | Findings DB | None |
| Session canary | Validates all tools before work | None | None |
| Client contracts | RoE template included | None | None |
**Hermes Pentest Lab** is built for the **practicing professional** — it prioritizes safety, audit trails, and client deliverables over autonomous exploitation.
---
## 🎓 Learning Path
1. **[PortSwigger Academy](https://portswigger.net/web-security)** — free, all web security labs
2. **Juice Shop** — `docker compose --profile lab up -d` → http://127.0.0.1:3000
3. **DVWA** — http://127.0.0.1:8080 (admin/password, set security to "low")
4. **Portfolio reports** — see sample reports above in [`reports/samples/`](docs/reports/samples/)
---
## ⚠️ Legal
This toolkit is for **authorized security testing only**. Never use it on systems you don't own or have explicit written permission to test. Every engagement requires a signed scope document (`scope/contract-template.md`). Every tool run is logged to an audit trail. Every report includes a data destruction certificate.
---
## 📄 License
MIT — use it, modify it, share it. Built by [@jayelbotvibe-web](https://github.com/jayelbotvibe-web).