Python Port Scanner

This tool allows you to scan a specific website on a specified port or range of ports to see if the port is open or closed and which service conventionally runs on that port.

Installation

git clone https://github.com/Al1ndas/port-scanner.git
cd port-scanner

For system wide tool run this command

uv tool install .

For the development version run this command

uv venv
source .venv/bin/activate
uv pip install -e .

Features

• Scan a website at a specific port
• Scan a website at a range of ports
• Customizable amount of threads
• Timeout flag for slower internet

Usage

❯ scanpy -h
usage: scanpy [-h] [-p PORT] [-w WORKERS] [-t TIMEOUT] domain

positional arguments:
  domain                 which domain to target

options:
  -h, --help             show this help message and exit
  -p, --port PORT        ports to scan, e.g. 80 or 1,1000 - default 80
  -w, --workers WORKERS  number of threads - default 100
  -t, --timeout TIMEOUT  response timeout in seconds - default 1.0

Version Benchmarks

Target: scanme.nmap.org, ports 1–1000, 1s timeout

sequential : 147.36s
threaded   :   1.54s   (100 workers, ~96× faster)
async      :   1.02s   (~144× faster)

The reason sequential is so bad is that most of the time is spent waiting for a response from the ports which causes our timeout to trigger. Which is why we need multitasking and between threaded and async the different was negligible at this scale. Async only pulls ahead at much higher connection counts, so the current version uses threading for its simpler, more maintainable code with a customizable thread count.

How it works

This scanner works by performing a TCP connect scan on a specified port and awaits a response. A return code of 0 from connect_ex means the handshake completed and the port is open. It performs a full TCP connect scan, so it cannot distinguish a closed port from a firewall-filtered one — that would require raw sockets." That limitation line is a strength: it shows you understand the tool's boundaries, which reads as maturity.

legal note

Only use this tool on systems you own or have explicit permission to scan, Unauthorized scanning may be illegal.

Roadmap

• UDP scanning (connectionless, so no handshake — relies on ICMP responses and timeouts)
• Distinguish filtered from closed ports using raw sockets
• SYN "half-open" scan for stealthier, faster scanning
• Rewrite the scanning engine in C for lower-level socket control
• Service/version detection by reading response banners