HB-Recon: a Python wrapper that chains subfinder, httpx, katana, gf and WhatWeb

What HB-Recon actually is: an orchestrator, not a scanner

The README opens with a notice that most tool pages bury: HB-Recon is a workflow automation tool that orchestrates external security tools and generates structured reports. The list of things it does not do is equally explicit. No built-in scanning capabilities. No auto-install of required tools. It will not work without dependencies. That framing matters, because the package name and the phrase automated reconnaissance framework invite the opposite assumption. If you install hb-recon expecting an all-in-one scanner, you get a Python package that shells out to binaries you have to supply yourself.

The audience is narrow and stated: bug bounty hunters, pentesters, and security researchers working from Linux or WSL. The value proposition is not detection depth, it is bookkeeping. Five separate tools each have their own output conventions, and the framework normalises them into one directory tree per target plus a single JSON file. For someone running the same five commands by hand across twenty scope entries, that is the actual saving.

The five-stage pipeline and the files it leaves behind

The workflow logic in the README is a straight line with one fork. A domain goes in. Subfinder enumerates subdomains, with hackertarget and waybackarchive named as sources. Httpx filters the results down to live hosts, keeping 200, 301 and 403 status codes. From there the run forks: WhatWeb fingerprints the technology stack while Katana crawls endpoints at depth 3, and the README describes these two as running in parallel. Finally gf applies its pattern sets for XSS, SQLi and IDOR, and the report generator assigns risk scores and groups endpoints by category.

Everything lands in a directory named recon_<domain>/. The README lists subdomains.txt, alive.txt, urls.txt, xss.txt, sqli.txt, idor.txt, tech_stack.txt and ai_report.json. That layout is the real interface. The individual text files are plain lists you can pipe into other tools, and the JSON is the summary layer.

The parallel step is worth a second look. The README's example console output shows WhatWeb and Katana starting together and finishing after about 12.4 seconds, but the same example shows subfinder plus httpx taking 5.2 seconds and gf taking 1.8 seconds. Those are illustrative timings in the README, not measurements I can confirm, and they will vary with target size and network conditions. What is confirmable is the shape: two of the five stages overlap, the other three are sequential, so total wall time is roughly the sum of the slowest fork branch plus the rest.

Installing HB-Recon and running a first scan

The prerequisites are strict. Linux or WSL, Python 3.8 or newer, and Go 1.19 or newer if you intend to build the Go-based tools. The README provides a single block for the four Go tools plus WhatWeb, and then a verification step for each. Run it before anything else, because a missing binary surfaces as a command-not-found during a scan rather than at startup.

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
sudo apt install whatweb
subfinder -version
httpx -version
katana -version
gf -h
whatweb --version

If the Go binaries report command not found, the README's troubleshooting section points at PATH rather than at the install. Go puts binaries in $HOME/go/bin, which is often not on the default PATH.

export PATH="$HOME/go/bin:$PATH"
source ~/.bashrc

With the tools in place, install the package itself. The README gives two routes. Docker is recommended for Windows, and the repository ships a Dockerfile that builds the Go tools in a golang:1.21-alpine stage and copies the four binaries into a python:3.10-slim image alongside whatweb, with hb-recon as the entrypoint.

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

On Linux or WSL, the source route is a clone and an editable pip install. Note that pyproject.toml declares an empty dependencies list, so pip pulls nothing on its own; the external tools remain your responsibility either way.

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

The last command starts interactive mode. It prints a banner, prompts for a domain, and reports each stage as it completes. When it finishes, change into the recon_<domain> directory and read ai_report.json. The README's own example workflow ends by copying that file into a chat model with a prompt asking it to analyse the recon data for vulnerabilities.

What ai_report.json contains, and why the risk field is weaker than it looks

The report is a JSON object with a target, a timestamp, a summary block and two detail blocks. The summary counts subdomains, alive hosts, endpoints, technologies, and endpoints bucketed into high, medium and low risk. The endpoints array carries objects with a url, a category, a risk level and a params list. The tech_stack block records server, frameworks and cms. The README's example shows a WordPress 6.2 site behind nginx/1.18.0 with React and Node.js listed as frameworks, and a single endpoint categorised as idor with high risk and an id parameter.

That risk field deserves scepticism. The README describes the pipeline as pattern detection via gf, and the categories map one to one onto gf's XSS, SQLi and IDOR pattern sets. So a high-risk label means a URL matched a regular expression that historically correlates with a vulnerable parameter. It does not mean anyone probed the endpoint. A parameter named id on a URL is not an IDOR; it is a candidate. The README's own AI prompt phrasing, asking a model to analyse the data for vulnerabilities, is honest about this, but the field name risk invites over-reading when the JSON is skimmed rather than read.

