🔍 PyPortScanner

A simple and educational TCP Port Scanner written in Python.

PyPortScanner is a beginner-friendly networking project that demonstrates how Python can communicate with network services using the built-in socket module.

This project was created to learn and understand the fundamentals of:

• Socket Programming
• TCP Connections
• IP Addresses
• Network Ports
• Client-Server Communication
• Basic Network Scanning Concepts

About This Project

A port scanner is a tool that checks whether specific ports on a computer or server are open or closed.

Every device connected to a network can run different services. These services communicate through numbered ports.

Examples:

• Port 22 → SSH
• Port 80 → HTTP
• Port 443 → HTTPS
• Port 3306 → MySQL
• Port 8000 → Development Servers

A port can have different states:

• Open: A service is running and accepting connections.
• Closed: No service is listening on that port.
• Filtered: A firewall or security system blocks access.

PyPortScanner checks ports by attempting to create TCP connections with the target machine.

How It Works

PyPortScanner uses Python's built-in socket module.

The scanning process:

1. The user enters a target IP address.
2. The user selects a starting port.
3. The user selects an ending port.
4. The program checks every port in the selected range.
5. It attempts a TCP connection.
6. If the connection succeeds, the port is marked as open.
7. The result is displayed in the terminal.

Example output:

Scanning 127.0.0.1 from port 7995 to 8005...

Port 8000 is open ✅

Scan complete. 1 open ports found: [8000]

Features

• Scan a range of TCP ports
• Detect open ports
• Simple command-line interface
• Timeout handling
• No external dependencies
• Uses Python standard library only

Technologies Used

• Python 3
• Socket Programming
• TCP Networking

Requirements

You only need:

• Python 3.x

Check your Python version:

python3 --version

No external libraries are required because this project uses only Python built-in modules.

Installation

Clone the repository:

git clone YOUR_REPOSITORY_URL

Enter the project directory:

cd PyPortScanner

Run the program:

python3 main.py

Usage

Start the scanner:

python3 main.py

The program will ask:

Enter target IP:
Start port:
End port:

Example:

Enter target IP: 127.0.0.1
Start port: 1
End port: 1024

Testing

The safest way to test this project is on your own computer.

Create a local test server:

python3 -m http.server 8000

This starts a simple HTTP server on port 8000.

Then run PyPortScanner:

Enter target IP: 127.0.0.1
Start port: 7995
End port: 8005

Expected result:

Port 8000 is open ✅

Troubleshooting

If you see:

Scan complete. 0 open ports found: []

It means no active service was found in the scanned range.

Start a test service:

python3 -m http.server 8000

and scan again.

If Python is not found:

python3 main.py

Make sure Python 3 is installed.

If you receive an invalid IP error, use a valid address such as:

127.0.0.1
192.168.1.10

Security Disclaimer

This project is created for educational purposes only.

Do not use this tool against:

• Other people's computers
• Public servers without permission
• Company networks without authorization
• Systems you do not own

Only use this tool on:

• Your own devices
• Your own networks
• Cybersecurity labs
• CTF environments
• Systems where you have permission

Unauthorized network scanning may violate laws and security policies.

Security Notes

PyPortScanner is a basic TCP Connect Scanner.

It is useful for learning networking and cybersecurity fundamentals, but it is not a replacement for professional security tools.

Professional tools may include:

• Service detection
• OS fingerprinting
• Vulnerability scanning
• Firewall analysis
• Advanced scanning techniques

This project focuses on learning the foundations of network scanning.

Future Improvements

Possible improvements:

• Add multithreading for faster scanning
• Detect running services
• Add command-line arguments using argparse
• Save results into files
• Add colored terminal output
• Add logging support
• Create a graphical interface
• Improve error handling

Project Structure

PyPortScanner/

├── main.py
├── scanner.py
├── README.md
├── LICENSE
├── requirements.txt
└── .gitignore

Why Build This Project?

Building a simple port scanner helps developers understand the connection between programming and cybersecurity.

Through this project, you learn:

• How computers communicate
• How TCP connections work
• How ports are used by services
• How Python interacts with networks
• How basic security tools are created

Small projects like this create the foundation for larger cybersecurity and networking projects.

Author

Created as a learning project while studying:

• Python Programming
• Networking Fundamentals
• Cybersecurity Concepts

⭐ If you find this project useful, consider giving it a star!