Port Scanner (Python)

A beginner-friendly TCP/UDP port scanner built in Python.

This project was built step-by-step to learn:

• socket programming
• command-line interfaces (argparse)
• multithreading (ThreadPoolExecutor)
• JSON output
• basic testing with unittest

Legal and Ethical Use

Use this tool only on systems you own or have explicit permission to test. Unauthorized scanning may be illegal.

Features

• TCP scanning (--scan-type tcp)
• UDP scanning (--scan-type udp)
• Port range scanning (--start, --end)
• Multithreaded scanning (--threads)
• Optional TCP banner grabbing (--banner)
• JSON result export (--output)
• Input validation for safe argument ranges
• Automated tests

Project Structure

• port_scanner.py: Entry point and orchestration
• cli.py: Command-line argument definitions
• scanner.py: TCP/UDP scanning logic
• utils.py: Validation and JSON save helpers
• tests/test_validation.py: Validation unit tests
• tests/test_scanner.py: Local integration-style scanner tests

Requirements

• Python 3.10+
• Works on Windows PowerShell (also compatible with other shells)

Quick Start

Open terminal in project folder and run:

python port_scanner.py 127.0.0.1 --start 1 --end 1024

Command Options

• target (required): Domain or IP
• --scan-type {tcp,udp}: Protocol to scan (default: tcp)
• --start: Start port (default: 1)
• --end: End port (default: 1024)
• --timeout: Socket timeout in seconds (default: 0.5)
• --threads: Number of threads (default: 100, allowed: 1-500)
• --banner: Try banner grabbing for open TCP ports
• --output: Output JSON path (default: result.json)

Example Commands

1) Basic TCP scan

python port_scanner.py 127.0.0.1 --scan-type tcp --start 1 --end 1024

2) TCP scan with banner grabbing

python port_scanner.py 127.0.0.1 --scan-type tcp --start 8000 --end 8005 --banner --output result_tcp.json

3) UDP scan

python port_scanner.py 127.0.0.1 --scan-type udp --start 53 --end 60 --output result_udp.json

Safe Local Testing

Start a local HTTP server in one terminal:

python -m http.server 8000

Run scanner in another terminal:

python port_scanner.py 127.0.0.1 --scan-type tcp --start 7990 --end 8010 --banner

Expected result: port 8000 should appear as open.

Output JSON Format

The scanner writes a JSON report with fields like:

• target, target_ip
• scan_type
• port_range
• threads, timeout, banner_mode
• started_at, duration_seconds
• total_scanned, total_interesting
• detected_ports (list of port, protocol, state, service, banner)

Running Tests

Run all tests:

python -m unittest discover -s tests -v

Notes

• UDP scanning is less reliable than TCP by nature; open|filtered is common.
• Banner grabbing works only for TCP mode.
• Firewalls can hide real port states.

Learning Progress (Step Summary)

1. Built basic TCP scanner
2. Added input validation
3. Added timing, summary stats, and JSON export
4. Added optional banner detection
5. Added UDP scan mode
6. Refactored into modules
7. Added tests
8. Added project documentation