🔍 NetRecon — Python Network Port Scanner

A lightweight, threaded network reconnaissance tool built with pure Python.
Designed for cybersecurity students learning network security fundamentals.

---

📌 What This Tool Does

NetRecon scans a target IP address for open TCP ports, identifies the services running on them, grabs service banners, and generates professional reports in JSON, CSV, and TXT formats.

This is the foundation of real-world tools like Nmap.

---

⚡ Features

• Threaded scanning — scan 100+ ports simultaneously (100x faster than sequential)
• Banner grabbing — identifies service versions (e.g., OpenSSH 8.2p1)
• Port presets — top100, web, database, remote access
• Custom ranges — --ports 22,80,1000-2000
• 3 report formats — JSON, CSV, TXT saved to reports/
• Hostname support — automatically resolves domains to IPs
• Zero dependencies — uses Python standard library only

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/raza360ahmed/NetRecon.git
cd NetRecon

2. Install Test Dependencies (optional)

pip install -r requirements.txt

3. Run Your First Scan

# Scan top 100 common ports (safe public target)
python main.py scanme.nmap.org

# Scan only web ports
python main.py 192.168.1.1 --preset web

# Scan custom ports
python main.py 10.0.0.5 --ports 22,80,443,3306,3389

# Scan a range with faster threads
python main.py 192.168.1.1 --ports 1-1024 --threads 200

---

📖 Usage

usage: python main.py TARGET [OPTIONS]

positional arguments:
  target              IP address or hostname to scan

options:
  --ports   -p        Ports: "80" | "22,80,443" | "1-1024" | "22,8000-8100"
  --preset            Preset list: top100 | web | database | remote | all
  --threads -t        Concurrent threads (default: 100)
  --timeout           Seconds per port (default: 1.0)
  --output  -o        Report output directory (default: reports/)

Examples

Command	Description
python main.py 192.168.1.1	Scan top 100 ports
python main.py 192.168.1.1 --preset web	Web ports only
python main.py 192.168.1.1 --preset database	Database ports
python main.py 192.168.1.1 --ports 1-65535 --threads 500	Full scan
python main.py scanme.nmap.org --preset remote	Remote access ports

---

📁 Project Structure

NetRecon/
├── main.py              # CLI entry point — start here
├── requirements.txt     # Dependencies
├── README.md
├── .gitignore
│
├── src/                 # Core modules
│   ├── __init__.py
│   ├── scanner.py       # Port scanning + banner grabbing engine
│   ├── reporter.py      # JSON / CSV / TXT report generation
│   └── port_lists.py    # Port presets and range parser
│
├── tests/               # Unit tests
│   └── test_scanner.py
│
└── reports/             # Generated scan reports (auto-created)
    ├── scan_*.json
    ├── scan_*.csv
    └── scan_*.txt

---

📊 Sample Output

[*] Resolved scanme.nmap.org → 45.33.32.156
[*] Using default TOP_100 port list: 100 port(s)
[*] Starting scan on 45.33.32.156
[*] Scanning 100 ports with 100 threads...

  [OPEN] Port    22/tcp  ssh             SSH-2.0-OpenSSH_6.6.1p1
  [OPEN] Port    80/tcp  http            HTTP/1.1 200 OK
  [OPEN] Port  9929/tcp  unknown
  [OPEN] Port 31337/tcp  unknown

[*] Scan complete: 4 open port(s) found in 3.42s

[+] JSON report saved: reports/scan_45_33_32_156_20240615_143022.json
[+] CSV report saved:  reports/scan_45_33_32_156_20240615_143022.csv
[+] TXT report saved:  reports/scan_45_33_32_156_20240615_143022.txt

---

🔬 How It Works

User types: python main.py 192.168.1.1 --preset web
                    │
                    ▼
            main.py (CLI)
          Parse args → resolve IP → build port list
                    │
                    ▼
            scanner.py
          ThreadPool: 100 workers scan ports simultaneously
          Each worker: TCP connect() → open/closed
          If open: banner grab attempt
                    │
                    ▼
            reporter.py
          Save JSON + CSV + TXT to reports/

---

⚠️ Legal & Ethical Use

Only scan systems you own or have explicit written permission to test.

Unauthorized port scanning may violate:

• Computer Fraud and Abuse Act (CFAA) — USA
• Computer Misuse Act — UK
• IT Act 2000 — Pakistan/India

Safe targets for practice:

• scanme.nmap.org — Nmap's official scan-me server
• Your own home router (192.168.1.1)
• Your own VMs / home lab

---

🧪 Running Tests

pip install pytest
python -m pytest tests/ -v

---

🛠 Built With

Technology	Purpose
socket	TCP connections and DNS resolution
concurrent.futures	Thread pool management
argparse	CLI argument parsing
json, csv	Report file generation

---

👤 Author

Ahmed Raza
BS Digital Forensics & Cyber Security — Hamdard University
GitHub · LinkedIn

---

📄 License

MIT License — free to use, modify, and distribute with attribution.