GitHub - RevoltSecurities/Khonshu: Khonsu is a powerful port scanning tool written in python that detect open ports with concurrent and accurately

Khonshu – A stealthy, concurrent port scanner written in asynchronous python that crafted for speed and accuracy.

Features:

Accurate, concurrent, and highly scalable scanning engine with distributed workers, adjustable concurrency, and deterministic results.
Passive scanning capability using Shodan Internet Database API for stealth reconnaissance
Resume functionality allows continuing interrupted scans from where they left off
JSON output format support for better integration with other security tools
Custom network interface selection and DNS resolver configuration for advanced networking
Port state filtering to show only specific port states (open, closed, filtered, unfiltered)
Enhanced rate limiting up to 1000 requests per second with configurable concurrency levels
Retry mechanism and configurable timeouts for improved scan reliability
Multiple ping methods for comprehensive host discovery and validation
All DNS IPs scanning to discover all IP addresses associated with a domain
Scans for both IPv4/IPv6 addresses with full protocol support

Installation:

Prerequisite

Note: before installing khonshu, make sure to install libpcap.

To install libcap on Linux: sudo apt install -y libpcap-dev, on Mac: brew install libpcap

Khonshu can be easily installed using the modern Python package installer uv. This method provides the fastest and most reliable installation experience.

Requirements:

Python 3.13 or higher
uv package manager

Quick Installation:

# Install using uv (Recommended)
uv tool install khonshu

Alternative Installation Methods:

# Install using pip
pip install khonshu

# Install from source
git clone https://github.com/RevoltSecurities/Khonshu.git
cd Khonshu
pip install .

Verify Installation:

khonshu --version

Update Khonshu:

# Update using built-in updater
khonshu --update

# Or update using uv
uv tool upgrade khonshu

Note: The uv tool install method automatically handles dependencies and provides better isolation, making it the preferred installation method for Khonshu.

Usage:

 khonshu -h

 _  __ _                         _            
| |/ /| |                       | |           
| ' / | |__    ___   _ __   ___ | |__   _   _ 
|  <  | '_ \  / _ \ | '_ \ / __|| '_ \ | | | |
| . \ | | | || (_) || | | |\__ \| | | || |_| |
|_|\_\|_| |_| \___/ |_| |_||___/|_| |_| \__,_|
                                              
                                              

                     - RevoltSecurities

                                                                             Khonshu – A stealthy, concurrent Python port scanner crafted for speed and accuracy.                                                                             

[DEFAULT FLAGS]
╭────────────┬────────────────────────────────────────╮
│ Flag       │ Description                            │
├────────────┼────────────────────────────────────────┤
│ -h, --help │ show this help message and exit.       │
├────────────┼────────────────────────────────────────┤
│ --plain    │ display the help message in plain text │
╰────────────┴────────────────────────────────────────╯

[INPUT]
╭───────────────────┬──────────────────────────────────────────────────────────────────────────────╮
│ Flag              │ Description                                                                  │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ -host, --host     │ hosts to scan for open ports and supports comma separated values             │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ -list, --list     │ file that contains list of host to scan for open ports                       │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ -exclude-hosts    │ hosts to exclude from the open port scan and supports comma separated values │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────┤
│ -resume, --resume │ resume file generated by khonshu to continue the port scanning               │
╰───────────────────┴──────────────────────────────────────────────────────────────────────────────╯

