[opensourcedex]

knockpy is a free, open source threat detection & response project written in Python and released under GPL-3.0. It has 4,199 GitHub stars, 874 forks and 72 open issues, and was last pushed 8 months ago. On this registry it ranks #24 of 50 tracked projects in Threat Detection & Response, with 5 head-to-head comparisons available.

What is knockpy?

Knockpy is a modular Python 3 subdomain enumeration tool for security testers, bug bounty hunters, and penetration testers who need to discover and audit a domain's subdomains through passive reconnaissance, DNS bruteforce, or both.

What it is

Knockpy is a command-line tool written in Python 3 that enumerates subdomains of a target domain using two complementary modes: passive reconnaissance across plug-in sources, and wordlist-driven DNS bruteforce, used individually or together. Its scanning engine is built on asynchronous httpx requests and async DNS resolution, with terminal output rendered through Rich as tables, progress bars, and panels. The codebase is split by responsibility into cli.py, engine/, cli_parts/, storage_parts/, and report.py, with stable facades such as core.py and storage.py kept for backward compatibility.

The concrete problem it addresses is that subdomain discovery and triage normally means stitching together separate lookups, ad-hoc scripts, and manual inspection of results. Knockpy consolidates this into a single run that resolves candidates, validates HTTP/HTTPS status, TLS certificates, and IP addresses, and stores the findings in a SQLite report you can later show, delete, export, search, or render as HTML. It also surfaces issues that would otherwise require separate checks, such as AXFR zone-transfer exposure on the root domain and legacy TLS 1.0/1.1 support, which it flags as warnings in the CLI, verbose output, and HTML report.

Key capabilities

  • Runs passive recon (--recon), bruteforce (--bruteforce/--brute), or both in one async scan, with an interactive --setup for persisted runtime defaults and API keys.
  • Diagnoses a single target in depth with --verbose, covering DNS, TCP, TLS, redirect chains, request errors, and security checks.
  • Checks AXFR zone transfers on the root domain during domain-mode scans and detects wildcard DNS via --wildcard.
  • Detects legacy TLS 1.0/1.1 support and reports it as a warning in CLI, verbose, and HTML output.
  • Stores runs in SQLite and exposes an interactive report mode (--report [ID|latest|list]) for show, delete, export, search, reset, and HTML export.
  • Integrates VirusTotal and Shodan API keys, configurable through --setup.
  • Filters results with --exclude TYPE VALUE on status, length/lenght, or body, and offers --test to check each recon source for failed, empty, or data responses.

Who uses it and how

  • Bug bounty practitioners triaging the scope of a target domain, using passive recon to seed candidates and bruteforce with a wordlist to extend coverage.
  • Penetration testers running knockpy -d domain.com as a first recon step, then using --verbose on specific hosts for DNS, TLS, and redirect diagnostics.
  • Teams scanning many domains at once by feeding -f a file of domains and tuning --threads and --timeout for large runs.
  • Analysts working from stored results through --report, exporting HTML reports or JSON output (--json, which forces --silent) into other tooling.
  • Environments where API keys and runtime defaults are managed once via --setup and reused across scans.

Getting started

Clone the repository from https://github.com/guelfoweb/knockpy.git, create and activate a virtual environment, and run python3 -m pip install . (Python 3.9+ is recommended); afterwards launch scans with knockpy -d domain.com [options]. A pip install knock-subdomains install is described as available only after the stable version is released on PyPI.

How it compares

Knockpy stands alone in this registry: the facts provided name no comparable subdomain enumeration projects for it to be measured against.

When to use it — and when not

Practical use assumes you can supply a wordlist, a DNS resolver, an HTTP user agent, and optionally VirusTotal and Shodan API keys, plus willingness to tune --threads and --timeout for large scans. It is not a fit for teams that need a hosted or web-based service rather than a local CLI, and the repository currently carries 72 open issues, so operators should check issue state before relying on it in a tight engagement.

