credkellar/hack-dhe-net repository overview

⁠🛡️ Hack-Dhe-Net — Authorized-Scope Penetration Testing Toolkit & Study Lab

🔍 A complete penetration-testing methodology as running code — the core 4-step workflow, the 9 extended practices, and the AI integration from the study document — where every assessment runs only against registered, authorized scope, verification never disrupts a service, and a real CVSS 3.1 engine ranks findings by business risk.

👨‍💻 By Darion Kellar · 📜 MIT License · 🐍 Python stdlib only, zero dependencies · 🏷️ v1.0.0

⁠🧰 Tech Stack

⁠📖 What is this about?

Hack-Dhe-Net began as a Gemini study document: a "Master Documentation Overview" of how a penetration test is actually run — Part 1, a core 4-step methodology (find open ports, understand services, discover vulnerabilities, determine exploitability safely); Part 2, the extended practices that make an assessment complete (OS fingerprinting, banner grabbing, directory brute-forcing, credential testing, topology and trust mapping, cryptographic posture, CVSS prioritization, documentation and rules of engagement); Part 3, advanced AI integration (Gemini Flow workflow automation, Gemini Argon 4 extended thinking); and a three-tab study checklist, with a repository layout of docs/, scripts/ and outputs/. This project implements all of it as one running system — and adds the guardrail the document itself demands: assessments operate strictly within authorized scopes, enforced by a scope registry that refuses unregistered targets in code.

⁠⚙️ What this does

1. 📋 Registers scope — targets are added to the authorized registry first; loopback is built in.
2. 🔍 Discovers ports — threaded TCP connect scan (plus best-effort UDP probes).
3. 🏷️ Detects services — banner grabbing identifies products and exact versions.
4. 🖥️ Estimates the OS — TTL + banner hints, always labelled an estimate.
5. 🗂️ Discovers web paths — a small wordlist finds admin panels, backups, API endpoints.
6. 🔐 Evaluates TLS posture — handshake, certificate, cipher, plain flags.
7. 🐛 Cross-references CVEs — offline reference set matched to banner evidence.
8. 🔑 Probes credential risk safely — one anonymous FTP login; portal exposure notes; password guessing is not built in.
9. 📊 Scores and prioritizes — real CVSS 3.1 math × asset criticality × exposure.
10. 🗺️ Maps trust — topology/trust map with warnings from observed evidence.
11. 📝 Reports with a command log — the RoE evidence trail, every time.
12. 🧪 Demonstrates itself — a built-in leaky lab fixture makes the whole pipeline run offline (python main.py demo).

⁠🔬 How this works

The pipeline (hackdhenet/pipeline.py) runs the methodology in order. The scope gate resolves the target against the registry and stops the run if it is not authorized. The scanner connects to candidate ports and grabs banners; the fingerprint module estimates the OS from reply TTL and banner hints. Web services get directory discovery; TLS services get a posture evaluation. Banners are cross-referenced against the offline CVE set, and FTP services get a single anonymous-login probe. Every candidate finding carries a CVSS vector, scored by the CVSS engine (the official FIRST formula, verified against canonical vectors: 9.8, 7.5, 10.0) and multiplied by business context into a priority. Findings, the trust map and the command log render into the report. The council — Argon 4 deciding, Flow ordering, Muse advising with no authority — holds 12 action classes (exploit execution, brute force, out-of-scope scanning, and friends) before they can ever run.

⁠🌟 Why this is cool

The study document most people would leave as notes is here as a working pipeline: scan → detect → cross-reference → verify safely → score → report, end to end, against a lab target that really answers.

⁠🔟 10 reasons why this is cool