[PORT]
╭─────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Flag                    │ Description                                                                                                        │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -port, --port           │ ports to scan (80,443 1-65535)                                                                                     │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -top-ports, --top-ports │ top port numbers to scan (100,1000,full-port)                                                                      │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -port-file, --port-file │ file that contains list of port numbers to scan                                                                    │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -ep, --exclude-ports    │ port numbers to exclude from port scanning and supports comma separated values                                     │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -tcpt, --tcp-ports      │ comma-separated TCP port(s) to use for checking host availability via TCP SYN/ACK pings (e.g., 80,443,8080)        │
├─────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -pst, --port-state      │ show only ports matching the specified state (e.g. open,closed,filtered,unfiltered,open|filtered) (default: open). │
╰─────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[OUTPUT]
╭──────────────┬─────────────────────────────────────────────╮
│ Flag         │ Description                                 │
├──────────────┼─────────────────────────────────────────────┤
│ -o, --output │ filename to save the open port scan results │
├──────────────┼─────────────────────────────────────────────┤
│ -j, --json   │ enabled the output in json format           │
╰──────────────┴─────────────────────────────────────────────╯

[RATE-LIMIT]
╭───────────────────┬──────────────────────────────────────────────────────────────────────────────────────╮
│ Flag              │ Description                                                                          │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────────────┤
│ -c, --concurrency │ set the concurrency level for concurrent port scanning (default: 100)                │
├───────────────────┼──────────────────────────────────────────────────────────────────────────────────────┤
│ -rt, --rate-limit │ set a rate limit for sending a maximum number of requests per second (default: 1000) │
╰───────────────────┴──────────────────────────────────────────────────────────────────────────────────────╯

[UPDATES]
╭──────────────────────┬──────────────────────────────────────────╮
│ Flag                 │ Description                              │
├──────────────────────┼──────────────────────────────────────────┤
│ -up, --update        │ update the khonshu to the latest version │
├──────────────────────┼──────────────────────────────────────────┤
│ -sup, --show-updates │ show the latest updates of khonshu       │
╰──────────────────────┴──────────────────────────────────────────╯

[HOST-DISCOVERY]
╭─────────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────╮
│ Flag                                │ Description                                                                      │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -Sn, --host-discovery               │ perform only host discovery and skips the port scan                              │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -Pn, --skip-discovery               │ skip the host discovery and directly perform port scan                           │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -En, --enable-discovery             │ enable the host discovery before port scanning                                   │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -tcp-syn, --tcp-syn-ping            │ performs TCP SYN ping on host (requires: -En and -Sn)                            │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -tcp-ack, --tcp-ack-ping            │ performs TCP ACK ping on host (requires: -En and -Sn)                            │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -icmp-ping, --icmp-echo-ping        │ performs ICMP echo request on host (requires -En and -Sn)                        │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -it-ping, --icmp-timestamp-ping     │ performs ICMP timestamp ping request on host (requires -En and -Sn)              │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -iam-ping, --icmp-address-mask-ping │ performs ICMP address mask ping request on host (requires -En and -Sn)           │
├─────────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ -arp, --arp-ping                    │ performs Address Resolution Protocol ping request on host (requires -En and -Sn) │
╰─────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────╯

[CONFIGURATION]
╭──────────────────────────┬─────────────────────────────────────────────────────────────╮
│ Flag                     │ Description                                                 │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -scan, --scan-type       │ type of port scan we need to do (supports: connect,syn)     │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -all-ips, --scan-all-ips │ scan all ips of associated DNS record of the domain         │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -passive, --passive      │ run passive open port scanning using shodan Internet DB API │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -il, --interface-list    │ display the list of available interfaces                    │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -i, --interface          │ network interface to use for port scan                      │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ -resolver, --resolver    │ custom DNS resolver to use for dns resolution               │
╰──────────────────────────┴─────────────────────────────────────────────────────────────╯

[OPTIMIZATION]
╭─────────────────┬────────────────────────────────────────────────────────╮
│ Flag            │ Description                                            │
├─────────────────┼────────────────────────────────────────────────────────┤
│ -to, --timeout  │ seconds to wait for port scanning timeout (default: 1) │
├─────────────────┼────────────────────────────────────────────────────────┤
│ -retry, --retry │ number of retries for open port scanning               │
├─────────────────┼────────────────────────────────────────────────────────┤
│ -ping, --ping   │ ping and verify host for port scan (default: false)    │
╰─────────────────┴────────────────────────────────────────────────────────╯

