Skip to content

README.md

Latest commit

 

History

History
96 lines (66 loc) · 2.59 KB

README.md

File metadata and controls

96 lines (66 loc) · 2.59 KB

TCP SYN Port Scanner

Author: Matthew Wilson GitHub: https://github.com/GrumpyKit10 Date: 12/20/25 Language: Python 3

Description

A TCP SYN port scanner built with Scapy for educational purposes. This tool supports:

  • Scanning single IPs, hostnames, and CIDR ranges
  • Port range specifications (single, comma-separated, and hyphenated ranges)
  • Multi-threaded banner grabbing
  • Batch scanning with optional randomization for stealth
  • Multiple output formats: human-readable, grepable, JSON, CSV
  • Verbosity levels for detailed progress and debugging
  • ICMP filtered port handling

This scanner is designed for learning and ethical testing only. Do not use it on unauthorized systems.

Installation

  1. Clone the repository:
git clone https://github.com/GrumpyKit10/port_scanner.git
cd port_scanner
  1. Install dependencies:
pip3 install scapy
  1. Run as root (required for raw socket operations):
sudo python3 port_scanner.py

Usage

sudo python3 port_scanner.py -t TARGET -p PORTS -v VERBOSE -b BATCH -o OUTPUT -r

Arguments

  • -t, --target: Target to scan (hostname, IP, CIDR). Default: scanme.nmap.org
  • -p, --ports: Ports to scan (80, 22,80,443, 1-1024). Default: 1-1024
  • -v, --verbose: Verbosity level (0=quiet, 1=standard, 2=detailed, 4=full packets). Default: 1
  • -b, --batch: Number of ports scanned per batch. Default: 50
  • -o, --output: Output format (human, grep, json, csv). Default: human
  • -r, --randomize: Randomize host and port order for stealth.

Examples

sudo python3 port_scanner.py -t scanme.nmap.org
sudo python3 port_scanner.py -t 192.168.1.1 -p 22,80,443
sudo python3 port_scanner.py -t 192.168.1.0/24 -p 22 -r
sudo python3 port_scanner.py -t example.com -p 1-1024 -o json
sudo python3 port_scanner.py -t localhost -p 80 -v 4

Features

  • CIDR expansion: Scan all hosts in a network range.
  • Batch scanning: Control scan size per batch.
  • Randomization: Reduce scan patterns for stealth.
  • Banner grabbing: Detect service information on open ports.
  • Structured output: JSON/CSV for easy integration.
  • Progress reporting: Shows progress, ops/sec, ETA even in non-human outputs.
  • Interrupt handling: Ctrl+C safely stops the scan.

Warning

This tool is for educational and authorized penetration testing only. Unauthorized scanning may violate laws and policies.

License

MIT License