⬡ NMAP Scanner

A personal-use, dual-mode (GUI + CLI) network port scanner built in pure Python.
Discover open ports, identify running services, grab version banners, and generate detailed reports — all from a single file with zero dependencies.

---

📋 Table of Contents

• Overview
• Features
• Project Structure
• Requirements
• Installation
• Parrot OS / Kali Linux Setup
• UI Layout & Description
• Usage — GUI Mode
• Usage — CLI Mode
• Scan Profiles
• Export Formats
• Scan History & Compare
• Configuration & Logging
• Service Port Reference
• Known Issues & Fixes
• Legal & Ethical Use
• Changelog
• Contributing
• License

---

🔍 Overview

NMAP Scanner is a personal Python-based network port scanning tool built for hands-on learning and home network administration. It probes a target host or subnet to detect which TCP/UDP ports are open, identifies the services running on them, and optionally retrieves live software version banners directly from the service.

It runs in two fully independent modes:

Mode	How to Launch	Best For
GUI	python3 port_scanner.py (no args)	Interactive use, visual results, history browsing
CLI	python3 port_scanner.py --target <host> ...	Scripting, automation, headless/SSH environments

Built entirely on the Python standard library — no pip install required.

---

✨ Features

🔬 Scanning Engine

• TCP + UDP scanning — covers both connection-oriented and datagram protocols
• Banner grabbing — reads live version strings from open ports (e.g. OpenSSH_8.9p1, Apache/2.4.52)
• Priority port ordering — high-value ports (22, 80, 443, 3306, 3389 etc.) scanned first for instant results
• 80+ service definitions — extended port-to-service map (was 13 in v1.0)
• CIDR / subnet support — scan entire subnets e.g. 192.168.1.0/24
• Ping / liveness check — TCP-based pre-scan host verification
• Stealth mode — throttled thread launch to reduce IDS/firewall alert risk
• Categorised error tracking — distinguishes Timeout, Refused, Unreachable, DNS Failure
• Graceful stop — cancel mid-scan cleanly without leaving hanging threads

🖥️ GUI Features

• Dark mode / Light mode toggle — one-click theme switch
• Sortable Treeview table — columns: Port · Protocol · Service · State · Banner
• 4 scan profiles — Quick / Standard / Deep / Custom (auto-fills all settings)
• Real-time stats — live open port count, progress percentage, elapsed timer
• Timestamped colour-coded log console — green for open ports, blue for info, orange for warnings
• Scan History tab — last 50 scans persisted locally, reloadable at any time
• Scan Compare / Diff tab — compare two past scans, see newly opened or closed ports
• 4 one-click export buttons — TXT · CSV · JSON · HTML

💻 CLI Features

• Full argparse-based interface — every scan option available as a flag
• Multi-host and subnet scanning in a single command
• Profile selection via --profile
• Output format selection via --output
• Stealth, UDP, banner, and ping as simple flags

📤 Export & Reporting

• TXT — Human-readable plain text
• CSV — Excel / Google Sheets compatible
• JSON — Structured output for scripting
• HTML — Standalone dark-themed report with summary cards, no internet required to view

📁 Persistence & Logging

• Auto-logging — every scan written to ~/.port_scanner/logs/scan_YYYYMMDD.log
• Scan history — stored as JSON in ~/.port_scanner/history.json (last 50 entries)

---

📁 Project Structure

NMAP-port-scanner/
│
├── port_scanner.py       ← Entire application (engine + GUI + CLI)
└── README.md             ← This file

# Auto-generated at first run (inside your home directory):
~/.port_scanner/
├── history.json          ← Persistent scan history (last 50 scans)
└── logs/
    ├── scan_20250101.log
    └── ...               ← One log file per calendar day

The entire application is self-contained in port_scanner.py — no packages, no virtual environments, no setup scripts.

---

📦 Requirements

Python Version

Python 3.8 or higher

Check your version:

python3 --version

Dependencies

None. Every module used is part of the Python standard library.

Module	Purpose
socket	TCP/UDP connection probing and banner grabbing
threading	Concurrent port scanning
queue	Thread-safe result delivery to the GUI
tkinter	Desktop GUI (GUI mode only — see install note below)
argparse	CLI flag parsing
ipaddress	CIDR/subnet expansion
json	History persistence and JSON export
csv	CSV export
logging	Auto log file generation
pathlib	Cross-platform file paths

---

🚀 Installation

Step 1 — Clone the repository

git clone https://github.com/SaiSugeet/NMAP-port-scanner.git
cd NMAP-port-scanner

Step 2 — Verify Python

python3 --version
# Expected: Python 3.8 or higher

Step 3 — Install tkinter (Linux only)

Tkinter ships with Python on Windows and macOS automatically.
On Linux it requires a one-time install — see the Parrot OS / Kali Linux Setup section below.

Step 4 — Run

# GUI mode (no arguments)
python3 port_scanner.py

# CLI mode
python3 port_scanner.py --target 192.168.1.1 --ports 1-1024

---

🦜 Parrot OS / Kali Linux Setup

Security distros like Parrot OS and Kali Linux do not ship with tkinter by default. Follow these steps exactly.

Step 1 — Install tkinter

sudo apt-get update --fix-missing
sudo apt-get install python3-tk -y --no-install-recommends --fix-missing

Note: If your mirrors return 404 errors for unrelated packages (e.g. samba, libldb2), the --fix-missing flag tells apt to skip those and install python3-tk anyway. This is a known Parrot OS mirror sync issue and does not affect the scanner.

Step 2 — Verify tkinter works

python3 -c "import tkinter; print('tkinter OK:', tkinter.TkVersion)"
# Expected output: tkinter OK: 8.6

Step 3 — Run the scanner

python3 port_scanner.py

If tkinter is still not found after install

Your system may have multiple Python versions. Match the install to the exact version you are running:

# Check which Python you're running
python3 --version

# Install for that specific version (e.g. 3.13)
sudo apt-get install python3.13-tk

# Verify
python3 -c "import tkinter; print('tkinter OK:', tkinter.TkVersion)"

---

🖼️ UI Layout & Description

🔍 Tab 1 — Scanner (Main Interface)

┌─────────────────────────────────────────────────────────────────┐
│ ⬡  NETWORK PORT SCANNER                            [☀ Light]    │
├─────────────────────────────────────────────────────────────────┤
│ ⚙ Scan Configuration                                            │
│  Target: [192.168.1.1          ]  Profile: [Quick        ▼]    │
│  Start:  [1    ]  End: [1024  ]  Timeout: [0.3]  Threads: [300]│
│  ☑ Banner Grab   ☐ UDP Scan   ☐ Stealth (slow)   ☑ Ping Check  │
│  [▶ Start Scan]  [■ Stop]  [🗑 Clear]                           │
├─────────────────────────────────────────────────────────────────┤
│ Scanning… 512/1024  (50%)          Open: 3      Elapsed: 1.8s  │
│ [████████████████░░░░░░░░░░░░░░░░░░░░░░]                        │
├─────────────────────────────────────────────────────────────────┤
│ 📡 Open Ports                                                    │
│  Port  │ Proto │ Service    │ State   │ Banner / Version        │
│ ───────┼───────┼────────────┼─────────┼──────────────────────── │
│    22  │  TCP  │ SSH        │ ● Open  │ OpenSSH 8.9p1 Ubuntu   │
│    80  │  TCP  │ HTTP       │ ● Open  │ Apache/2.4.52          │
│   443  │  TCP  │ HTTPS      │ ● Open  │                        │
├─────────────────────────────────────────────────────────────────┤
│ 📝 Scan Log                                                      │
│  [14:32:01] Target : 192.168.1.1 (192.168.1.1)                 │
│  [14:32:02] [+] TCP    22  SSH           OpenSSH 8.9p1 Ubuntu  │
├─────────────────────────────────────────────────────────────────┤
│ Export:  [TXT]  [CSV]  [JSON]  [HTML]                           │
└─────────────────────────────────────────────────────────────────┘

Panel	Description
Configuration	All scan settings in one place. Choosing a profile auto-fills port range, timeout, and thread count
Status bar	Live progress %, open port count, elapsed timer — all update in real time
Progress bar	Fills as ports are probed
Treeview table	Each open port appears as a sortable row — click any column header to sort
Log console	Timestamped entries: 🟢 green = open port, 🔵 blue = info, 🟠 orange = warning
Export row	Four buttons save results instantly in your chosen format

---

📋 Tab 2 — History

┌─────────────────────────────────────────────────────────────────┐
│ 📋 Recent Scans                                                  │
│  Timestamp           │ Target          │ Range    │ Open │ Time │
│ ─────────────────────┼─────────────────┼──────────┼──────┼───── │
│  2025-01-15 14:32:01 │ 192.168.1.1     │ 1-1024   │  3   │ 3.2s │
│  2025-01-14 09:10:44 │ 10.0.0.1        │ 1-10000  │ 12   │ 18s  │
├─────────────────────────────────────────────────────────────────┤
│  [🗑 Clear History]   [↩ Load Selected]                          │
└─────────────────────────────────────────────────────────────────┘

Lists the last 50 scans. Select any row and click ↩ Load Selected to restore those results into the Scanner tab.

---

🔄 Tab 3 — Compare / Diff

┌─────────────────────────────────────────────────────────────────┐
│  Scan A: [2025-01-15 — 192.168.1.1 (3 open)              ▼]   │
│  Scan B: [2025-01-14 — 10.0.0.1   (12 open)              ▼]   │
│  [🔄 Compare]                                                    │
├─────────────────────────────────────────────────────────────────┤
│  Unchanged: 2 port(s)                                            │
│                                                                  │
│  [+] NEW in B (2):                        ← shown in green      │
│      Port 8080 (HTTP-Alt)                                        │
│      Port 3306 (MySQL)                                           │
│                                                                  │
│  [-] CLOSED in B (1):                     ← shown in red        │
│      Port 443 (HTTPS)                                            │
└─────────────────────────────────────────────────────────────────┘

Dropdowns are populated from scan history. Newly opened ports appear in green, closed ports in red.

---

🖥️ Usage — GUI Mode