Python Port Scanner

A fast, multi-threaded TCP port scanner built from scratch in Python, designed for educational purposes and basic network reconnaissance. This tool helps identify open ports on a target host and can optionally grab banners from services running on those ports.

Table of Contents

• Features
• Getting Started
  • Prerequisites
  • Installation
  • Usage
• Development Journey & Attribution
• Contributing
• License
• Disclaimer

Features

• Multi-threaded Scanning: Efficiently scans multiple ports concurrently using Python's threading module.
• Customizable Port Range: Specify start-port and end-port to scan any desired range.
• Adjustable Concurrency: Control the number of simultaneous connections using --max-connections.
• Hostname Resolution: Automatically resolves hostnames to IP addresses.
• Verbose Output: Option to display the status (open, closed, or filtered) for every port scanned.
• Banner Grabbing: Attempts to retrieve service banners from open ports, providing insights into running services.
• Output to File: Save scan results to a specified file, with an option for automatic timestamped filename generation.
• Lightweight & Pure Python: No external dependencies beyond Python's standard library.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Python 3.x (Tested with Python 3.8+)
• Basic understanding of command-line interfaces.

Installation

1. Clone the repository:

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

2. No extra dependencies: This project uses only Python's standard library, so there are no additional pip install commands required.

Usage

Run the main.py script from your terminal.

python main.py --help

This will display the available options

usage: main.py [-h] [-t TARGET] [-sp START_PORT] [-ep END_PORT] [-mc MAX_CONNECTIONS] [-v] [-o [OUTPUT]]

A multi-threaded TCP Port Scanner Tool

options:
  -h, --help            show this help message and exit
  -t TARGET, --target TARGET
                        Target host to scan (e.g., 'example.com' or '192.168.1.1'). Defaults to 'localhost'.
  -sp START_PORT, --start-port START_PORT
                        Starting port for the scan range. Defaults to 1.
  -ep END_PORT, --end-port END_PORT
                        Ending port for the scan range (inclusive). Defaults to 1024.
  -mc MAX_CONNECTIONS, --max-connections MAX_CONNECTIONS
                        The maximum number of concurrent connections (threads) to use during scanning. Defaults to 100.
  -v, --verbose         Enable verbose output. Prints the status of every port (open, closed, or filtered) as it's scanned.
  -o [OUTPUT], --output [OUTPUT]
                        Specify an output file to save results (e.g., results.txt). If just '-o' is used without a
                        filename, a timestamped file will be created automatically in a 'port-scanner_results' directory.

Examples

• Scan default ports (1-1024) on localhost:

python main.py

• Scan a specific target and port range:

python main.py -t example.com -sp 1 -ep 65535

• Scan with verbose output (showing all port statuses):

python main.py -t scanme.nmap.org -v

• Scan with output saved to a custom file:

python main.py -t example.com -o my_scan_results.txt

• Scan with output saved to an auto-generated timestamped file:

python main.py -t example.com -o

• Combine options:

python main.py -t example.com -sp 80 -ep 1000 -mc 200 -v -o

Development Journey & Attribution

This Python Port Scanner was developed from the ground up as a learning project, focusing on core networking concepts with Python's socket module, multi-threading, and command-line argument parsing.

The entire development process, including incremental changes, problem-solving, and feature additions, is fully documented and can be traced in my main learning repository:

• Original Project Folder: AwaniCaleb/Python-Sockets/Port-Scanner

This project was built interactively with the assistance of a large language model (LLM). This collaborative approach allowed for rapid prototyping, concept clarification, and iterative refinement, demonstrating a modern method of software development where human expertise is augmented by AI capabilities.

While AI provided guidance and code suggestions, the core design decisions, problem analysis, and integration were driven by me as the developer.

Contributing

Contributions are welcome! If you have suggestions for improvements, bug fixes, or new features, please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature-name or bugfix/your-bug-fix).
3. Make your changes.
4. Commit your changes (git commit -m 'Add new feature').
5. Push to the branch (git push origin feature/your-feature-name).
6. Open a Pull Request.

Please ensure your code adheres to PEP 8 standards and includes appropriate comments and documentation. Read the CONTRIBUTING.md for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool is provided for educational and ethical hacking purposes only. Unauthorized port scanning or any form of network intrusion is illegal and unethical. The developer assumes no liability for any misuse or damage caused by this software.

Always obtain explicit permission before scanning any network or system that you do not own or have authorization to test.