8.0.0

Author: guelfoweb

.env

@@ -0,0 +1,4 @@
+# .env
+API_KEY_VIRUSTOTAL=
+API_KEY_SHODAN=
+

.gitignore

@@ -4,4 +4,5 @@ build/
 knockpy.egg-info/
 *.pyc
 knockpy_report/
-knock_subdomains.egg-info/
+knock_subdomains.egg-info/
+.env

README.md

@@ -1,91 +1,151 @@
-# Knock Subdomain Scan v7
+# 🔍 Knock Subdomain Scan v8
 
-:heavy_check_mark: Fast :heavy_check_mark: Easy :heavy_check_mark: Modular
+✅ Fast & Async • 🔐 Recon + Brute • 🔧 Easy to Extend
 
-**Knockpy** is a portable and modular `python3` tool designed to quickly enumerate subdomains on a target domain through *passive reconnaissance* and *dictionary scan*.
+**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.
 
-![knockpy7](https://github.com/guelfoweb/knock/assets/41558/b168f105-720f-4f21-aba1-5be5c0326957)
+> Version: **8**  
+> GitHub: [https://github.com/guelfoweb/knock](https://github.com/guelfoweb/knock)
 
-## Install via pip
+![knockpy8](https://github.com/guelfoweb/knock/assets/41558/b168f105-720f-4f21-aba1-5be5c0326957)
 
-```
-pip install knock-subdomains
-```
+---
+
+## 🚀 Features (v8)
+
+- ✅ **Async scanning** with `httpx` and DNS resolution
+- ✅ Modular: plug new passive sources easily
+- 🔍 Supports **passive recon**, **bruteforce**, or both
+- 📜 Validates **HTTP/HTTPS status**, **TLS cert**, and **IP**
+- 💡 Supports **wildcard DNS** detection
+- 🧪 Output as **JSON**, optional save & reload
+- 🔐 Supports **VirusTotal** and **Shodan** API
+
+---
+
+## 📦 Installation
 
-## Install via git
+### From GitHub source (recommended)
 
 ```bash
 git clone https://github.com/guelfoweb/knock.git
 cd knock
 pip install .
 ```
 
-## Usage
+⚠️ Recommended Python version: 3.9+
 
-```
-usage: KNOCKPY [-h] [-d DOMAIN] [-f FILE] [-v] [--dns DNS] [--useragent USERAGENT]
-               [--timeout TIMEOUT] [--threads THREADS] [--recon] [--bruteforce] 
-               [--wordlist WORDLIST] [--json-output] [--list] [--report REPORT]
-
-knockpy v.7.0.1 - Subdomain Scan
-https://github.com/guelfoweb/knock
-
-options:
-  -h, --help            show this help message and exit
-  -d DOMAIN, --domain DOMAIN
-                        domain to analyze
-  -f FILE, --file FILE  domain list from file path
-  -v, --version         show program's version number and exit
-  --dns DNS             custom dns
-  --useragent USERAGENT
-                        custom useragent
-  --timeout TIMEOUT     custom timeout
-  --threads THREADS     custom threads
-  --recon               subdomain reconnaissance
-  --bruteforce          subdomain bruteforce
-  --wordlist WORDLIST   wordlist file to import
-                        --bruteforce option required
-  --wildcard            test wildcard and exit
-  --json                shows output in json format
-  --save FOLDER         folder to save report
-  --report REPORT       shows saved report
+
+### Using pip
+
+*Only after the stable version is released on GitHub*
+
+```bash
+pip install knock-subdomains
 ```
 
-### Example
+## 🧪 Usage
 
-- Start scanning domain with `--recon` and `--bruteforce` options
+```bash
+knockpy -d domain.com [options]
+```
+
+### Options
+
+| Flag              | Description                        |
+| ----------------- | ---------------------------------- |
+| `-d`, `--domain`  | Target domain                      |
+| `-f`, `--file`    | File with list of domains          |
+| `--recon`         | Enable passive reconnaissance      |
+| `--bruteforce`,`brute`    | Enable bruteforce using wordlist   |
+| `--wordlist`      | Custom wordlist (default included) |
+| `--dns`           | Custom DNS resolver                |
+| `--useragent`     | Custom HTTP user-agent             |
+| `--timeout`       | Request timeout in seconds         |
+| `--threads`       | Number of concurrent workers       |
+| `--wildcard`      | Test wildcard DNS and exit         |
+| `--json`          | Output results in JSON             |
+| `--save FOLDER`   | Save report to folder              |
+| `--report FILE`   | Load and show a saved report       |
+| `--silent`        | Hide progress bar                  |
+| `--logfile`       | Write debug log to file            |
+| `--show-settings` | Print scan settings and continue   |
+| `--version`       | Show KnockPy version               |
+| `-h`, `--help`    | Show help message                  |
+
+
+## 📌 Examples
+
+### 🔎 Recon + Brute
 
 ```bash
-knockpy -d domain.com --recon --bruteforce
+knockpy -d example.com --recon --bruteforce
 ```
 
-- Set API KEY: VirusTotal and Shodan
+### 🧠 API Keys (optional)
 
 ```bash
 export API_KEY_VIRUSTOTAL=your-virustotal-api-key
 export API_KEY_SHODAN=your-shodan-api-key
 ```
 
-- Save the report in a folder
+You can use `.env` file:
 
 ```bash
-knockpy -d domain.com --recon --bruteforce --save report
+API_KEY_VIRUSTOTAL=your-virustotal-api-key
+API_KEY_SHODAN=your-shodan-api-key
 ```
 
-- Shows saved report
+### 💾 Save and reload report
 
 ```bash
-knockpy --report domain.com_yyyy_aa_dd_hh_mm_ss.json
+knockpy -d example.com --recon --bruteforce --save report/
+knockpy --report report/example.com_2025_10_25_14_00_00.json
 ```
 
-### Import as module
+### 🧪 Wildcard test only
+
+```bash
+knockpy -d example.com --wildcard
+```
+
+## 🧬 Python API Usage
+
+KnockPy can be used as a Python module:
 
 ```python
 from knock import KNOCKPY
 
-domain = 'domain.com'
+domain = 'example.com'
+
+results = KNOCKPY(
+    domain,
+    dns="8.8.8.8",
+    useragent="Mozilla/5.0",
+    timeout=2,
+    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 `knock/wordlist/wordlist.txt`.
+You can supply your own with `--wordlist`.
 
-results = KNOCKPY(domain, dns=None, useragent=None, timeout=None, threads=None, recon=True, bruteforce=True, wordlist=None)
+## Test
 
-print (results)
+```bash
+python tests/poc.py
 ```
+
+## 📖 License
+
+Licensed under the GPLv3 license.
+Gianni Amato (@guelfoweb)