hb-recon README

The project's README from github.com/mrhlaingbwardev/hb-recon. As one markdown file: README.md.

HB-Recon

Python License Stars

Automated reconnaissance workflow with AI-ready report generation.

Perfect for bug bounty hunters, pentesters, and security researchers.

⚠️ Important Notice

HB-Recon is a workflow automation tool — it orchestrates external security tools and generates structured reports.

What it does:

What it does NOT do:

Features

✅ Subdomain Enumeration — subfinder integration
✅ Live Host Detection — httpx for alive checks
✅ Technology Stack Scan — WhatWeb detection
✅ Endpoint Crawling — Katana deep crawl (depth 3)
✅ Vulnerability Patterns — gf pattern matching (XSS, SQLi, IDOR)
✅ AI Report Generation — Structured JSON with risk scoring

Prerequisites

System Requirements

Required External Tools

You MUST install these tools before using hb-recon:

Tool Purpose Installation
subfinder Subdomain enumeration go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
httpx HTTP probe go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
katana Web crawler go install -v github.com/projectdiscovery/katana/cmd/katana@latest
gf Pattern matcher go install github.com/tomnomnom/gf@latest
whatweb Tech detection sudo apt install whatweb (Debian/Ubuntu)

Quick Install (All Tools)

# Install Go tools
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install github.com/tomnomnom/gf@latest

# Install WhatWeb
sudo apt install whatweb

# Verify installations
subfinder -version
httpx -version
katana -version
gf -h
whatweb --version

Installation

docker build -t hb-recon .
docker run -it hb-recon -h

Option 2: From Source (Linux/WSL)

git clone https://github.com/mrhlaingbwardev/hb-recon.git
cd hb-recon
pip install -e .

Usage

Interactive Mode

python -m hb_recon

Example:

=======================================================
  Auto Recon -> AI Ready
=======================================================

[>] Domain: example.com

[+] Subfinder + Httpx
[v] Done (5.2s)

[*] WhatWeb + Katana (parallel)...
[+] Katana (crawl)
[v] Done (12.4s)

[+] gf (XSS/SQLi/IDOR patterns)
[v] Done (1.8s)

[√] Total: 19.4s

Output Structure

recon_example.com/
├── subdomains.txt      # All discovered subdomains
├── alive.txt           # Live hosts (200, 301, 403)
├── urls.txt            # Crawled endpoints (depth 3)
├── xss.txt             # XSS-prone endpoints
├── sqli.txt            # SQLi-prone endpoints
├── idor.txt            # IDOR-prone endpoints
├── tech_stack.txt      # Technology detection
└── ai_report.json      # AI-ready structured report

AI Report Format

The tool generates ai_report.json with structured data perfect for AI analysis:

{
  "target": "example.com",
  "timestamp": "2026-06-20T13:45:00",
  "summary": {
    "subdomains": 15,
    "alive_hosts": 8,
    "endpoints": 324,
    "technologies": 12,
    "high_risk": 3,
    "medium_risk": 7,
    "low_risk": 15
  },
  "endpoints": [
    {
      "url": "https://admin.example.com/api/users?id=123",
      "category": "idor",
      "risk": "high",
      "params": ["id"]
    }
  ],
  "tech_stack": {
    "server": "nginx/1.18.0",
    "frameworks": ["React", "Node.js"],
    "cms": "WordPress 6.2"
  }
}

Use with AI:

# After scan
cat recon_example.com/ai_report.json | pbcopy
# Paste into ChatGPT/Claude: "Analyze this recon data for vulnerabilities"

Workflow Logic

Input: Domain
    ↓
1. Subdomain Enumeration (subfinder)
    → hackertarget, waybackarchive sources
    ↓
2. Live Detection (httpx)
    → Filter 200, 301, 403 status codes
    ↓
3. Parallel Execution:
    ├─→ Tech Stack (WhatWeb)
    └─→ Endpoint Crawl (Katana depth=3)
    ↓
4. Pattern Detection (gf)
    ├─→ XSS patterns
    ├─→ SQLi patterns
    └─→ IDOR patterns
    ↓
5. AI Report Generation
    → Risk scoring
    → Category grouping
    → JSON export

Example Workflow

# 1. Install hb-recon (from source)
git clone https://github.com/mrhlaingbwardev/hb-recon.git
cd hb-recon
pip install -e .

# 2. Run scan
python -m hb_recon
# Enter: bugcrowd.com

# 3. Wait 30-60 seconds

# 4. Check results
cd recon_bugcrowd.com
cat ai_report.json

# 5. Analyze with AI
# Copy ai_report.json content to ChatGPT/Claude

Security Notice

⚠️ Only use on authorized targets.

This tool is for:

Unauthorized scanning is illegal and violates:

You are responsible for your actions.

Troubleshooting

"Command not found" errors

Problem: Tool binaries not in PATH

Solution:

# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/go/bin:$PATH"

# Reload shell
source ~/.bashrc

"Platform Error" on Windows

Problem: hb-recon requires Linux/WSL

Solution:

# Use WSL (Windows Subsystem for Linux)
wsl -d kali-linux
pip install hb-recon
python -m hb_recon

Network timeouts

Problem: Slow/unstable connection

Solution:

# Increase timeout in cli.py
# Default: timeout=300 (5 minutes)

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

License

MIT License - See LICENSE

Author

Hlaing Bwar

Made with ❤️ for the bug bounty community

Disclaimer: This tool is for educational and authorized testing only. Misuse may result in legal consequences.

hb-recon (mrhlaingbwardev/hb-recon)

Searching Database…

339 ·GitHub
Hb-recon
What is this?A workflow tool for security reconnaissance: it chains external recon tools and turns their output into structured JSON reports for analysis.
Does it run scans itself or wrap other tools?It wraps other tools. It orchestrates external security tools, has no built-in scanning engine, and does not install those tools for you.
How do I get it running?Install the external tools first (subfinder, httpx, katana, gf, whatweb), then set up hb-recon from source on Linux or WSL, or use the Docker option.
What do I need before I start?Python 3.8+ and Go 1.19+, since most of the chained tools are installed with 'go install'. whatweb comes from apt on Debian and Ubuntu.
What is the catch?You must install several external tools by hand, a tool binary missing from PATH breaks runs, and the author asks you to scan only targets you are authorized to test.
Is it meant for bug bounty hunters?Yes. The README targets bug bounty hunters, pentesters and security researchers, with the caveat that bug bounty programs must have a defined scope.
Does it work on Windows?Not directly. It requires Linux or WSL, and the README recommends the Docker option for Windows users.
Which tools does it chain together?Subfinder finds subdomains, httpx checks which hosts are alive, WhatWeb detects the tech stack, Katana crawls endpoints to depth 3, and gf matches patterns for XSS, SQLi and IDOR.
What is the 'Command not found' error about?It appears when tool binaries are not in PATH. The README lists it as the first troubleshooting case, so check that the installed tools are reachable from your shell.
What are similar projects?bbot, strix, opentrap, Cybermes, awesome-osint-arsenal, d0rk3r, OneForAll, theHarvester
Which topics is it in?subdomain-enumeration, pentesting-tools, bug-bounty, information-gathering, web-security, reconnaissance, crawler, vulnerability-scanner, ai-tools, penetration-testing, workflow-automation, json
Creator
mrhlaingbwardev
Size
<0.1 MB
Stars
339
Updated
CommitAug 18
Age
3mo
Commits · 90 Days