1. 🎯 The whole methodology, not a slice — 4 core steps + 8 extended practices + AI seats + the checklist.
2. 🛡️ Scope enforced in code — authorization is a runtime gate, not a README promise.
3. 📊 A real CVSS calculator — official formula, canonical vectors reproduced exactly.
4. 💼 Business-context ranking — a 9.8 on a lab box and a 9.8 on a critical internet asset sort differently, as they should.
5. 🧪 Self-demonstrating — the leaky fixture (Apache 2.4.49, anonymous FTP, OpenSSH 7.4) makes the demo find 11 real findings offline.
6. 🔑 Credential testing with a spine — anonymous-login probe yes; built-in password brute force, never.
7. 🗺️ Trust mapping from evidence — warnings come from what the scan observed, not vibes.
8. 📝 Command log as RoE evidence — every run documents itself.
9. 🧠 A council with a HOLD list — Argon 4 can refuse 12 action classes; the advisor cannot talk it out of a refusal.
10. 🪶 Zero dependencies — the entire toolkit is the Python standard library.

⁠🧩 What problems this solves

1. 📚 Study notes that never become skill.
2. 🎲 Ad-hoc scans with no methodology.
3. 🚫 Testing that drifts outside authorized scope.
4. 💥 "Verification" that disrupts the service it tests.
5. 🔢 CVSS scores quoted from memory or vibes.
6. 📉 Findings ranked by score alone, ignoring business context.
7. 🕵️ Banners leaking versions with nobody noticing.
8. 🔓 Anonymous access and plaintext login portals left unreported.
9. 🗒️ Assessments with no command log to audit afterwards.
10. 🤖 AI assistance with no guardrails on what it may do.

⁠✅ 10 solutions

1. 📚 The document is implemented as modules — read the code, run the steps, tick the checklist.
2. 🎲 One pipeline runs the same 10-step flow every time.
3. 🚫 The registry gate refuses unregistered targets before any packet.
4. 💥 Verification = version evidence + one safe probe + configuration facts. Nothing executes, nothing floods.
5. 🔢 The CVSS engine computes from the vector with the official formula and roundup rule.
6. 📉 Priority = CVSS × criticality × exposure, shown next to the raw score.
7. 🕵️ Every versioned banner becomes a disclosure finding automatically.
8. 🔓 Anonymous FTP and plaintext portals are first-class findings in the demo and in real runs.
9. 🗒️ The command log is generated by the pipeline itself and printed in every report.
10. 🤖 12 HOLD gates, a decider, and an advisor whose authority is explicitly none.

⁠🚀 How to install this — step by step

1. 📥 Clone the repo: git clone https://github.com/credkellar/Hack-Dhe-Net.git
2. 📂 Enter it: cd Hack-Dhe-Net
3. 🐍 Check Python: python3 --version (3.10+; developed on 3.12).
4. 🧪 (Optional, for tests) Install pytest: pip install pytest
5. ✅ Run the self-checks: python main.py checks → expect CHECKS: 24/24 passed.
6. 🧪 Run the demo assessment against the lab fixture: python main.py demo
7. 📋 See the study checklist: python main.py checklist
8. 📋 Register your own lab host: python main.py register 192.168.1.50 my lab box
9. 🔍 Assess it: python main.py assess 192.168.1.50
10. 🐳 Or run it in Docker: docker build -t hack-dhe-net . && docker run --rm hack-dhe-net

⁠📋 Requirements

• 🐍 Python 3.10+ (standard library only — nothing to pip-install for the tool itself)
• 🧪 pytest (only for the test suite)
• 🔐 Written authorization for any target you register beyond your own machines
• 🐳 Docker (optional, for the container run)
• 🚫 No network access needed for the demo: the fixture is local

⁠🧒 Explain in 5th grade English

Imagine you hire a guard to check your house. First, the guard writes down which houses he is allowed to check — he never checks a stranger's house. Then he walks around your house and writes down every door and window (the ports). He reads the labels on the doors to learn who made them (the banners). If a label names an old lock that burglars know how to open, he writes that down too (the CVE list). He gently tries the front gate once to see if it is unlocked for anybody (the anonymous test) — he never tries to break anything. He gives every problem a danger score, but he also thinks about what is inside: a broken lock on the candy jar matters less than one on the safe. At the end he hands you a neat report with everything he did written down, step by step. That is this project.

⁠🗂️ Project structure