[DEBUG]
╭─────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Flag                │ Description                                                                                                                   │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -hc, --health-check │ run the health check for the khonshu                                                                                          │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -debug, --debug     │ display the debugging information (debug option is specially for contributors and devs to understand the workflow of khonshu) │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -verbose, --verbose │ increase the verbosity of khonshu                                                                                             │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -version, --version │ shows the version of the khonshu                                                                                              │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -silent, --silent   │ shows only the port scanning results                                                                                          │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -stats, --stats     │ logs the progress of the khonshu                                                                                              │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ -nc, --no-color     │ disables the colored output of the khonshu                                                                                    │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Running Khonshu:

Khonshu provides flexible scanning options for various penetration testing scenarios. Below are common usage patterns and examples.

Basic Usage:

# Basic port scan on a single host
khonshu -host example.com

# Scan specific ports
khonshu -host example.com -port 80,443,8080

# Scan top 1000 ports
khonshu -host example.com -top-ports 1000

Multiple Hosts:

# Scan multiple hosts
khonshu -host example.com,target.com,test.org

# Scan from host list file
khonshu -list targets.txt

# Exclude specific hosts
khonshu -list targets.txt -exclude-hosts cdn.example.com

Advanced Scanning:

# SYN scan with custom concurrency
khonshu -host example.com -scan syn -c 200

# UDP scan with rate limiting
khonshu -host example.com -scan udp -rt 500

# Stealth scan with custom timeout
khonshu -host example.com -scan syn -to 3 -silent

Host Discovery:

# Perform only host discovery
khonshu -host example.com -Sn

# Skip host discovery and scan directly
khonshu -host example.com -Pn

# Use ICMP ping for host discovery
khonshu -host example.com -En -icmp-ping

Output Options:

# Save results to file
khonshu -host example.com -o results.txt

# JSON output format
khonshu -host example.com -j -o results.json

# Silent mode (results only)
khonshu -host example.com -silent

Passive Scanning:

# Use Shodan for passive reconnaissance
khonshu -host example.com -passive

# Scan all DNS-associated IPs
khonshu -host example.com -all-ips

Resume Scans:

# Resume interrupted scan
khonshu -resume resume_20240101_120000.cfg

Configuration Examples:

# Custom DNS resolver and interface
khonshu -host example.com -resolver 8.8.8.8 -i eth0

# High-performance scan
khonshu -host example.com -c 500 -rt 2000 -to 0.5

# Comprehensive security assessment
khonshu -host example.com -top-ports full-port -scan syn -En -verbose

Tip: Use khonshu --help to see all available options and flags, or khonshu --plain for plain text help output.

Host Discovery:

Khonshu provides comprehensive host discovery capabilities to determine which hosts are alive and reachable before performing port scans. This helps optimize scanning efficiency and reduces unnecessary network traffic.

Basic Host Discovery:

# Enable host discovery before port scanning
khonshu -host example.com -En -Sn

# Skip host discovery and scan directly
khonshu -host example.com -Pn

ICMP-based Discovery:

# ICMP echo request (ping) - requires -En and -Sn
khonshu -host example.com -En -Sn -icmp-ping

# ICMP timestamp ping - requires -En and -Sn
khonshu -host example.com -En -Sn -it-ping

# ICMP address mask ping - requires -En and -Sn
khonshu -host example.com -En -Sn -iam-ping

TCP-based Discovery:

# TCP SYN ping on default ports - requires -En and -Sn
khonshu -host example.com -En -Sn -tcp-syn

# TCP ACK ping - requires -En and -Sn
khonshu -host example.com -En -Sn -tcp-ack

# TCP ping on specific ports - requires -En and -Sn
khonshu -host example.com -En -Sn -tcp-syn -tcpt 80,443,8080

ARP Discovery:

# ARP ping for local network discovery - requires -En and -Sn
khonshu -host 192.168.1.1-254 -En -Sn -arp

Multiple Host Discovery:

