NetProbe

Multi-Threaded Network Port Scanner with service detection, banner grabbing, and vulnerability flagging.

---

Table of Contents

• Features
• Prerequisites
• Installation
• How to Find Your Target IP
• Quick Start (Beginner)
• Understanding the Command Structure
• Basic Commands
• Intermediate Commands
• Advanced Commands
• Output & Report Commands
• Performance Tuning
• Debugging & Verbose Mode
• Real-World Scan Recipes
• CLI Reference
• Port Specification Formats
• Target Specification Formats
• Running Tests
• Architecture & How It Works
• Troubleshooting
• Contributing
• License
• Legal Disclaimer

---

Features

• TCP Connect scan — full three-way handshake, works without root
• TCP SYN scan — half-open stealth scan (Linux + root required)
• UDP scan — protocol-specific payloads (DNS, SNMP, NTP, DHCP)
• Multi-threaded — up to 5 000 concurrent threads via ThreadPoolExecutor
• Service detection — 200+ port-to-service mappings
• Banner grabbing — protocol-aware (HTTP/S, SSH, FTP, SMTP, MySQL, Redis, PostgreSQL, VNC)
• Vulnerability detection — 34+ CVE patterns, category-based risk flags
• Multi-format reports — coloured console, JSON, CSV, plain-text
• CIDR / range / hostname — flexible target specification
• Graceful interruption — Ctrl+C shows partial results
• Progress bar — real-time ETA and completion percentage
• macOS & Linux compatible (SYN scan Linux-only)

---

Prerequisites

• Python 3.8+ — check your version:

  python3 --version
  

• pip3 — Python package manager (usually comes with Python)
• macOS or Linux — the tool works on both platforms (SYN scan is Linux-only and requires root)

---

Installation

Step 1: Clone the project

git clone https://github.com/thesatyam161/netprobe.git
cd netprobe

Step 2: Install dependencies

pip3 install -r requirements.txt

This installs: colorama, pytest, and pytest-cov.

(Optional) Install as a system-wide package

pip3 install .

After this you can run netprobe from anywhere instead of python3 main.py.

---

How to Find Your Target IP

New to networking? Before you can scan a device, you need to know its IP address. Here's how to find it.

Find Your Router's IP (Gateway)

macOS:

route -n get default | grep gateway

Linux:

ip route | grep default

Tip: Most home routers use 192.168.1.1 or 192.168.0.1.

Find Your Own Device's IP (Local/Private IP)

macOS:

ipconfig getifaddr en0

Linux:

hostname -I

Find Other Devices on Your Network

arp -a

This lists all devices connected to your local network along with their IP addresses.

Find a Website's IP Address

nslookup example.com

Or use ping:

ping -c 1 example.com

Note: You can also use hostnames directly — NetProbe will resolve them automatically:

python3 main.py --target example.com -p 80,443

Scan Yourself (Always Works)

If you just want to try NetProbe immediately, use localhost:

python3 main.py --target 127.0.0.1

127.0.0.1 refers to your own machine and is always safe to scan.

---

Quick Start (Beginner)

First time? Follow these steps to run your first scan.

Step 1: Open your terminal

Step 2: Navigate to the NetProbe directory

cd netprobe

Step 3: Run your first scan on localhost

python3 main.py --target 127.0.0.1

This will scan the top 100 most common ports on your own machine using the default settings.

Step 4: Try scanning specific ports

python3 main.py --target 127.0.0.1 -p 22,80,443,8080

Step 5: Try a scan with service detection

python3 main.py --target 127.0.0.1 -p 22,80,443 --service-detection

Congratulations! You've just completed your first network scan. Read on for more commands.

---

Understanding the Command Structure

Every NetProbe command follows this pattern:

python3 main.py --target <IP_ADDRESS> [OPTIONS]

| Part | Required? | Description | |------|-----------|-------------| | python3 main.py | ✅ Yes | Runs the NetProbe scanner | | --target <IP> | ✅ Yes | The device/host you want to scan (replace <IP> with any IP or hostname) | | -p <ports> | ❌ Optional | Which ports to scan (defaults to top 100) | | --threads <N> | ❌ Optional | Number of threads (defaults to 1000) | | --timeout <sec> | ❌ Optional | Connection timeout in seconds (defaults to 1.0) | | Other flags | ❌ Optional | See CLI Reference for all options |

Important: Replace <YOUR_IP> in all examples below with your actual target IP. See How to Find Your Target IP to find it.

---

Basic Commands

1. Scan Localhost (Your Own Machine)

python3 main.py --target 127.0.0.1

2. Scan Your Router

