Skip to content

USAGE.md

Latest commit

 

History

History
396 lines (276 loc) · 8.27 KB

USAGE.md

File metadata and controls

396 lines (276 loc) · 8.27 KB

NetScan — Usage Guide

Prerequisites

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

Installation

Option 1: Install system-wide (recommended)

# Clone the repo
git clone https://github.com/Evil-Null/netscan.git
cd netscan

# Install to ~/.cargo/bin/
cargo install --path .

# Add to PATH (if not already)
# For bash:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
netscan --version

Now netscan works from any directory.

Enable sudo access (required for SYN, UDP, FIN and other raw socket scans):

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

Without this, sudo netscan will say "command not found" because sudo uses a different PATH.

Option 2: Build without installing

cargo build --release
./target/release/netscan --version

Binary location: ./target/release/netscan (must run from project directory or use full path).

Uninstall

cargo uninstall netscan

Quick Start

# Scan a single host (top 1000 ports)
netscan -sT 192.168.1.1

# Scan specific ports
netscan -sT 192.168.1.1 -p 22,80,443

# Fast scan (top 100 ports)
netscan -sT 192.168.1.1 -F

# Scan entire subnet
netscan -sT 192.168.1.0/24 -p 22,80,443

Scan Types

Flag Type Root? Description
-sT TCP Connect No Full TCP handshake — reliable, detectable
-sS TCP SYN Yes Half-open — fast, stealthy
-sU UDP Yes UDP port scan
-sF TCP FIN Yes FIN flag only — evades some firewalls
-sX TCP XMAS Yes FIN+PSH+URG — evades some firewalls
-sN TCP NULL Yes No flags — evades some firewalls
-sA TCP ACK Yes Firewall rule mapping (unfiltered vs filtered)
-sO Protocol Yes IP protocol scan (TCP, UDP, ICMP, etc.)
--ping-only ICMP Ping Yes Host discovery only, no port scan
--arp ARP Yes LAN host discovery (Layer 2)
--zombie HOST Idle Yes Stealth scan via zombie host

Nmap-style shortcuts

netscan -sS 192.168.1.1       # same as: netscan -s S 192.168.1.1
netscan -sV 192.168.1.1       # same as: netscan --service-version
netscan -sn 192.168.1.0/24    # same as: netscan --ping-only
netscan -PR 192.168.1.0/24    # same as: netscan --arp

Multiple scan types

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

Target Specification

# Single IP
netscan -sT 192.168.1.1

# Multiple IPs
netscan -sT 192.168.1.1 192.168.1.254 10.0.0.1

# CIDR range
netscan -sT 192.168.1.0/24

# Hostname
netscan -sT example.com

# From file (one target per line)
netscan -sT -i targets.txt
netscan -sT -iLtargets.txt     # Nmap-style

# Exclude targets
netscan -sT 192.168.1.0/24 --exclude 192.168.1.1
netscan -sT 192.168.1.0/24 --exclude-file skip.txt

Port Specification

# Specific ports
-p 22,80,443

# Port range
-p 1-1024

# Mixed
-p 22,80-90,443,8080-8090

# All ports (1-65535)
-p-
-p -

# Top N common ports
--top-ports 20
--top-ports 100

# Fast mode (top 100)
-F

Service & OS Detection

# Service/version detection on open ports
netscan -sT 192.168.1.1 -F --service-version

# OS fingerprinting
netscan -sT 192.168.1.1 -F -O

# Aggressive mode (service + OS + traceroute)
netscan -sT 192.168.1.1 -F -A

# Adjust probe intensity (0=light, 9=deep, default=7)
netscan -sT 192.168.1.1 -F --service-version --version-intensity 9

# Traceroute
netscan -sT 192.168.1.1 --traceroute

Output Formats

Terminal (always shown)

netscan -sT 192.168.1.1 -F

Save to file

# JSON
netscan -sT 192.168.1.1 -F --output-json results.json

# XML (Nmap-compatible)
netscan -sT 192.168.1.1 -F --output-xml results.xml

# CSV (spreadsheet-friendly)
netscan -sT 192.168.1.1 -F --output-csv results.csv

# HTML (self-contained report)
netscan -sT 192.168.1.1 -F --output-html report.html

# Markdown
netscan -sT 192.168.1.1 -F --output-markdown report.md

# Greppable (Nmap grepable format)
netscan -sT 192.168.1.1 -F --output-grep results.gnmap

# Normal text
netscan -sT 192.168.1.1 -F --output-normal results.txt

All formats at once

netscan -sT 192.168.1.1 -F --output-all scan_results
# Creates: scan_results.txt, .json, .xml, .csv, .html, .md, .gnmap

Nmap-style short flags

-oJresults.json     # --output-json results.json
-oXresults.xml      # --output-xml results.xml
-oCresults.csv      # --output-csv results.csv
-oHreport.html      # --output-html report.html
-oMreport.md        # --output-markdown report.md
-oGresults.gnmap    # --output-grep results.gnmap
-oNresults.txt      # --output-normal results.txt
-oAscan             # --output-all scan

Timing & Performance

Timing Templates

Flag Name Delay Max Rate Timeout Retries Use Case
-T0 Paranoid 5 min 1 pps 15 min 10 IDS evasion
-T1 Sneaky 15 sec 10 pps 15 min 10 IDS evasion
-T2 Polite 400 ms 100 pps 10 min 10 Low bandwidth
-T3 Normal none 1,000 pps 5 min 6 Default
-T4 Aggressive none 10,000 pps 2 min 3 Fast LAN scan
-T5 Insane none 100,000 pps 30 sec 2 Localhost/CTF 
netscan -sT 192.168.1.0/24 -F -T4       # Fast LAN scan
netscan -sT target.com -p 1-1024 -T1     # Slow and stealthy

Fine-tuning

# Rate control
--min-rate 500        # Minimum 500 packets/sec
--max-rate 5000       # Maximum 5000 packets/sec

# Timeouts
--host-timeout 60000  # 60 second max per host
--scan-delay 100      # 100ms between probes

# Retries
--max-retries 3       # Max 3 retransmissions per probe

Firewall/IDS Evasion

# Fragment packets (-f)
sudo netscan -sS 10.0.0.1 -p 80 -f

# Decoy source addresses
sudo netscan -sS 10.0.0.1 -p 80 -D 10.0.0.5,10.0.0.6,ME,10.0.0.7
# ME = your real IP position among decoys

# Custom source port
sudo netscan -sS 10.0.0.1 -p 80 --source-port 53

# Custom TTL
sudo netscan -sS 10.0.0.1 -p 80 --ttl 128

# Append random data to packets
sudo netscan -sS 10.0.0.1 -p 80 --data-length 64

# Randomize host scan order
netscan -sT 192.168.1.0/24 -F --randomize-hosts

# Spoof MAC address
sudo netscan -sS 10.0.0.1 -p 80 --spoof-mac AA:BB:CC:DD:EE:FF

Network Options

# Use specific network interface
netscan -sT 192.168.1.1 -e eth0

# Custom DNS servers
netscan -sT example.com --dns-servers 8.8.8.8,1.1.1.1

Verbosity & Output Control

-v       # Show INFO logs (scan progress)
-vv      # Show DEBUG logs (config details, per-packet info)
-vvv     # Show TRACE logs (everything)
-q       # Quiet mode — minimal terminal output

Real-World Examples

1. Quick localhost audit

netscan -sT 127.0.0.1 -F

2. LAN device discovery

netscan -sT 192.168.1.0/24 --top-ports 20 -T4

3. Full scan with service detection + HTML report

netscan -sT 192.168.1.1 -p- --service-version --output-html report.html -v

4. Aggressive audit of web server

netscan -sT example.com -p 80,443,8080,8443 -A --output-json web_audit.json

5. Stealthy scan (SYN + slow timing)

sudo netscan -sS target.com -p 1-1024 -T1 -f --randomize-hosts

6. Subnet scan with all output formats

netscan -sT 10.0.0.0/24 -F -T4 --output-all network_scan -v

7. Compare open ports — CSV for spreadsheet

netscan -sT 192.168.1.0/24 -F --output-csv ports.csv

8. Firewall mapping with ACK scan

sudo netscan -sA 10.0.0.1 -p 1-1024
# unfiltered = firewall allows through, filtered = firewall blocks

9. UDP service discovery

sudo netscan -sU 192.168.1.1 -p 53,67,68,123,161,500

10. Multiple scan types combined

sudo netscan -sS -sU 192.168.1.1 -p 22,53,80,443 --service-version -v

Exit Behavior

  • Ctrl+C: Graceful shutdown — stops sending probes, collects partial results, outputs what it has
  • All output files are written before exit
  • Exit code 0 on success, non-zero on error