HackDev-PortScanner

Async TCP/UDP port scanner with banner grabbing, service fingerprinting, and a lightweight OS heuristic, part of the HackDev cybersecurity toolkit.

HackDev-PortScanner is a fast, dependency-free Python port scanner built on asyncio. It scans a single host, hostname, or an entire CIDR range against a flexible port specification, grabs banners from open TCP ports, sends protocol-appropriate probes for UDP services, and guesses the running service/version from a built-in signature table.

Features

• TCP scanning: asyncio-based concurrent scanning with a configurable connection pool (--threads)
• Real UDP scanning (--udp/--udp-only): protocol-appropriate probes for DNS, NTP, and SNMP, with ICMP-port-unreachable detection to distinguish closed from open|filtered, plus exponential-backoff retries (--udp-retries) since UDP is inherently lossy
• Service/version fingerprinting: banners are matched against a signature table (OpenSSH, FTP daemons, nginx/Apache/IIS, SMTP/IMAP/POP3, MySQL/MariaDB, Redis, and more) to report a guessed product + version, not just a generic port name
• OS fingerprinting heuristic (--os-fingerprint): a clearly-labeled, best-effort guess from TCP response TTL bucketing — not nmap-grade, just a hint
• Async DNS resolution: hostnames and CIDR ranges are both supported as targets; hostnames resolve concurrently before scanning starts
• --top-ports N: scan only the N most common ports instead of specifying a range
• Token-bucket rate limiting (--rate) to cap TCP connection attempts per second
• Text (human table) and JSON output formats, plus file output via -o/--output
• Structured logging via the logging module (no bare print() for status/errors)

Installation

Requires Python 3.10+. No third-party runtime dependencies.

git clone https://github.com/raghubirrajmahato15/HackDev-PortScanner.git
cd HackDev-PortScanner
pip install -r requirements.txt   # no-op, stdlib only

Usage

Scan the default port range (1-1024) on a single host:

python portscan.py 192.168.1.10

Scan the top 100 most common ports plus UDP, verbose logging:

python portscan.py scanme.example.com --top-ports 100 --udp -v

Scan an entire subnet with an OS heuristic, higher concurrency, and a rate cap, JSON to a file:

python portscan.py 10.0.0.0/24 -p 22,80,443,3389 --os-fingerprint --threads 500 --rate 200 --format json -o results.json

UDP-only scan of common UDP services with extra retries against a lossy network:

python portscan.py 192.168.1.1 -p 53,123,161,500 --udp-only --udp-retries 4

Example text output

HOST                PORT    PROTO STATE           SERVICE         VERSION                     BANNER
192.168.1.10        22      tcp   open            ssh             OpenSSH 9.6                 SSH-2.0-OpenSSH_9.6
192.168.1.10        80      tcp   open            http            nginx 1.24.0                HTTP/1.1 200 OK
                       OS guess: Linux/Unix-like (heuristic)
192.168.1.10        53      udp   open            dns             unknown

2 result(s) in 1.42s

Example JSON output

{
  "results": [
    {
      "host": "192.168.1.10",
      "port": 22,
      "protocol": "tcp",
      "state": "open",
      "service": "ssh",
      "banner": "SSH-2.0-OpenSSH_9.6",
      "version": "OpenSSH 9.6",
      "os_guess": "Linux/Unix-like (heuristic)"
    }
  ],
  "stats": { "total_found": 1, "duration_seconds": 1.42 }
}

CLI flag reference

Flag	Default	Description
target (positional)	—	Host, hostname, IP address, or CIDR range to scan
-p, --ports	1-1024	Port specification: ranges and/or comma-separated list (mutually exclusive with --top-ports)
--top-ports N	—	Scan only the top N most common ports instead of --ports
--udp	off	Also scan UDP ports (in addition to TCP)
--udp-only	off	Scan UDP only, skip TCP entirely
--udp-retries	2	UDP retry attempts (exponential backoff)
--os-fingerprint	off	Run a lightweight TCP-behavior OS heuristic per host
-o, --output	stdout	Write results to a file instead of stdout
--format	text	Output format: text or json
-v, --verbose	off	Enable verbose (debug) logging
--threads	200	Maximum concurrent TCP connection attempts
--timeout	3	Per-connection timeout in seconds
--banner-timeout	2	Timeout in seconds for reading a TCP banner after connecting
--rate	0	Maximum TCP connection attempts per second (0 = unlimited)

Project layout

portscan.py                  Thin CLI entrypoint
hackdev_portscanner/
  scanner.py                 Core async TCP scan engine, ScanResult model, rate limiter
  udp_scanner.py             Real UDP scanning with protocol-appropriate probes + retry/backoff
  fingerprint.py              Banner signature matching + OS-heuristic classification
  ports.py                    Port-spec parsing, CIDR/target expansion, top-ports list
  resolver.py                 Async DNS resolution
  cli.py                      argparse wiring, output formatting
tests/                        pytest suite (see below)

Testing

pip install -r requirements-dev.txt
pytest -q

The suite includes real end-to-end tests against loopback sockets (not just mocks): a live TCP server is started on 127.0.0.1 and the scanner is pointed at it alongside a guaranteed-closed port, confirming the scanner correctly reports the open port with its banner and reports nothing for the closed one. UDP scanning, port-spec parsing, CIDR expansion, banner/OS fingerprinting, the rate limiter's actual timing behavior, and CLI argument handling are all covered too.

Legal

This tool is intended for authorized security testing only — systems you own, or systems you have explicit written permission to test. Scanning networks or hosts without authorization may violate the Computer Fraud and Abuse Act (US), the Computer Misuse Act (UK), or equivalent laws in your jurisdiction. The authors and contributors accept no liability for misuse of this software.