NetScan

A professional-grade, async network scanner written in Rust with an Nmap-compatible CLI. Designed for security auditors, penetration testers, and network administrators who need fast, flexible host and port discovery on Linux.

---

Table of Contents

• Features
• Architecture
• Installation
• Quick Start
• Scan Types
• Output Formats
• Development
• Documentation
• License

---

Features

Capability	Status	Notes
TCP Connect scan (-sT)	✅ Ready	No root required; full 3-way handshake
TCP SYN scan (-sS)	✅ Ready	Half-open; requires root or CAP_NET_RAW
UDP scan (-sU)	✅ Ready	Requires root or CAP_NET_RAW
FIN / XMAS / NULL / ACK scans	✅ Ready	Raw socket stealth scans
ICMP Ping (-sn)	✅ Ready	Host discovery
ARP discovery (-PR)	✅ Ready	Layer-2 LAN host discovery
Service detection (-sV)	✅ Ready	Banner grabbing & version probes
OS fingerprinting (-O)	🟡 Partial	Passive matching when data is present
7 output formats	✅ Ready	JSON, XML, CSV, HTML, Markdown, greppable, plain text
Timing templates (-T0..-T5)	✅ Ready	Paranoid through Insane
Rate limiting	✅ Ready	--min-rate, --max-rate, --scan-delay
Packet fragmentation (-f)	🟡 Parsed	CLI accepted; not yet wired into scanners
Decoys (-D)	🟡 Parsed	CLI accepted; not yet wired into scanners
Idle / zombie scan	❌ Not impl	Blocked at config time with clear error
IP protocol scan (-sO)	❌ Not impl	Blocked at config time with clear error

• Flexible targeting — single IPs, CIDR ranges, hostnames, and target files with exclusions
• Nmap-compatible CLI — familiar flags like -sS, -sT, -sV, -O, -A, -T4, -oJ, -oX
• Async architecture — built on Tokio for high-throughput concurrent scanning
• Graceful shutdown — Ctrl+C cancels in-flight scans and preserves partial results

---

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   CLI Args  │────▶│ Config Build│────▶│   ScanEngine    │
│  (clap)     │     │  (validate) │     │  (orchestrator) │
└─────────────┘     └─────────────┘     └────────┬────────┘
                                                  │
          ┌────────────┬────────────┬─────────────┼────────────┐
          ▼            ▼            ▼             ▼            ▼
   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
   │ TCP Syn  │ │TCP Stealth│ │TCP Connect│ │  UDP     │ │  ICMP    │
   │ Scanner  │ │ Scanner  │ │ Scanner  │ │ Scanner  │ │ Scanner  │
   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
        │            │            │            │            │
        └────────────┴────────────┴────────────┴────────────┘
                                  │
                          ┌───────▼────────┐
                          │ Result Collector│
                          └───────┬────────┘
                                  │
          ┌────────────┬──────────┼──────────┬────────────┐
          ▼            ▼          ▼          ▼            ▼
   ┌──────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────┐
   │   JSON   │ │   XML    │ │  CSV   │ │  HTML  │ │ Terminal │
   │  Output  │ │  Output  │ │ Output │ │ Output │ │  Output  │
   └──────────┘ └──────────┘ └────────┘ └────────┘ └──────────┘

Key modules:

• config/ — CLI parsing (clap), argument preprocessing, scan configuration building, timing templates
• scanner/ — Scan engine that dispatches to individual scanners (TCP, UDP, ICMP, ARP); rate limiter and RST suppression
• packet/ — Raw socket abstraction, packet builders (Ethernet/IP/TCP/UDP/ICMP), checksum computation
• network/ — DNS resolution, target parsing (CIDR, ranges, files), interface enumeration
• probe/ — Service banner grabbing, version detection probes, OS fingerprinting, SSL/TLS inspection
• output/ — Pluggable formatters: JSON, XML, CSV, HTML, Markdown, greppable, terminal
• evasion/ — Timing jitter, host randomization, decoy/fragmentation stubs
• results/ — Structured scan results: hosts, ports, services, warnings

---

Installation

Prerequisites

• Rust 1.70+: https://rustup.rs
• Linux (tested on Ubuntu / ZorinOS)
• Root / sudo for raw socket scans (SYN, UDP, FIN, etc.). TCP Connect (-sT) works without root.

Install from source

git clone https://github.com/null0xxx/netscan.git
cd netscan
cargo install --path .

Enable sudo access for raw-socket scans:

sudo ln -s ~/.cargo/bin/netscan /usr/local/bin/netscan

Verify:

netscan --version

---

Quick Start

# Scan top 1000 ports on a host (no root needed)
netscan -sT 192.168.1.1

# Fast scan (top 100 ports) with service detection
netscan -sT 192.168.1.1 -F --service-version

# SYN scan a subnet (requires root)
sudo netscan -sS 192.168.1.0/24 -p 22,80,443 -T4

# Full audit with HTML report
netscan -sT example.com -p- -A --output-html report.html

# Multiple output formats at once
netscan -sT 192.168.1.1 -F --output-all scan_results

# Read targets from file, exclude a host
netscan -sT -i targets.txt --exclude 192.168.1.10

---

Scan Types

Flag	Type	Root Required	Description
-sT	TCP Connect	No	Full 3-way handshake — reliable, detectable
-sS	TCP SYN	Yes	Half-open scan — fast and stealthy
-sU	UDP	Yes	UDP port scan
-sF	TCP FIN	Yes	FIN flag only — evades some firewalls
-sX	TCP XMAS	Yes	FIN+PSH+URG flags
-sN	TCP NULL	Yes	No flags set
-sA	TCP ACK	Yes	Firewall rule mapping (unfiltered vs filtered)
-sn	ICMP Ping	Yes	Host discovery only
-PR	ARP	Yes	Layer-2 LAN host discovery

Combine multiple scan types:

netscan -sT -sU 192.168.1.1 -p 22,53,80

---

Output Formats

Flag	Format	File Extension
--output-json	JSON	.json
--output-xml	XML (Nmap-compatible)	.xml
--output-csv	CSV	.csv
--output-html	HTML report	.html
--output-markdown	Markdown	.md
--output-grep	Greppable (Nmap .gnmap)	.gnmap
--output-normal	Plain text	.txt
--output-all	All of the above	multiple

Terminal output is shown by default unless --quiet (-q) is used.

---

Development

# Format check
cargo fmt --check

# Run all tests
cargo test

# Release build
cargo build --release

# Run with cargo
cargo run -- -sT 127.0.0.1 -p 22,80,443

---

Documentation

• USAGE.md — Complete CLI reference: all flags, timing templates, evasion options, and real-world examples
• RUNNING.md — Current support matrix, setup checklist, and development workflow

---

License

MIT