Python Port Scanner

A beginner-friendly Python port scanner project built to help me learn how TCP port scanning works using Python sockets.

This repository includes:

• a working single-threaded port scanner
• a threaded port scanner currently in progress

---

Table of Contents

• Overview
• Project Goals
• Current Features
• Project Structure
• How the Scanner Works
• Requirements
• Installation
• Usage
• Example Run
• What I Learned
• Planned Improvements
• Disclaimer

---

Overview

This project was created as part of my Python and cybersecurity learning journey.

The purpose of this repository is to practice:

• working with Python modules
• understanding socket programming
• learning how TCP connections are used for port scanning
• validating user input
• measuring scan runtime
• exploring multithreading for performance improvements

---

Project Goals

The main goals of this project are to:

• understand how the socket module works
• build a basic TCP port scanner from scratch
• learn the logic behind checking open ports
• improve code organization with functions
• experiment with threading to speed up scanning
• document progress through GitHub

---

Current Features

Basic Port Scanner (port_scan.py)

• accepts a hostname or IP address
• resolves hostnames to an IPv4 address
• validates IP addresses
• scans through a user-defined number of ports
• checks whether a port is open using TCP socket connections
• displays open ports found during the scan
• shows how long the scan took to complete
• uses colored terminal output with colorama

Threaded Port Scanner (threaded_port_scan.py)

• intended to scan ports faster using threads
• uses threading-related components such as workers, locks, and queues
• currently still being developed and debugged

---

Project Structure

python-port-scan/
│
├── port_scan.py
├── threaded_port_scan.py
└── README.md

File Descriptions

port_scan.py

The first working version of the scanner.
This script focuses on simplicity and understanding the core logic of port scanning.

threaded_port_scan.py

A work-in-progress version that attempts to improve scan speed using multithreading.

---

How the Scanner Works

The basic scanner follows this process:

1. Ask the user for a target host
2. Resolve the hostname to an IP address
3. Ask how many ports to scan
4. Loop through each port in the chosen range
5. Create a TCP socket for each port
6. Attempt a connection to the target
7. Identify whether the port is open
8. Close the socket after the attempt
9. Display the total runtime after the scan finishes

---

Requirements

• Python 3.x
• colorama

---

Installation

Clone the repository:

git clone https://github.com/tbaaaa/python-port-scan.git
cd python-port-scan

Install the required dependency:

pip install colorama

---

Usage

Run the basic scanner with:

python port_scan.py

You will be prompted to enter:

• the target hostname or IP address
• the number of ports to scan through

---

Example Run

Enter the host IP address or domain name to scan: scanme.nmap.org
Enter how many ports to increment through (large number ==> scan takes more time..): 100

Example output:

[+] Port 22 is open!
[+] Port 80 is open!
[+++] Completed port scan!
[+++] 2 ports are open on scanme.nmap.org.
[+++] Scan completed in 4.21 seconds.

---

What I Learned

Through this project, I practiced and improved my understanding of:

• Python modules and imports
• the socket module
• TCP connection logic
• validating IP addresses
• handling user input
• using functions to organize code
• measuring execution time
• using threading concepts like locks and queues

---

Planned Improvements

• finish and debug the threaded scanner
• allow users to define custom start and end port ranges
• improve command-line argument handling
• improve error handling and user feedback
• clean up and refactor code
• add comments and documentation throughout the scripts
• possibly add service detection or banner grabbing later

---

Disclaimer

This project is intended for educational purposes and authorized testing only.

Only scan systems that you own or have explicit permission to test.

---

Status

• port_scan.py → working
• threaded_port_scan.py → in progress