A professional, modular network scanner for pentesters and security auditors.
Built in Python 3.10+, NetScan Pro provides host discovery, TCP port scanning, service/banner detection, risk scoring, and four output formats — all from a clean CLI.
⚠️ Authorised use only. Scanning networks or systems without explicit written permission is illegal. This tool is for authorised security assessments, CTF challenges, home labs, and educational purposes only.
| Category | Capabilities |
|---|---|
| Host Discovery | ICMP ping sweep · TCP fallback · ARP-less · Reverse DNS · TTL OS fingerprinting |
| Port Scanning | TCP connect · Common ports (80+) · Custom ranges · Full 1-65535 · Top-N |
| Service Detection | Banner grabbing · Protocol fingerprinting · TLS wrapping · Version extraction |
| Concurrency | ThreadPoolExecutor · Configurable thread count · Per-phase pools · Rate limiting |
| Output | Terminal (Rich) · JSON · CSV · Self-contained HTML dashboard |
| Risk Scoring | 0-100 per host · Low/Medium/High/Critical bands · Cleartext protocol penalties |
| CLI | argparse · Help menu · Custom scan profiles |
| Logging | Rotating file log · Coloured console · DEBUG/INFO levels |
# Install
git clone https://github.com/youruser/netscan-pro.git
cd netscan-pro
pip install -r requirements.txt
# Basic scan
python main.py 192.168.1.0/24
# Specific ports + all output formats
python main.py 10.0.0.1-20 --ports 22,80,443,3306 --output terminal json html csv
# Fast scan of top 20 ports, 200 threads
python main.py 192.168.1.0/24 --top-ports 20 --threads 200
# Full port range on single host
python main.py 10.0.0.1 --full-range --threads 300 --timeout 0.5
# No ping sweep (treat all as live), no banners
python main.py 10.0.0.1 --no-ping --no-banner --output json- Python 3.10 or higher
- pip
pip install -r requirements.txtpip install -e .
netscan --helpusage: netscan [-h] [-p PORTS] [--top-ports N] [--full-range] [--no-common]
[--no-ping] [--no-banner] [-T N] [--timeout SECS]
[-o FORMAT [FORMAT ...]] [--output-dir DIR] [-v] [--version]
TARGET [TARGET ...]
Target formats:
192.168.1.1 Single IP
192.168.1.0/24 CIDR subnet
192.168.1.1-50 Dash range (last octet)
scanme.nmap.org Hostname (resolved to IP)
Port options:
-p, --ports PORTS Comma-separated ports or ranges: 22,80,443 or 1-1024
--top-ports N Scan the top N most common ports
--full-range Scan all 65535 ports
--no-common Disable built-in common port list
Scan behaviour:
--no-ping Skip host discovery (treat all as live)
--no-banner Skip banner grabbing / service detection
-T, --threads N Concurrent threads (default: 100, max: 500)
--timeout SECS Per-probe timeout (default: 1.0)
Output:
-o, --output terminal json csv html (can specify multiple)
--output-dir DIR Directory for file reports (default: reports/)
Misc:
-v, --verbose Enable DEBUG-level logging
--version Show version and exit
Rich-formatted tables with colour-coded risk bands printed directly to stdout.
{
"scan_id": "A3F1B2C4",
"tool_name": "NetScan Pro",
"elapsed_seconds": 4.27,
"summary": {
"live_hosts": 3,
"total_open_ports": 12,
"risk_band_counts": {"Critical": 1, "High": 1, "Medium": 1, "Low": 0}
},
"hosts": [
{
"ip": "192.168.1.1",
"hostname": "router.home",
"os_hint": "Linux / macOS / FreeBSD",
"risk_score": 55,
"risk_band": "High",
"open_ports": [
{"port": 22, "service": "SSH", "banner": "SSH-2.0-OpenSSH_8.9"},
{"port": 80, "service": "HTTP", "banner": "Apache/2.4.51"}
]
}
]
}Self-contained single-file HTML with:
- Stat cards (hosts, open ports, risk counts)
- Risk band donut chart
- Attack surface bar chart (open ports per host)
- OS breakdown chart
- Top services table
- Per-host collapsible detail with port tables
One row per open port — import directly into Excel / Google Sheets for reporting.
netscan-pro/
├── main.py # CLI entry point (argparse → ScanConfig)
├── scanner/
│ ├── engine.py # Orchestrates all phases in order
│ ├── aggregator.py # Merges results, computes risk scores
│ ├── config.py # Constants: ports, timeouts, risk weights
│ ├── logger.py # Two-handler logging (Rich + rotating file)
│ └── exceptions.py # Typed exception hierarchy
├── modules/
│ ├── host_discovery.py # Ping sweep, TCP fallback, DNS, TTL hints
│ ├── port_scanner.py # TCP connect scan, port list builder
│ ├── service_detector.py # Banner grabbing, protocol fingerprinting
│ └── concurrency.py # TaskRunner, RateLimiter, chunk_list
├── reports/
│ ├── base_reporter.py # Abstract base class
│ ├── json_reporter.py
│ ├── csv_reporter.py
│ ├── terminal_reporter.py
│ └── html_reporter.py
└── tests/ # 238 unit tests, zero network calls
Scan pipeline (engine.py):
parse_targets → ping_sweep → build_port_list → scan_multiple_hosts → enrich_all → Aggregator.build
Each live host receives a 0–100 risk score:
score = Σ PORT_RISK_WEIGHTS[port] # per open port
+ 15 per cleartext service # FTP, Telnet, SMTP, HTTP…
+ 10 if >10 open ports
+ 20 if >20 open ports
(capped at 100)
| Band | Score | Example |
|---|---|---|
| 🟢 Low | 0–24 | Only HTTPS open |
| 🟡 Medium | 25–49 | SSH + HTTP |
| 🔴 High | 50–74 | FTP + RDP + MySQL |
| 🔴 Critical | 75–100 | Docker daemon + Telnet + SMB |
# All 238 tests
pytest tests/ -v
# With coverage report
pytest tests/ --cov=scanner --cov=modules --cov=reports --cov-report=term-missing
# Single module
pytest tests/test_port_scanner.py -vTests use unittest.mock — zero real network calls are made.
Scan logs are written to logs/netscan.log (5 MB rotating, 5 backups):
2024-01-15 14:32:01 | INFO | netscan.scanner.engine | Targets resolved: 254 IPs
2024-01-15 14:32:01 | INFO | netscan.modules.host_discovery | Starting ping sweep: 254 hosts
2024-01-15 14:32:05 | INFO | netscan.modules.host_discovery | Ping sweep complete: 8/254 hosts up in 3.82s
2024-01-15 14:32:09 | INFO | netscan.scanner.engine | Scan complete id=A3F1B2C4 elapsed=8.14s
- UDP scanning — ICMP port-unreachable detection for DNS (53), SNMP (161), NTP (123)
- SYN scan — raw socket half-open scan (faster, stealthier, requires root)
- IPv6 support — expand
parse_targetsto handle IPv6 CIDR notation - OS fingerprinting v2 — TCP/IP stack fingerprinting (window size, TTL, options) à la Nmap
- CVE lookup — match detected service versions against NVD API for known CVEs
- Async engine —
asyncio+asyncio.open_connectionfor 10× throughput on large subnets - Plugin system — drop-in scanner plugins (e.g. Shodan enrichment, SSL cert analysis)
- Web UI — Flask dashboard for real-time scan monitoring
- Scheduled scans — cron-style repeated scanning with diff reports ("what changed?")
- Network topology map — D3.js force graph of discovered hosts and open services
- Evasion mode — randomised port order, jitter between probes, decoy source IPs
- Credential testing — default credentials check for SSH/FTP/Telnet (opt-in, authorised only)
- TLS analysis — cipher suite enumeration, cert expiry, HSTS / HPKP headers
- SMB enumeration — share listing, null session checks (Eternal-Blue surface)
- Kubernetes / cloud probes — metadata API detection (169.254.169.254), k8s API checks
This tool is provided for educational, research, and authorised security testing purposes only.
- Always obtain written permission before scanning any system you do not own.
- Unauthorised port scanning may violate computer misuse laws in your jurisdiction.
- The author accepts no liability for misuse of this software.
MIT License — see LICENSE for details.