Hack-Dhe-Net/
├── main.py                  # 🎛️ CLI entry point
├── conftest.py              # 🧪 root path fix for bare pytest
├── pyproject.toml           # 📦 package metadata
├── Dockerfile               # 🐳 container build
├── hackdhenet/
│   ├── scope.py             # 📋 RoE + authorized scope registry
│   ├── fixture.py           # 🧪 leaky lab target (HTTP/FTP/SSH)
│   ├── scanner.py           # 🔍 ports + banner/service detection
│   ├── fingerprint.py       # 🖥️ OS estimate (TTL + hints)
│   ├── webdir.py            # 🗂️ directory discovery
│   ├── tlscheck.py          # 🔐 TLS posture evaluation
│   ├── vulndb.py            # 🐛 offline CVE cross-reference
│   ├── credcheck.py         # 🔑 credential-risk seat
│   ├── topology.py          # 🗺️ topology + trust mapping
│   ├── cvss.py              # 📊 CVSS 3.1 engine + prioritization
│   ├── checklist.py         # ✅ study checklist data
│   ├── pipeline.py          # 🔬 the assessment pipeline + report
│   └── brains/              # 🧠 argon4 · flowseat · muse · council
├── docs/                    # 📚 01 core workflow · 02 extra practices · 03 AI orchestration
├── scripts/                 # 🛠️ port-scanner.py · recon-pipeline.sh
├── outputs/                 # 📝 where reports land
└── tests/                   # 🧪 pytest suite

⁠📊 Flowchart for every script

⁠📄 main.py

flowchart TD
    A["python main.py"] --> B{"Command?"}
    B -->|demo| C["Fixture + full pipeline"]
    B -->|assess| D["Registered-host assessment"]
    B -->|scan / tls / cvss| E["Single-step tools"]
    B -->|checklist / scope| F["Study + RoE views"]
    B -->|checks| G["24 self-checks"]

⁠📄 hackdhenet/scope.py

flowchart TD
    A["Target named"] --> B{"In the registry?"}
    B -->|yes| C["Resolved IP released"]
    B -->|no| D["ScopeError - RoE HOLD"]
    C --> E["Run is logged"]

⁠📄 hackdhenet/fixture.py

flowchart TD
    A["start_fixture"] --> B["HTTP: Apache/2.4.49 banner + leaky paths"]
    A --> C["FTP: ProFTPD 1.3.5 + anonymous login"]
    A --> D["SSH banner: OpenSSH_7.4"]
    B --> E["127.0.0.1 ephemeral ports"]
    C --> E
    D --> E

⁠📄 hackdhenet/scanner.py

flowchart LR
    A["Candidate ports"] --> B["Threaded connect scan"]
    B --> C["Open ports"]
    C --> D["Passive banner read"]
    D -->|silent| E["HTTP HEAD probe"]
    D --> F["Service + product"]
    E --> F

⁠📄 hackdhenet/fingerprint.py

flowchart TD
    A["Host + services"] --> B["Ping TTL"]
    A --> C["Banner hints"]
    B --> D{"TTL family"}
    D -->|64| E["Linux / Unix-like"]
    D -->|128| F["Windows"]
    C --> G["Estimate + confidence label"]
    E --> G
    F --> G

⁠📄 hackdhenet/webdir.py

flowchart LR
    A["Wordlist: 10 paths"] --> B["GET each path"]
    B --> C{"Status?"}
    C -->|200| D["Accessible"]
    C -->|401| E["Auth required"]
    C -->|403| F["Exists, forbidden"]
    C -->|404| G["Skipped"]

⁠📄 hackdhenet/tlscheck.py

flowchart TD
    A["Host + port"] --> B["TLS handshake"]
    B --> C["Protocol + cipher"]
    B --> D["Certificate fields"]
    D --> E{"Flags?"}
    E -->|expired / legacy / self-signed| F["Posture flags"]
    E -->|clean| G["No flags raised"]

⁠📄 hackdhenet/vulndb.py

flowchart LR
    A["Service banners"] --> B["Offline CVE reference set"]
    B --> C{"Match?"}
    C -->|yes| D["Candidate finding + vector"]
    C -->|no| E["Version-disclosure check"]
    E --> F["Info finding"]

⁠📄 hackdhenet/credcheck.py