project readme (upstream, from github) — read inline

🔍 Knockpy Subdomain Scan v9.0

✅ Fast & Async • 🔐 Recon + Brute • 🔧 Easy to Extend

KnockPy is a modular Python 3 tool to enumerate subdomains via passive reconnaissance and bruteforce, now with async/await support, enhanced performance, and modern HTTP/TLS handling.

🚀 Features (v9)

  • ✅ Async scanning with httpx and DNS resolution
  • ✅ Modular: plug new passive sources easily
  • 🔍 Supports passive recon, bruteforce, or both
  • 🎨 Formatted terminal output with Rich (tables, progress, panels)
  • 📜 Validates HTTP/HTTPS status, TLS cert, and IP
  • ⚠️ Detects legacy TLS support (TLS 1.0/1.1) as warning in CLI/verbose/HTML report
  • 🧾 Checks AXFR (zone transfer) on root domain during domain-mode scans
  • 🔎 --verbose single-domain diagnostics (DNS/TCP/TLS/redirect chains/request errors + security checks)
  • 💡 Supports wildcard DNS detection
  • 🧪 SQLite reports with interactive catalog (show/delete/export/search)
  • 🔐 Supports VirusTotal and Shodan API
  • 🚀 Optimized bruteforce runtime with TLS-probe endpoint caching (no timeout changes required)

📦 Installation

From GitHub source (recommended)

git clone https://github.com/guelfoweb/knockpy.git
cd knockpy
# recommended: install in a virtual environment
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -U pip
pip install .

# alternative: install for the current user (no venv)
# python3 -m pip install --user .

⚠️ Recommended Python version: 3.9+

🧱 Project Structure

The codebase is organized by responsibility, with stable facades for backward compatibility:

knockpy/
  cli.py                   # CLI entrypoint (facade/orchestration)
  cli_parts/
    status.py              # runtime/status panel rendering
    setup.py               # interactive setup and persisted runtime defaults
    report.py              # interactive report mode
    scan_flow.py           # exclude rules, recon-test, wildcard helpers
  core.py                  # public core facade (compatibility)
  engine/
    runtime.py             # scanning engine implementation
  storage.py               # public storage facade (compatibility)
  storage_parts/
    db.py                  # SQLite persistence/settings
    export.py              # report export orchestration
    html_report.py         # HTML report rendering
  output.py                # terminal output rendering
  server_versions.py       # web-server versions catalog
  knockpy.py               # compatibility module exports

Compatibility note:

  • Preferred external imports: import knockpy or from knockpy import KNOCKPY.
  • Internal modules are split into engine/, cli_parts/, and storage_parts/.

Using pip

Only after the stable version is released on GitHub

pip install knock-subdomains

🧪 Usage

knockpy -d domain.com [options]

Options

Flag Description
-d, --domain Target domain (or stdin if used without value)
-f, --file File with list of domains
--recon Enable passive reconnaissance
--bruteforce, --brute Enable bruteforce using wordlist
--exclude TYPE VALUE Exclude matches (status, length/lenght, body)
--verbose Deep diagnostics for single-domain scans only
--wildcard Test wildcard DNS and exit
--test With --recon, test each recon source (failed/empty/data)
--setup Interactive setup (runtime defaults + API keys in DB)
--update-versions Update local latest web-server versions catalog
--report [ID|latest|list] Report mode (interactive show/delete/export/search/reset db, export HTML)
--check-update Check online if a newer Knockpy release is available on PyPI
--wordlist Runtime override for wordlist
--dns Runtime override for DNS resolver
--useragent Runtime override for HTTP user-agent
--timeout Runtime override for timeout (seconds)
--threads Runtime override for concurrent workers
--silent Hide progress bar
--json JSON-only output (forces --silent)
--status Print runtime status and continue
-h, --help Show help message

Performance Tuning: --threads and --timeout

