knockpy combines passive reconnaissance and wordlist bruteforce into an async Python scanner that maps subdomains, HTTP/TLS posture and zone-transfer risk for authorized asset discovery.

knockpy is a Python 3 subdomain enumeration tool from Gianni Amato that has been substantially rearchitected for version 9, moving to an async/await model built on httpx for HTTP handling and concurrent DNS resolution. The premise is familiar — combine passive reconnaissance against third-party data sources with active wordlist bruteforce — but the execution is more modern than most entries in this category. At roughly 4,200 stars and licensed under GPL-3.0, it sits comfortably in the mainstream of reconnaissance tooling, and the README suggests an actively curated project rather than an abandoned script.

The feature set is broad without being incoherent. A single invocation with --recon --bruteforce chains both enumeration strategies, and every discovered host is validated for HTTP/HTTPS status, TLS certificate details, and resolved IP. Two checks stand out as genuinely useful beyond raw enumeration: the tool flags legacy TLS 1.0/TLS 1.1 support as a warning in CLI, verbose, and HTML report output, and during domain-mode scans it probes for AXFR zone transfer on the root domain. Neither is exotic, but having them folded into the enumeration pass means the operator gets an exposure summary, not just a hostname list, which shortens the gap between discovery and triage in an authorized assessment.

Wildcard DNS detection is a first-class concern rather than an afterthought. The --wildcard flag runs a standalone test that resolves and exits, while domain-mode scans apply wildcard helpers internally so that brute-force results aren't polluted by catch-all records answering every query. This matters operationally: naive brute tools against wildcarded zones produce enormous false-positive lists, and the README's mention of scan_flow.py handling wildcard helpers alongside exclude rules indicates the logic lives in the orchestration layer where it belongs.

The CLI surface is unusually rich. Beyond the core -d/--domain and -f file-input modes, you get --exclude filters on status, response length, and body content, --verbose for single-domain deep diagnostics covering DNS, TCP, TLS, redirect chains and request errors, and --json for machine-readable output that forces --silent. Runtime overrides exist for --dns, --useragent, --timeout, --threads and --wordlist, and the precedence model is documented clearly: CLI values override saved --setup values, which override built-in defaults of threads=250 and timeout=3. That kind of explicit precedence documentation is a small thing that saves real debugging time.

Performance tuning gets its own treatment, which tells you the maintainer expects large-scale use. The README proposes concrete profiles — --threads 50 --timeout 5 for accuracy on few domains, --threads 150 --timeout 4 balanced, --threads 250 --timeout 3 for 10k+ target lists — and describes a two-pass strategy where a fast aggressive pass is followed by a slower retry against uncertain or missing targets. The stated trade-offs are honest: more threads means more CPU, network and DNS load plus rate-limit risk, while aggressive timeouts risk false negatives on slow-but-valid hosts. Bruteforce runtime is also optimized through TLS-probe endpoint caching, so repeated TLS handshakes against the same endpoints don't recur needlessly.

The passive reconnaissance layer is where knockpy earns its modularity claim. At first run it writes ~/.knockpy/recon_services.json, an editable catalog where each service defines a name, an enabled toggle, a parser, a url_template supporting {domain}, {virustotal_key} and {shodan_key} placeholders, and an optional requires_api field. Supported parsers cover csv_first_column, rapiddns_html_td, json_list, virustotal_subdomains and shodan_subdomains. The KNOCK_RECON_SERVICES environment variable redirects to a custom file path, meaning you can extend or prune the source list without touching code. The --test flag, used with --recon, evaluates each source independently and classifies it as failed, empty, or returning data — a rare and welcome diagnostic for when a passive source silently breaks.

API integration with VirusTotal and Shodan is optional, with keys supplied via API_KEY_VIRUSTOTAL and API_KEY_SHODAN environment variables or a .env file, and the interactive --setup persists runtime defaults plus API keys into the local database. There is an operational privacy trade-off here worth flagging for authorized engagements: querying these services associates the target domain with your API key, which may be undesirable on sensitive assessments where third-party query logs constitute evidence leakage. The --dns and --useragent overrides give some control over the active side's footprint, but passive-source telemetry is inherent to the model.

Persistence is handled through SQLite with an interactive report mode. After a scan, knockpy --report list or --report latest opens a menu offering show, delete, export, search, and a confirmed database reset, with export to HTML rendering the same tables and panels the terminal shows via Rich. For teams running repeated enumeration against owned estates, the searchable catalog turns the tool from a one-shot scanner into a lightweight asset-history store — you can diff what changed between scans rather than re-deriving state from scattered text files.

The internal architecture, as laid out in the project-structure section, shows deliberate layering. cli.py and the cli_parts/ modules (status.py, setup.py, report.py, scan_flow.py) handle orchestration and presentation; the actual scanning engine lives in engine/runtime.py; storage is split between storage_parts/db.py, export.py and html_report.py; and public facades (core.py, storage.py, knockpy.py) preserve backward compatibility so from knockpy import KNOCKPY keeps working. The Python API is fully documented — instantiate KNOCKPY(domain, dns=..., recon=True, bruteforce=True, ...) and iterate over result dicts containing domain, ip, http and cert keys — which makes it straightforward to embed knockpy in a larger custom enumeration pipeline.

Installation follows the modern venv pattern: clone the repo, activate a virtual environment, and pip install ., with Python 3.9+ recommended. A PyPI package, knock-subdomains, is noted as available only after the stable release lands, and --check-update polls PyPI for newer versions. A default wordlist ships at knockpy/wordlist/wordlist.txt, replaceable via --wordlist, and --update-versions refreshes the local web-server versions catalog used to fingerprint targets — a small but thoughtful touch for keeping banner data current.

From a defensive perspective, knockpy's activity profile is well understood and detectable. Wordlist-driven subdomain queries generate the classic high-volume NXDOMAIN signature against authoritative nameservers, HTTP probes arrive with an overridable but default-identifiable user agent, and bruteforce bursts from a single source IP are trivially rate-limitable. The AXFR check will be logged as a failed zone-transfer request on any competently configured DNS server. Defenders running their own asset-discovery passes with knockpy against owned infrastructure get a direct answer to shadow-IT drift: the wildcard detection and TLS-legacy flagging surface exactly the misconfigurations — catch-all records, forgotten TLS 1.0 endpoints, permissive zone transfers — that external attackers enumerate first.

Overall, knockpy v9 reads as a mature, deliberately engineered enumeration tool. The async rewrite, the editable recon-source catalog, the SQLite reporting layer and the documented tuning guidance together make it a credible default choice for subdomain discovery in authorized engagements — particularly for operators who want a tool they can extend through configuration rather than forks, and who value structured, queryable output over raw terminal dumps.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.

Related coverage

• Claude-BugHunter for structured external attack-surface testing with agent skills