# Hermes Pentest Lab

> **Turn any Kali Linux laptop into a production-grade pentesting workstation — with AI agent orchestration, native tooling, VPN OPSEC, encrypted storage, and automated report generation.**
>
> **⚠️ Requires Kali Linux** — tools run natively on the host for raw sockets, SMB, and packet capture. Docker is used only for lab targets and Neo4j.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Hermes Agent](https://img.shields.io/badge/Hermes%20Agent-Compatible-purple.svg)](https://github.com/NousResearch/hermes-agent)
[![Docker](https://img.shields.io/badge/Docker-3%20profiles-blue.svg)](docker/docker-compose.yml)
[![Subagents](https://img.shields.io/badge/Subagents-7-green.svg)](skills/)
[![MCP](https://img.shields.io/badge/MCP-tool--server-8b5cf6.svg)](mcp_server/)
[![Frameworks](https://img.shields.io/badge/ATT%26CK%20%2B%20OWASP-mapped-0ea5e9.svg)](#-new-capabilities)
[![Findings KB](https://img.shields.io/badge/finding_KB-14_entries-f59e0b)](#-finding-knowledge-base-new)
[![Sample Reports](https://img.shields.io/badge/Sample%20Reports-2-gold.svg)](https://jayelbotvibe-web.github.io/hermes-pentest-lab/)
[![Tools](https://img.shields.io/badge/Tools-16_cataloged-orange.svg)](#-tools-included)
[![Canary](https://img.shields.io/badge/canary-active-brightgreen)](scripts/pentest-canary.sh)
[![Templates](https://img.shields.io/badge/Templates-5-teal.svg)](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. 7/7 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
       Verify agent → 5 DRAFT findings verified: 2 CORROBORATED, 1 GATED

Agent: Building report...
       Findings: 2 Critical, 1 High, 4 Medium, 3 Low
       Risk level: Critical
       Verification: 2 corroborated · 1 gated · 2 unverified · 0 refuted

Report saved: reports/acme-corp-2026-07/report-2026-07-01.pdf
Engagement complete. All actions logged to audit trail.
```

---

## Architecture

<div align="center">

[![System architecture](https://raw.githubusercontent.com/jayelbotvibe-web/hermes-pentest-lab/master/docs/pentest-reference.png)](https://raw.githubusercontent.com/jayelbotvibe-web/hermes-pentest-lab/master/docs/pentest-reference.png)

**[System Architecture](https://jayelbotvibe-web.github.io/hermes-pentest-lab/pentest-reference.html)** — full inventory: subagents, DB schema, OPSEC

[![Verification pipeline](https://raw.githubusercontent.com/jayelbotvibe-web/hermes-pentest-lab/master/docs/verification-pass.png)](https://raw.githubusercontent.com/jayelbotvibe-web/hermes-pentest-lab/master/docs/verification-pass.png)

**[Verification Pipeline](https://jayelbotvibe-web.github.io/hermes-pentest-lab/verification-pass-architecture.html)** — verdict router, taxonomy, L1-L6

</div>

### 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 **7 subagents** in parallel
3. **Each subagent** runs tools natively on the Kali host
4. **Findings** flow into a shared SQLite v5 database
5. **Verify agent** independently reproduces every DRAFT finding — benign only
6. **Report agent** generates a professional PDF with verdict badges and confidence tiers
7. **Audit trail** logs every action

---

## 🆕 New Capabilities

Four additions layered on the safety-first core — each shipped independently with its own stdlib test suite:

### 🔌 MCP tool-server — guardrails enforced in code
The toolchain is exposed over the [Model Context Protocol](https://modelcontextprotocol.io) so any MCP client (Claude Code / Desktop, Cursor) can drive it. Unlike the skill docs — which *ask* an agent to check scope and keep rate limits on — every target-touching tool routes through `scope-check.py` before running and appends to the tamper-evident audit chain after. The **scope, VPN, rate-limit, and audit guardrails are enforced in code and cannot be bypassed** by the calling agent. Destructive tools (sqlmap/hydra/metasploit/responder) stay operator-run.

```bash
make mcp     # stdio server — full detail in mcp_server/README.md
```

### 🎯 MITRE ATT&CK + OWASP Top 10 mapping
Findings carry optional `attack_technique` / `owasp_category` tags that render a **Framework Mapping** coverage section in the report, so defenders can align remediation with the frameworks they already track. Delivered as an additive, idempotent DB migration (`migrate-add-attack-owasp.py`, v4 → v5).

### 📚 Reusable findings library
15 pre-approved, **generic** finding templates (`reports/findings-library.json`) with `{placeholder}` text and pre-applied ATT&CK/OWASP tags + CVSS — render one instead of writing a finding from scratch:

```bash
python3 scripts/add-finding.py <engagement> sql-injection --set host=10.0.0.5 endpoint=/login parameter=id
```

### 🔁 Retest / delta tracking
Mark findings **open / fixed / regressed** across retest rounds (`retest.py`); the report renders a **Remediation Progress** section with the remediation rate and per-finding status. Status is asserted after re-testing — never guessed — and every mark is written to the audit chain.

---

## 📊 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) |

<div align="center"><img src="docs/reports/samples/report-preview.png" alt="Report Preview" width="50%"></div>

**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` v4 — automated CVSS impact generation, per-finding screenshot embedding, findings heatmap, 6-phase methodology (incl. verification pass).*

---

## 🚀 Quick Start

Three levels, depending on how much you want. Full detail in [INSTALL.md](INSTALL.md).

**Reference only** — the skills, scope engine, and tests, nothing installed:

```bash
git clone https://github.com/jayelbotvibe-web/hermes-pentest-lab.git
cd hermes-pentest-lab
make test        # needs only Python 3.8+
```

**Practice lab** (~15 min) — bundled vulnerable targets, no VPN or vault. For
learning against Juice Shop / DVWA on localhost:

```bash
./install.sh --minimal
docker compose -f docker/docker-compose.yml --profile lab up -d   # targets
make doctor
```

**Full engagement setup** (~30 min) — encrypted vault, VPN OPSEC gate, and the
full toolchain (native on Kali, or the kali-* containers elsewhere):

```bash
./install.sh                                    # interactive
bash scripts/create-pentest-vault.sh --size 40G # encrypted client-data vault
```

On **Kali**, tools run natively — install them once:

```bash
sudo apt install -y nmap metasploit-framework ffuf gobuster wpscan sqlmap   hydra john enum4linux whatweb responder impacket-scripts evil-winrm seclists   wireguard-tools age cryptsetup
pipx install netexec bloodhound certipy-ad theHarvester holehe sherlock
```

On a **non-Kali host**, use the tool containers instead:

```bash
make images                          # build kali-web / kali-net / osint-tools
# then set PENTEST_USE_CONTAINERS=true in your config
```

Stuck at any point:

```bash
make doctor      # what is missing, and the command that fixes it
```

### Daily use

```bash
mount-pentest-vault                       # open the encrypted vault
bash scripts/init-engagement.sh acme-2026 # start an engagement
bash scripts/preflight.sh acme-2026       # authorization gate (VPN + signed scope)
# ... work ...
bash scripts/build-report.py acme-2026    # PDF report
unmount-pentest-vault                     # close when done
```

### AI orchestrator

In a Hermes Agent session: `/skill pentest-engage`, then describe the engagement.

### MCP tool-server (any MCP client)

Drive the same toolchain from Claude Code / Desktop or Cursor — with the scope,
VPN, rate-limit, and audit guardrails **enforced in code**, not just documented:

```bash
make mcp     # launches the stdio server (mcp_server/)
```

Point a client at `scripts/pentest-mcp.sh` (see
[`mcp_server/mcp.json.example`](mcp_server/mcp.json.example)). Every
target-touching tool refuses out-of-scope targets, injects the engagement's
rate tier, and appends to the tamper-evident audit chain before it runs.
Destructive tools stay operator-run. Details:
[`mcp_server/README.md`](mcp_server/README.md).

---

## 🛠️ Tools Included

> 💻 = Native host &nbsp; 🐳 = Docker service &nbsp; `:port` = web access

### Web Application Testing

| Tool | Runtime | Purpose |
|------|---------|---------|
| ffuf | 💻 Host | Directory/file brute-force, virtual host discovery |
| nuclei | 💻 Host | CVE and misconfiguration scanning (6,683 templates) |
| sqlmap | 💻 Host | Automated SQL injection detection |
| gobuster | 💻 Host | Directory, DNS, and VHOST enumeration |
| wpscan | 💻 Host | WordPress vulnerability scanner |
| whatweb | 💻 Host | Technology fingerprinting |

### Network & Active Directory

| Tool | Runtime | Purpose |
|------|---------|---------|
| nmap | 💻 Host | Port scanning, service detection, OS fingerprinting |
| metasploit | 💻 Host | Exploitation framework (6.4) — gated |
| netexec (nxc) | 💻 Host | SMB/LDAP/WinRM enumeration and authentication |
| bloodhound-python | 💻 Host | Active Directory attack path analysis |
| certipy-ad | 💻 Host | AD Certificate Services exploitation |
| kerbrute | 💻 Host | Kerberos user enumeration and password spraying |
| impacket | 💻 Host | Windows protocol tools (secretsdump, GetUserSPNs) |
| responder | 💻 Host | LLMNR/NBT-NS/mDNS poisoning — gated |
| evil-winrm | 💻 Host | Windows Remote Management shell |
| enum4linux | 💻 Host | SMB enumeration |
| hydra | 💻 Host | Online brute-force (user-approved only) |
| john / hashcat | 💻 Host | Password hash cracking |

### OSINT & Passive Recon

| Tool | Runtime | Purpose |
|------|---------|---------|
| theHarvester | 💻 Host | Email, subdomain, and name enumeration |
| holehe | 💻 Host | Check if email is registered on services |
| sherlock | 💻 Host | Username search across 300+ social networks |
| crt.sh | 💻 Host | Certificate transparency log subdomain discovery |
| shodan | 💻 Host | Internet-connected device search engine |

### Infrastructure

| Service | Access | Purpose |
|---------|--------|---------|
| Neo4j 5 | 🐳 neo4j `: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}` |
| **Verify** 🆕 | **5.5️⃣ Quality** | **🔵 Benign only** | **Independently reproduces every DRAFT finding before reporting — benign observation, never exploits** | **`{VERIFIED, CORROBORATED, GATED, UNVERIFIED, REFUTED}`** |
| 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 |
| Verification gate | Every DRAFT finding independently reproduced before reporting — probe errors stay UNVERIFIED, destructive classes GATED, REFUTED findings in ruled-out appendix |
| Cross-validation | Critical findings (CVSS ≥ 9.0) require second-tool confirmation |
| Confidence levels | HIGH (multi-tool) / MEDIUM (single) / LOW (auto-only) / TENTATIVE (degraded) — verdict-driven via verification pass |

---

## 📊 Report Pipeline

```
Findings DB (SQLite) → Verify Pass (independent reproduction)
           ↓                        ↓
    Jinja2 Templates  ←  Verdicts + Confidence
           ↓
      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 |
| Framework Mapping 🆕 | Blue team | OWASP Top 10 (2021) + MITRE ATT&CK coverage of findings |
| Remediation Progress 🆕 | IT team | Open / fixed / regressed status across retest rounds |
| 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
├── ruff.toml                                ← pinned lint rule set (version-stable CI)
├── mcp_server/                              ← 🆕 MCP tool-server (scope/rate/audit enforced in code)
│   ├── server.py                            ← FastMCP tools (scan, osint, findings, retest, report)
│   ├── enforce.py                           ← the gates: scope · VPN · rate · audit
│   ├── catalog.py                           ← rate-limit lookups from tool-catalog.yaml
│   ├── requirements.txt / mcp.json.example  ← venv deps + example client config
│   └── README.md
├── docs/
│   ├── index.html                           ← GitHub Pages landing page
│   ├── pentest-architecture-complete.html   ← interactive system diagram
│   ├── pentest-architecture.html
│   ├── pentest-ops-architecture.html
│   ├── verification-pass-architecture.html  ← 🆕 verification pass system diagram
│   ├── pentest-reference.html               ← 🆕 complete production reference
│   ├── 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                   ← 4 services, 3 profiles (lab, sandbox, neo4j)
│   ├── Dockerfile.kali-web                   ← (deprecated — tools now native)
│   ├── Dockerfile.kali-net                   ← (deprecated — tools now native)
│   └── Dockerfile.osint-tools               ← (deprecated — tools now native)
├── 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, v5 + verdict/ATT&CK/OWASP/retest)
│   ├── build-report.py                      ← findings → Jinja2 → HTML + PDF (verdict + framework + retest aware)
│   ├── verify-findings.py                   ← 🆕 independent finding reproduction engine
│   ├── migrate-add-verification.py          ← 🆕 additive, idempotent DB migration (v3→v4)
│   ├── migrate-add-attack-owasp.py          ← 🆕 additive, idempotent DB migration (v4→v5)
│   ├── framework_map.py                     ← 🆕 ATT&CK + OWASP lookups + report coverage
│   ├── findings_library.py / add-finding.py ← 🆕 reusable finding templates (module + CLI)
│   ├── retest.py                            ← 🆕 open/fixed/regressed lifecycle + progress
│   ├── report_verification.py               ← 🆕 partition (body/ruled-out), verdict→confidence
│   ├── pentest-mcp.sh                        ← 🆕 launches the MCP tool-server (venv, stdio)
│   ├── 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)
│   └── findings-library.json                ← 🆕 15 pre-approved, pre-tagged finding templates
├── tools/
│   └── tool-catalog.yaml                    ← tools with version, fallback, rate limits
├── skills/
│   ├── pentest-context.md                   ← system map — loaded every session
│   ├── pentest-engage.md                    ← orchestrator — dispatches 7 subagents
│   ├── pentest-ops.md                       ← startup/shutdown/repair/troubleshooting
│   ├── pentest-verify.md                    ← 🆕 7th subagent — independent reproduction skill
│   ├── pentest-mcp.md                        ← 🆕 driving the toolchain over MCP
│   ├── pentest-findings/SKILL.md            ← finding encyclopedia — 14 interpretations + library
│   ├── 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/<name>/
├── ENGAGEMENT.yaml       ← client, dates, status, assessor
├── scope.json            ← scope definition (IPs, domains, signed)
├── findings.db           ← SQLite v5 database (6 tables, verdict + ATT&CK/OWASP + retest columns)
├── findings.json         ← machine-readable findings export
├── metadata.json         ← controls, observations, methodology
├── audit/
│   └── actions.jsonl     ← every tool run, scope-validated (incl. verification actions)
├── 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 | Burp Suite Pro | PwnDoc |
|---------|-------------------|----------------|--------|
| Agent runtime | Hermes Agent **+ any MCP client** | Extensions API | Manual |
| **MCP access** 🆕 | **Tool-server — scope/rate/audit enforced in code** | Extensions API | None |
| Subagents | 7 (customizable) + 1 findings KB | None | 0 |
| **Finding verification** 🆕 | **Independent reproduction pass (Phase 5.5) — benign only** | Manual retest | None |
| **Finding KB** | **14-entry encyclopedia** | None | None |
| **Findings library** 🆕 | **15 pre-approved, pre-tagged templates** | None | Shared library |
| **Framework mapping** 🆕 | **MITRE ATT&CK + OWASP Top 10 on findings + report** | Manual | Manual |
| **Retest tracking** 🆕 | **open/fixed/regressed lifecycle + progress report** | None | Retest field |
| Tool isolation | Native Kali host + Docker lab targets | Java VM | Not applicable |
| Report generation | Jinja2 + WeasyPrint → PDF | BApp extensions | Markdown → PDF |
| 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 v5 (6 tables, versioned, verdict + ATT&CK/OWASP + retest columns) | Project file | JSON store |
| 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.

---

## 🆕 Verification Pass (Phase 5.5) — Just Added

> **Every DRAFT finding is independently reproduced before it reaches the report.**

The verification pass sits between discovery (Phases 2-5) and reporting (Phase 6). It runs a **benign, independent method** against each finding — re-fetching headers with a plain stdlib client, observing TLS with a different tool, checking open ports with a socket probe. It **never fires an exploit**.

### How it works

```
  DRAFT findings → verify-findings.py → 5 possible verdicts:
                                          ├─ VERIFIED       — manual confirmation
                                          ├─ CORROBORATED   — independent signal agrees
                                          ├─ GATED          — destructive class, abstained
                                          ├─ UNVERIFIED     — couldn't confirm (probe error ≠ refute)
                                          └─ REFUTED        — evidence contradicts finding → ruled-out appendix
```

### Design rules (baked in)

| Rule | What it means |
|------|---------------|
| **Independent method** | Verification must differ from `tool_used` — no echo chamber |
| **Benign observation only** | Header re-fetch, TLS observe, socket banner. Never an exploit |
| **Abstain, don't guess** | SQLi, RCE, SSRF, auth-bypass → GATED with reason recorded |
| **Probe error ≠ verdict** | Timeout/DNS/reset → UNVERIFIED, never REFUTED |
| **Confidence is an output** | Verdict drives confidence tier — single source of truth |
| **REFUTED is surfaced** | Goes to the ruled-out appendix, never silently dropped |

### Commands

```bash
python3 scripts/verify-findings.py <engagement>            # write verdicts
python3 scripts/verify-findings.py <engagement> --dry-run   # preview only
python3 scripts/migrate-add-verification.py --all           # migrate existing DBs
```

### What the report shows

- **Verdict badge** on every finding card (`CORROBORATED`, `UNVERIFIED`, `GATED`, etc.)
- **Confidence driven by verdict** — CORROBORATED→MEDIUM, UNVERIFIED→LOW, GATED→TENTATIVE
- **Independent Verification block** on each finding — method used + observable evidence
- **Ruled-Out Candidates appendix** — REFUTED findings surfaced for transparency

[→ Full verification architecture diagram](https://jayelbotvibe-web.github.io/hermes-pentest-lab/verification-pass-architecture.html)

---

## 🎓 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).