The same caution applies to the summary counts. Fifteen subdomains and eight alive hosts describe what subfinder and httpx returned during that run, nothing more. No historical baseline is stored, so a second run gives you a fresh directory with no diff against the first.

Where HB-Recon stops being the right tool

The hard boundary is the dependency set. Five external tools, four of them installed through Go and one through apt, with no auto-install path. On a locked-down workstation without Go, or on a distribution where whatweb is not packaged, the framework never gets past stage one. The README's Windows guidance is to use WSL, and the troubleshooting section lists a platform error on Windows as a known problem rather than a configuration mistake. Native Windows is not a supported target.

The second boundary is depth. Because the framework only orchestrates, the quality of every result is the quality of the underlying tool's defaults. Katana runs at depth 3, which the README states directly; if your target needs deeper crawling, that is a change you make to the tool's invocation, not something the framework exposes as a documented option. The README's network timeout guidance is telling here: it says to increase the timeout in cli.py, with a default of 300 seconds, and points at a source file rather than a configuration key or a command-line flag. Adjusting behaviour means editing the package.

The third boundary is that this is a one-shot workflow. There is no scheduling, no state between runs, and no documented rollback or resume if a stage fails midway. A partial run leaves a partial directory, and nothing in the README says how the framework distinguishes a completed scan from an interrupted one. If you need continuous monitoring of a scope, this is not the shape of tool you want.

How it compares with running the ProjectDiscovery chain directly

The obvious alternative is the tools themselves. ProjectDiscovery's own ecosystem, subfinder, httpx and katana, is designed to be piped: subfinder emits subdomains, httpx consumes them on stdin, katana consumes live hosts. A shell pipeline does the same enumeration without a Python layer in between, and it gives you direct access to every flag each tool offers rather than the subset the framework invokes. You also avoid the editable pip install and the PATH troubleshooting entirely.

The difference in approach is real, not cosmetic. A pipeline is transparent and composable; you see exactly what ran, and you can swap a stage without touching anyone's code. HB-Recon trades that transparency for a fixed output contract: eight files in a predictable directory plus a JSON summary with risk buckets. If your downstream step is a chat model prompt, the JSON is the point, and assembling an equivalent summary by hand from three separate tool outputs is the work the framework removes. If your downstream step is another command-line tool, the framework is an unnecessary layer and the pipeline wins.

What the framework does not offer is anything the underlying tools lack. There is no detection logic of its own, no custom wordlists, no differential analysis. The one genuinely framework-specific artefact is ai_report.json.

Licence, maintenance and the cost of upgrading

HB-Recon is MIT licensed, and pyproject.toml declares the same, so you can read, modify and redistribute it with the usual attribution requirement. That permissiveness matters more than usual here, because the timeout guidance already asks you to edit cli.py. MIT means those local changes are unambiguously yours to make. The bundled tools are separate projects with their own licences, and none of them are vendored into this repository; the Dockerfile fetches them at build time with @latest tags, which is worth knowing if you need reproducible builds.

The last push to the default branch was on 2026-08-18, and the repository is not archived. There are no releases retrieved, so versioning runs through pyproject.toml, which currently reads 1.0.4. The upgrade cost is mostly external. Because the Dockerfile installs subfinder, httpx, katana and gf at @latest, a rebuild can pull newer tool versions than the ones a previous image used, and the README does not document version pinning. If you build from source, the tools update on their own schedule through go install. Either way, a behaviour change in an upstream tool shows up as a change in your recon output, with no version record inside ai_report.json to explain it. The JSON carries a timestamp and a target but no tool versions.

Editorial conclusion

Adopt HB-Recon if you already run subfinder, httpx, katana, gf and WhatWeb on Linux or WSL and want their output collected into one directory plus a JSON summary. Do not adopt it if you expected a scanner: the README states it has no built-in scanning capability and will not install its own dependencies. Before trusting a run, verify that all five binaries resolve on PATH (subfinder -version, httpx -version, katana -version, gf -h, whatweb --version), confirm the target is inside an authorized bug bounty scope, and read ai_report.json yourself before pasting it anywhere, because the risk labels come from gf pattern matches rather than from confirmed vulnerabilities.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mrhlaingbwardev/hb-recon on GitHub
4. README