daecayde/bloodhoundr

# bloodhoundr 🕷️ An automated attack surface mapper and threat intelligence pipeline for penetration testers. Built because I got tired of running five tools manually and stitching the output together in a text file. (renamed from nightcrawler cause I found it corny overtime)     ## What it does Most recon tools do one thing. You run nmap, copy the output. You run subfinder, copy the output. You search CVEs manually, copy that too. Then you spend an hour writing a report from scratch. bloodhoundr chains all of that into one command: recon → port enum → CVE lookup → MITRE ATT&CK mapping → VAPT report One target in. Structured report out. The machine spirits are appeased. ## Features - **Passive + active recon** — subdomain brute-force, DNS record collection, ASN lookup, tech fingerprinting from HTTP headers - **Nmap wrapper** — port/service enumeration with version detection, outputs structured data not raw text - **NVD CVE pipeline** — queries NIST NVD API v2 automatically per discovered service banner, CVSS scored and sorted - **MITRE ATT&CK mapper** — converts CVEs and finding types to TTP IDs with tactic context, detection notes, and mitigations - **Active Directory module** — Kerberoasting, AS-REP Roasting, Pass-the-Hash chain suggestions based on discovered AD services - **Report generator** — PTES-structured output in Markdown, JSON, and PDF with exec summary, findings table, remediation timeline - **Plugin architecture** — drop a Python file in `/plugins` and it's auto-loaded. Write your own modules without touching core ## QuickStart ## Docker # Create a reports folder first mkdir reports # Run — reports will appear in that folder docker run -v $(pwd)/reports:/app/reports rhysonance/bloodhoundr scan --target example.com ##Setup git clone https://github.com/daecayde/bloodhoundr cd bloodhoundr pip install -r requirements.txt # Full pipeline bloodhoundr scan --target example.com # Just recon bloodhoundr recon --target example.com --passive # CVE lookup for specific banners bloodhoundr cve "nginx/1.18.0" "OpenSSH 7.4p1" "Apache Tomcat 9.0.50" # Map technique IDs to ATT&CK detail bloodhoundr mitre T1190 T1068 T1110 # Generate report from saved JSON bloodhoundr report --target example.com --input results.json --formats md,pdf ## Installation Tested on Kali Linux 2024.x and Arch Linux. Should work on any Debian-based distro. # Clone git clone https://github.com/daecayde/bloodhoundr cd bloodhoundr # Install deps pip install -r requirements.txt # Optional: install globally pip install -e . # Verify bloodhoundr version For PDF report generation: pip install weasyprint markdown ## Usage ### Full scan pipeline bloodhoundr scan --target corp.example.com --passive --ports top1000 --formats md,json,pdf Options: | Flag | Default | Description | |---|---|---| | `--target` | required | Domain or IP | | `--passive / --active` | passive | Recon mode | | `--ports` | top1000 | Port range: top100, top1000, all, or custom like `22,80,443` | | `--wordlist` | built-in | Custom subdomain wordlist path | | `--nvd-key` | none | NVD API key for higher rate limits | | `--formats` | md,json | Report formats: md, json, pdf | | `--output` | reports/ | Output directory | | `--assessor` | bloodhoundr | Your name for the report header | ### Recon only bloodhoundr recon --target example.com --wordlist /usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt ### CVE lookup from banners bloodhoundr cve "Apache Tomcat 9.0.50" "vsftpd 3.0.3" --nvd-key YOUR_KEY --output-json cves.json Get a free NVD API key at [https://nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key) — bumps your rate limit from 5 to 50 req/30s which makes a difference on large scopes. ## Example output $ bloodhoundr scan --target corp.example.com [*] Starting passive reconnaissance... [+] Resolved corp.example.com → 203.0.113.42 [+] Subdomains found: 47 ├── api.corp.example.com ├── dev.corp.example.com ├── vpn.corp.example.com ← interesting └── +44 more [+] Technologies: nginx/1.18.0, Apache Tomcat/9.0.50 [*] Querying NVD for: Apache Tomcat... [CRIT] CVE-2021-41773 CVSS:9.8 Apache HTTPd path traversal/RCE [HIGH] CVE-2020-1938 CVSS:9.8 Tomcat AJP Ghostcat LFI [HIGH] CVE-2018-15473 CVSS:5.3 OpenSSH user enumeration [*] MITRE ATT&CK mapping... Initial Access → T1190 Exploit Public-Facing Application Discovery → T1083 File and Directory Discovery Credential Access → T1110 Brute Force [+] Report saved → reports/corp_example_20250524_143022.md [+] Report saved → reports/corp_example_20250524_143022.json ## Project structure bloodhoundr/ ├── bloodhoundr/ │ ├── cli.py # Typer CLI entry point │ ├── modules/ │ │ ├── recon.py # Subdomain enum, DNS, ASN, fingerprinting │ │ ├── enum.py # Port/service enumeration (Nmap wrapper) │ │ ├── cve_lookup.py # NVD API v2 CVE pipeline │ │ ├── mitre_mapper.py # ATT&CK technique mapper │ │ ├── ad_module.py # Active Directory attack chain mapper │ │ └── report_gen.py # VAPT report generator (MD/JSON/PDF) │ ├── plugins/ # Drop custom modules here │ └── utils/ # Shared helpers ├── tests/ ├── wordlists/ ├── requirements.txt └── setup.py ## Active Directory module It maps out potential attack paths: - Kerberoastable SPNs → T1558.003 - AS-REP Roastable accounts → T1558.004 - Pass-the-Hash vectors → T1550.002 - BloodHound-style path suggestions ## Plugin system # plugins/my_custom_check.py def run(target: str, results: dict) -> dict: """My custom recon check.""" # your logic here return {"custom_finding": "..."} ## Ethical use This tool is for authorized penetration testing and security research only. Running it against systems you don't have explicit written permission to test is illegal under the Computer Fraud and Abuse Act, Computer Misuse Act, and equivalents in most jurisdictions. ## Roadmap - [ ] Nuclei template integration for web vuln scanning - [ ] Shodan/Censys API support for passive IP intelligence - [ ] HTML report theme with dark mode - [ ] Docker image - [ ] Slack/Discord webhook notifications - [ ] CI/CD pipeline integration mode (exit codes based on severity threshold) - [ ] CVSS v4.0 support ## Author **Daecayde** — [GitHub](https://github.com/daecayde) · [TryHackMe](https://tryhackme.com/p/daecayde) Built this during my time doing VAPT work and CTFs. Got fed up manually correlating nmap output with CVE databases at 2am. There had to be a better way. ## License MIT — see [LICENSE](LICENSE)