# Replace with your router's IP (usually 192.168.1.1 or 192.168.0.1)
python3 main.py --target <YOUR_ROUTER_IP>

3. Scan Specific Ports

python3 main.py --target <YOUR_IP> -p 22,80,443

4. Scan a Port Range

python3 main.py --target <YOUR_IP> -p 1-1024

5. Scan Top N Most Common Ports

# Scan top 20 most commonly open ports
python3 main.py --target <YOUR_IP> --top-ports 20

# Scan top 100 (default — same as not specifying -p at all)
python3 main.py --target <YOUR_IP>

6. Scan Specific Ports List

python3 main.py --target <YOUR_IP> -p 22,80,443,3306,8080

7. Scan a Website by Hostname

python3 main.py --target example.com -p 80,443

8. Show Help

python3 main.py --help

9. Show Version

python3 main.py --version

---

Intermediate Commands

10. Mixed Port Specification

# Combine individual ports and ranges
python3 main.py --target <YOUR_IP> -p 22,80,443,3000-3100,8000-9000

11. Scan All 65535 Ports

python3 main.py --target <YOUR_IP> -p 1-65535 --threads 5000 --timeout 0.3

12. Enable Service Detection

Identifies what software is running on each open port:

python3 main.py --target <YOUR_IP> -p 22,80,443,3306,6379 --service-detection
# or using the short flag:
python3 main.py --target <YOUR_IP> -p 22,80,443 -sV

13. Skip Banner Grabbing (Faster Scan)

By default, NetProbe grabs banners from open ports. To disable and scan faster:

python3 main.py --target <YOUR_IP> -p 1-1024 --no-banner

14. Scan Multiple Targets (Comma-Separated)

python3 main.py --target 192.168.1.1,192.168.1.2,10.0.0.1 -p 80,443

15. Scan a CIDR Subnet (Multiple Hosts)

# Scan all 254 hosts in a /24 subnet
python3 main.py --target 192.168.1.0/24 --top-ports 20 --threads 2000

16. Scan an IP Range

# Scan 192.168.1.100 through 192.168.1.110
python3 main.py --target 192.168.1.100-110 -p 22,80,443

17. Scan Targets from a File

Create a file called targets.txt with one target per line:

# targets.txt — comments and blank lines are ignored
192.168.1.1
192.168.1.2
10.0.0.0/24
example.com

Then run:

python3 main.py --input-list targets.txt --top-ports 50
# or using the short flag:
python3 main.py -iL targets.txt -p 22,80,443

---

Advanced Commands

18. TCP Connect Scan (Default, Explicit)

Full three-way TCP handshake — works on macOS and Linux, no root required:

python3 main.py --target <YOUR_IP> -p 1-1024 -sT

19. SYN Scan (Linux Only, Requires Root)

Half-open stealth scan — doesn't complete the TCP handshake (faster, stealthier):

sudo python3 main.py --target <YOUR_IP> -p 1-1024 -sS

⚠️ Note: SYN scan only works on Linux with root privileges. On macOS, use TCP Connect scan (-sT) instead.

20. UDP Scan

Detects open UDP services (DNS, SNMP, NTP, DHCP, etc.):

python3 main.py --target <YOUR_IP> -p 53,123,161,67 -sU

21. Rate Limiting (Stealth Mode)

# Limit to 100 connections per second (stealthy, avoids detection)
python3 main.py --target <YOUR_IP> -p 1-1024 --rate-limit 100

22. Adjust Retries

# No retries (fastest, may miss filtered ports)
python3 main.py --target <YOUR_IP> -p 1-1024 --retries 0

# Extra retries for unreliable networks
python3 main.py --target <YOUR_IP> -p 1-1024 --retries 3

23. Full Reconnaissance Scan (Everything Combined)

python3 main.py --target <YOUR_IP> \
  -p 1-65535 \
  --service-detection \
  --threads 3000 \
  --timeout 0.5 \
  --output-json full_scan.json \
  --output-txt full_scan.txt

---

Output & Report Commands

24. Save Results to JSON

python3 main.py --target <YOUR_IP> -p 1-1024 --output-json scan_results.json
# or short:
python3 main.py --target <YOUR_IP> -p 1-1024 -oJ scan_results.json

25. Save Results to CSV

python3 main.py --target <YOUR_IP> -p 80,443 --output-csv results.csv
# or short:
python3 main.py --target <YOUR_IP> -p 80,443 -oC results.csv

26. Save Results to Plain Text

python3 main.py --target <YOUR_IP> -p 1-1024 --output-txt report.txt
# or short:
python3 main.py --target <YOUR_IP> -p 1-102