# Discover multiple hosts with ICMP
khonshu -host example.com,target.org,test.net -En -Sn -icmp-ping

# Discover from host file
khonshu -list targets.txt -En -Sn -tcp-syn

# Exclude specific hosts from discovery
khonshu -list targets.txt -En -Sn -icmp-ping -exclude-hosts router.local,printer.local

Advanced Discovery Options:

# Combine multiple discovery methods
khonshu -host example.com -En -Sn -icmp-ping -tcp-syn -tcpt 22,80,443

# Discovery with custom timeout and concurrency
khonshu -host example.com -En -Sn -icmp-ping -to 2 -c 50

# Verbose discovery output
khonshu -host example.com -En -Sn -tcp-syn -verbose

Network Range Discovery:

# Discover all hosts in subnet
khonshu -host 192.168.1.0/24 -En -Sn -arp

Discovery with Output:

# Save discovery results
khonshu -host example.com -En -Sn -icmp-ping -o discovery_results.txt

# JSON format discovery output
khonshu -host example.com -En -Sn -tcp-syn -j -o discovery.json

# Silent discovery mode
khonshu -host example.com -En -Sn -tcp-ack -silent

Discovery with Custom Configuration:

# Custom DNS resolver for discovery
khonshu -host example.com -En -Sn -icmp-ping -resolver 8.8.8.8

# Discovery with retry mechanism
khonshu -host example.com -En -Sn -tcp-syn -retry 3 -to 5

Important: Most discovery methods require the combination of -En (enable discovery) and -Sn (host discovery mode) flags. ICMP and raw socket operations may require root/administrator privileges. Use -Pn to skip discovery if you know hosts are alive but not responding to pings.

Using Khonshu as a Library

This section explains how to embed Khonshu into Python projects and leverage its high-performance scanning pipeline programmatically. It includes usage of the scanner, Request/Response objects, combined Pyrunner execution, and best practices.

Notes:

uvloop is recommended on POSIX systems for performance.

Elevated privileges may be required for some scanning features.

Using Scanner, Request, and Response

import asyncio
from khonshu import AsyncConnectScanner, Request, Response

async def run_scanner():
    req = Request(ip='192.168.1.1', port=80)
    scanner = AsyncConnectScanner(timeout=2)
    resp: Response = await scanner.scan(req)

    if resp.status == "open":
        print(f"Port {resp.port} is open on {resp.ip}")
    else:
        print(f"Port {resp.port} is closed on {resp.ip}")

asyncio.run(run_scanner())

Using Pyrunner with Request/Response

import asyncio
from khonshu import Settings, Pyrunner

async def run_pyrunner():
    args = Settings(
        concurrency=50,
        rate_limit=200,
        timeout=2,
        retry=1,
        json=True,
        ports="80,443",
        scan_type="connect",
    )

    runner = Pyrunner(args)
    runner.inputer = 'targets.txt'

    try:
        await runner.sprint()
    finally:
        await runner.cleanup()

asyncio.run(run_pyrunner())
o.run(main())

Developed with 💙 by the RevoltSecurities Team.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github/workflows		.github/workflows
khonshu		khonshu
static		static
.dockerignore		.dockerignore
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

RevoltSecurities/Khonshu

Folders and files

Latest commit

History

Repository files navigation

Features:

Installation:

Requirements:

Quick Installation:

Alternative Installation Methods:

Verify Installation:

Update Khonshu:

Usage:

Running Khonshu:

Basic Usage:

Multiple Hosts:

Advanced Scanning:

Host Discovery:

Output Options:

Passive Scanning:

Resume Scans:

Configuration Examples:

Host Discovery:

Basic Host Discovery:

ICMP-based Discovery:

TCP-based Discovery:

ARP Discovery:

Multiple Host Discovery:

Advanced Discovery Options:

Network Range Discovery:

Discovery with Output:

Discovery with Custom Configuration:

Using Khonshu as a Library

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages