🔍 NetSleuth — CLI Network Port Scanner

A minimalist, high-performance, multi-threaded TCP port scanner built for security professionals and portfolios.

---

⚠️ Educational Purposes Only — Only scan targets you own or have explicit written permission to test.

---

✨ Features

Feature	Detail
Concurrent scanning	ThreadPoolExecutor — up to N threads in parallel
Service detection	Identifies probable service names via socket.getservbyport()
Flexible port input	Single (80), list (80,443), or range (1-1024)
DNS resolution	Resolves hostnames to IP before scan; shown to user up-front
JSON export	Persist full reports with -o results.json
Rich terminal UI	Coloured output, live progress bar, animated spinner
Graceful shutdown	Ctrl+C stops threads cleanly and prints partial results
Top-100 default	Scans the 100 most common ports when no range is given
Google-style docstrings	Full inline documentation on every class and method
Type hints	PEP 604-compliant annotations throughout the codebase

---

🗂 Project Structure

netsleuth/
├── scanner.py        # All source code — single-file, self-contained
├── requirements.txt  # Third-party dependencies
└── README.md         # This file

---

🚀 Quick Start

1. Clone & install dependencies

git clone https://github.com/defacesh/NetSleuth.git
cd netsleuth
pip install -r requirements.txt

2. Run your first scan

python scanner.py -t scanme.nmap.org

---

📖 Usage

usage: netsleuth [-h] -t HOST [-p PORTS] [--timeout SEC] [--threads N] [-o FILE]

Arguments

Flag	Long form	Default	Description
-t	--target	(required)	Target hostname or IP address
-p	--ports	Top-100	Ports: 80, 80,443, or 1-1024
	--timeout	1.0	Socket connection timeout (seconds)
	--threads	50	Number of concurrent threads
-o	--output	(none)	Save results to a JSON file
-h	--help		Show help message

---

💡 Example Commands

# Scan top-100 common ports on a host (default mode)
python scanner.py -t scanme.nmap.org

# Scan a well-known port range with 100 threads
python scanner.py -t 192.168.1.1 -p 1-1024 --threads 100

# Scan specific ports with a custom timeout
python scanner.py -t 10.0.0.5 -p 22,80,443,3306,5432 --timeout 0.5

# Scan and export results to JSON
python scanner.py -t example.com -p 1-65535 --threads 200 -o report.json

# Scan localhost for development / testing
python scanner.py -t 127.0.0.1 -p 1-9999

---

📊 Sample Output

 _   _      _   ____  _            _   _
| \ | | ___| |_/ ___|| | ___ _   _| |_| |__
|  \| |/ _ \ __\___ \| |/ _ \ | | | __| '_ \
| |\  |  __/ |_ ___) | |  __/ |_| | |_| | | |
|_| \_|\___|\__|____/|_|\___|\__,_|\__|_| |_|

╭─────────────────────────────────────────────────╮
│   ⚠  Educational Purposes Only — Authorized Scanning Only  ⚠   │
╰─────────────────────────────────────────────────╯

Resolving scanme.nmap.org …
  ✓ Resolved → 45.33.32.156

╭─ Scan Configuration ──────────────────────────╮
│  Target       scanme.nmap.org                  │
│  Resolved IP  45.33.32.156                     │
│  Ports        21–60010  (100 total)            │
╰────────────────────────────────────────────────╯

╭─────────────── Open Ports on 45.33.32.156 ────────────────╮
│  PORT  │ PROTOCOL │    SERVICE     │   STATUS   │
├────────┼──────────┼────────────────┼────────────┤
│    22  │   TCP    │      SSH       │    OPEN    │
│    80  │   TCP    │      HTTP      │    OPEN    │
│  9929  │   TCP    │    NPING-HOST  │    OPEN    │
│ 31337  │   TCP    │    ELITE       │    OPEN    │
╰────────────────────────────────────────────────────────────╯

╭─ ✓ Scan completed ──────────────────────────╮
│  Ports Scanned     100                       │
│  Open Ports Found  4                         │
│  Duration          2.847s                    │
╰──────────────────────────────────────────────╯

---

📁 JSON Report Format

When -o report.json is specified, NetSleuth writes a structured report:

{
  "target": "scanme.nmap.org",
  "resolved_ip": "45.33.32.156",
  "start_time": "2024-11-20T14:32:01.123456",
  "end_time": "2024-11-20T14:32:03.970234",
  "duration_seconds": 2.847,
  "total_ports_scanned": 100,
  "open_ports": [
    { "port": 22, "is_open": true, "service": "ssh", "banner": "" },
    { "port": 80, "is_open": true, "service": "http", "banner": "" }
  ]
}

---

🏗 Architecture

NetSleuth is structured around a single, well-encapsulated class with clear separation of concerns:

main()
 ├── parse_arguments()         → argparse setup
 ├── PortScanner
 │    ├── resolve_target()     → DNS → IP
 │    ├── scan_port(port)      → single TCP probe + service lookup
 │    ├── run_scan(ports)      → ThreadPoolExecutor orchestration
 │    ├── build_report()       → aggregate ScanReport dataclass
 │    └── save_report()        → JSON serialisation
 └── Display helpers
      ├── print_banner()
      ├── print_scan_header()
      ├── print_results_table()
      └── print_scan_footer()

Design decisions

• dataclasses – ScanResult and ScanReport are lightweight, type-safe value objects with zero boilerplate.
• concurrent.futures.ThreadPoolExecutor – Network I/O is blocking and thread-bound; threads outperform asyncio for pure-socket workloads at this scale without adding framework complexity.
• rich – Provides production-quality terminal UI (progress bars, coloured tables, panels) with a single dependency.
• Single-file layout – Maximises portability and reviewability for interview contexts without sacrificing structure.

---

🛡 Ethical & Legal Notice

This tool is intended solely for authorised security assessments, CTF challenges, and educational use.

• ✅ Scan your own servers and VMs
• ✅ Scan explicitly authorised lab environments (TryHackMe, HackTheBox, etc.)
• ❌ Never scan third-party hosts without explicit written consent
• ❌ Unauthorised port scanning may violate the Computer Fraud and Abuse Act (CFAA) and equivalent laws in your jurisdiction

---

📜 License

MIT © 2026 — See LICENSE for details.