Home Posts Projects About Service

Port scanner

#Python #Networking #Sockets #Concurrency 2026/08/15 00:00:00
Table of contents
  1. Overview
  2. How it works
  3. Example usage
  4. What I learned
  5. Current status and next steps

Overview

This project is a command-line TCP port scanner built to learn how network clients establish connections and how concurrency changes the performance of I/O-bound work. It uses Python’s socket module to attempt a TCP connection to each port and a ThreadPoolExecutor to run multiple connection attempts concurrently.

The scanner currently:

  • Accepts a target hostname or IP address from the command line.
  • Scans a range of TCP ports, defaulting to ports 0–9999.
  • Allows the number of worker threads to be configured.
  • Applies a short socket timeout so unresponsive ports do not stall the scan.
  • Collects successful connections and prints the open ports in a table.
  • Uses the local service database to associate known port numbers with service names.

How it works

Each worker creates its own IPv4 TCP socket and calls connect_ex() against one port. A return value of zero indicates that the connection succeeded. Successful port numbers are collected after all tasks finish and then matched against the operating system’s service-name database with socket.getservbyport().

This last step is service-name lookup rather than active banner grabbing: it identifies the conventional service associated with a port number but does not prove which application is actually listening there.

Example usage

python scanner.py --host 127.0.0.1

The CLI also exposes --start-port, --end-port, and --threads options. Numeric argument validation for those overrides is one of the remaining fixes; the default values currently work as integers, while supplied values still need to be parsed explicitly as integers.

What I learned

  • The difference between a TCP connection attempt and a full protocol-aware probe.
  • How socket timeouts affect scan speed and reliability.
  • Why I/O-bound network checks benefit from a thread pool.
  • How to collect concurrent results without sharing a writable result list between workers.
  • Why a port’s conventional service name should not be treated as confirmed service detection.

Current status and next steps

The core concurrent scan and result table are working. Planned improvements include stricter host and port validation, a corrected progress indicator, graceful interruption, configurable timeouts, accurate active banner probing, and exportable results.

This tool is intended only for systems I own or have explicit permission to test.