These two options have the biggest impact on runtime for large scans.

  • --threads controls concurrency (how many targets are processed in parallel)
  • --timeout controls how long each network step waits before giving up

Trade-off:

  • higher threads = faster scans, but more load on CPU/network/DNS and higher risk of remote rate-limits
  • lower timeout = faster scans, but higher risk of missing slow yet valid targets (false negatives)

Recommended profiles:

  • small/accurate scan (few domains): --threads 50 --timeout 5
  • balanced scan: --threads 150 --timeout 4
  • large scan (10k+ domains): start with --threads 250 --timeout 3

If you need both speed and completeness on very large lists, use 2-pass strategy:

  1. fast pass: --threads 250 --timeout 3
  2. retry pass only on missing/uncertain targets: --threads 80 --timeout 5 (or higher)

Notes:

  • CLI values always override saved setup values
  • saved setup values (--setup) override built-in defaults
  • current built-in defaults are threads=250, timeout=3

📌 Examples

🔎 Recon + Brute

knockpy -d example.com --recon --bruteforce

🧪 Recon services test

knockpy -d example.com --recon --test

🔄 Update web-server latest versions catalog

knockpy --update-versions

🆕 Check for Knockpy updates

knockpy --check-update

⚙️ Recon sources config (editable)

At first run, KnockPy creates:

~/.knockpy/recon_services.json

You can add/disable sources by editing the services array. You can also point to a custom file path without changing code:

export KNOCK_RECON_SERVICES=/path/to/recon_services.json

Each service supports:

  • name
  • enabled (true/false)
  • parser
  • url_template (supports {domain}, {virustotal_key}, {shodan_key})
  • requires_api (virustotal or shodan, optional)

Supported parsers:

  • csv_first_column
  • rapiddns_html_td
  • json_list
  • virustotal_subdomains
  • shodan_subdomains

📥 Domain from stdin

echo "example.com" | knockpy -d

🧠 API Keys (optional)

export API_KEY_VIRUSTOTAL=your-virustotal-api-key
export API_KEY_SHODAN=your-shodan-api-key

You can use .env file:

API_KEY_VIRUSTOTAL=your-virustotal-api-key
API_KEY_SHODAN=your-shodan-api-key

💾 Reports (SQLite + Interactive HTML export)

knockpy -d example.com --recon --bruteforce
knockpy --report list
knockpy --report latest
knockpy --report

Interactive report menu:

  • 1 show
  • 2 delete
  • 3 export
  • 4 search
  • 0 reset db (asks explicit confirmation)

Exit report mode:

  • press Enter on empty action prompt
  • or press CTRL+C

🔍 Single-domain diagnostics

knockpy -d forum.example.com --verbose

🧪 Wildcard test only

knockpy -d example.com --wildcard

🧬 Python API Usage

KnockPy can be used as a Python module:

import knockpy

result = knockpy.KNOCKPY("example.com", timeout=5.0, threads=20)
print(result["domain"], result["ip"])

or:

from knockpy import KNOCKPY

domain = 'example.com'

results = KNOCKPY(
    domain,
    dns="8.8.8.8",
    useragent="Mozilla/5.0",
    timeout=5,
    threads=10,
    recon=True,
    bruteforce=True,
    wordlist=None,
    silent=False
)

for entry in results:
    print(entry['domain'], entry['ip'], entry['http'], entry['cert'])

📂 Wordlist

A default wordlist is included in knockpy/wordlist/wordlist.txt. You can supply your own with --wordlist.

Test

python3 -m pytest

# (optional) smoke-run example script
python3 examples/poc.py

📖 License

Licensed under the GPLv3 license.

Gianni Amato (@guelfoweb)

Frequently asked questions

Is knockpy free to use?

knockpy is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does knockpy do?

Knock Subdomain Scan

What is knockpy written in?

knockpy is primarily written in Python. Its source is publicly available at https://github.com/guelfoweb/knockpy, and it has 4,199 GitHub stars.