flowchart TD
    A["FTP service"] --> B["USER anonymous / PASS / QUIT"]
    B --> C{"Accepted?"}
    C -->|230| D["Anonymous-login finding"]
    A2["Web portals"] --> E["Plaintext HTTP?"]
    E -->|yes| F["Portal exposure finding"]
    G["Password guessing"] --> H["HOLD - external tools only"]

⁠📄 hackdhenet/topology.py

flowchart TD
    A["Scope hosts"] --> B["Map builder"]
    C["Assessment runs"] --> B
    B --> D["Nodes + edges"]
    B --> E["Trust warnings"]
    D --> F["Mermaid trust map"]

⁠📄 hackdhenet/cvss.py

flowchart LR
    A["CVSS vector"] --> B["Parse metrics"]
    B --> C["Official 3.1 formula + roundup"]
    C --> D["Base score + severity"]
    D --> E["x criticality x exposure"]
    E --> F["Priority ranking"]

⁠📄 hackdhenet/checklist.py

flowchart TD
    A["3 groups / 14 items"] --> B["Progress state"]
    B --> C["Core Workflow"]
    B --> D["Extra Practices"]
    B --> E["Google AI Tools"]
    C --> F["Percent complete"]
    D --> F
    E --> F

⁠📄 hackdhenet/pipeline.py

flowchart TD
    A["Scope gate"] --> B["Ports"] --> C["Services"] --> D["OS estimate"]
    D --> E["Directories + TLS"] --> F["CVE cross-reference"] --> G["Credential-risk probes"]
    G --> H["CVSS + business priority"] --> I["Report + command log + trust map"]

⁠📄 hackdhenet/brains/argon4.py

flowchart TD
    A["Proposed action"] --> B{"HOLD action?"}
    B -->|yes| C["HOLD - refused"]
    B -->|no| D["PROCEED"]
    A --> E["Thinking tier: 2048 / 8192 / 32768"]

⁠📄 hackdhenet/brains/flowseat.py

flowchart LR
    A["Assessment Flow"] --> B["10 named steps"]
    B --> C["Scope gate first"]
    C --> D["Report last"]

⁠📄 hackdhenet/brains/council.py

flowchart TD
    A["Action"] --> B["Argon 4 decides"]
    B --> C["Flow orders the steps"]
    B --> D["Muse advises - authority none"]
    C --> E["Strictest verdict wins"]
    D --> E

⁠📄 scripts/port-scanner.py

flowchart LR
    A["Host + ports"] --> B["Scope check"]
    B --> C["scanner.detect_services"]
    C --> D["Printed services"]

⁠🚦 HOLD gates (12)

⁠🧪 Demo findings (observed, against the built-in fixture)

11 findings, top two CRITICAL 9.8: Apache httpd 2.4.49 path traversal / possible RCE [CVE-2021-41773] and ProFTPD 1.3.5 mod_copy [CVE-2015-3306]; then anonymous FTP accepted, OpenSSH 7.4 user enumeration [CVE-2018-15473], /backup.zip and /.git/HEAD exposed, two plaintext login portals, and three version disclosures. Verification: pytest 6 passed, CHECKS 24/24, hold-demo exit 2.

⁠⚖️ Honest status

• ✅ Real: scope gate, connect scanning, banner detection, directory discovery, TLS handshake evaluation, the CVSS engine, the fixture end-to-end run, the council HOLD logic.
• 🏷️ The OS fingerprint is an estimate from TTL + banner hints — the lab equivalent of the nmap -O study item, not stack interrogation.
• 📚 The CVE set is a small offline reference, not a live feed; matches are candidates grounded in banner evidence.
• 🔌 Argon 4 / Flow / Muse are seats with names-only keys (GEMINI_API_KEY, MODEL_API_KEY); offline they run the deterministic local logic in brains/. Live model calls are the operator's step.
• 🐳 The Dockerfile is verified statically; this build machine has no Docker daemon.
• 🚫 By design: no exploit execution, no password brute force, no scanning outside the registry — ever.

⁠📜 License

MIT © 2026 Darion Kellar