1. Tool Introduction
Masscan, created by Robert Graham, is an asynchronous, stateless TCP port scanner designed for extreme speed. It uses its own custom TCP/IP stack and can transmit packets at rates limited only by the network hardware — its author has demonstrated scanning the entire IPv4 address space in under six minutes. Unlike Nmap, which maintains connection state, Masscan sends probes and asynchronously matches responses, allowing it to scale to very large target ranges. It supports Nmap-compatible output formats and syntax for target/port specification, making it easy to feed results into Nmap for deeper follow-up scanning.
2. Installation
sudo apt update
sudo apt install masscan -y
Verify:
masscan --version
Expected output:
Masscan version 1.3.2 ( https://github.com/robertdavidgraham/masscan )
Compiled: ...
3. Syntax
masscan [Options] {target specification} -p{port(s)}
4. Command-Line Options (Full Reference)
-p <ports>— Ports to scan (e.g.,-p80,443or-p0-65535)--rate <packets-per-second>— Set transmit rate (default 100)-e <interface>— Specify network interface--router-mac <mac>— Set destination MAC (gateway)--source-ip <ip>— Spoof/set source IP--source-port <port>— Set source port--adapter-ip <ip>— Send packets from this IP-oX <file>— Output in XML-oJ <file>— Output in JSON-oG <file>— Output in Nmap grepable format-oL <file>— Output in “list” format-oB <file>— Output in binary format--banners— Grab service banners (limited protocols: HTTP, FTP, SSH, etc.)--http-user-agent <string>— Set custom HTTP User-Agent for banner grabs--exclude <range>— Exclude an IP range--excludefile <file>— Exclude ranges from file--includefile <file>— Include ranges from file-c/--conf <file>— Read a configuration file--echo— Print configuration and exit--ping— Include ICMP echo probe in the scan--top-ports <n>— Scan the n most common ports--shard <a/b>— Distribute scan across multiple machines (shard a of b)--seed <num>— Set randomization seed for repeatable scans--retries <num>— Number of retransmissions--wait <secs>— Time to wait for responses after scan finishes--resume <file>— Resume from a paused scan--pcap <file>— Save raw packets to a pcap file--pcap-payload— Include full packet payload in pcap-sL— List scan only (no packets sent, just print targets)--interactive— Print output to screen in addition to any output file--append-output— Append instead of overwrite output file--open-only— Only show open ports in output--regress— Run regression tests--nmap— Print help mapping Masscan options to Nmap equivalents-iL <file>— Input target list from file (Nmap-compatible)--rotate <time>— Rotate output files periodically (e.g. for long scans)--rotate-dir <dir>— Directory to store rotated output files
5. Basic Usage
sudo masscan -p80,443 192.168.1.0/24 --rate 1000
Expected output:
Starting masscan 1.3.2 (http://bit.ly/14GZzcT)
-- forced options: -sS -Pn -n --randomize-hosts -v --send-eth
Initiating SYN Stealth Scan
Scanning 256 hosts [2 ports/host]
Discovered open port 80/tcp on 192.168.1.10
Discovered open port 443/tcp on 192.168.1.10
Discovered open port 80/tcp on 192.168.1.15
6. Practical Examples
Example 1 — Scan a single host across all ports
sudo masscan -p0-65535 10.10.10.5 --rate 10000
Discovered open port 22/tcp on 10.10.10.5
Discovered open port 80/tcp on 10.10.10.5
Discovered open port 3306/tcp on 10.10.10.5
Example 2 — Scan an entire /16 network for port 443
sudo masscan -p443 10.10.0.0/16 --rate 100000
Discovered open port 443/tcp on 10.10.5.12
Discovered open port 443/tcp on 10.10.9.201
Example 3 — Output results to JSON
sudo masscan -p22,80,443 192.168.1.0/24 --rate 5000 -oJ scan.json
[cat scan.json]
[
{ "ip": "192.168.1.10", "ports": [ {"port": 22, "proto": "tcp", "status": "open"} ] }
]
Example 4 — Grab HTTP/SSH banners
sudo masscan -p22,80 10.10.10.0/24 --banners --rate 2000
Discovered open port 22/tcp on 10.10.10.5
Banner on port 22/tcp on 10.10.10.5: [ssh] SSH-2.0-OpenSSH_8.9p1 Ubuntu
Example 5 — Exclude specific hosts from scan
sudo masscan -p1-1000 10.10.10.0/24 --excludefile exclude.txt --rate 3000
Discovered open port 21/tcp on 10.10.10.3
Discovered open port 80/tcp on 10.10.10.9
Example 6 — Resume an interrupted scan
sudo masscan --resume paused.conf
Resuming scan at checksum offset ...
Discovered open port 80/tcp on 10.10.10.44
Example 7 — Scan top 100 ports across a large range
sudo masscan --top-ports 100 172.16.0.0/12 --rate 50000 -oG top_scan.gnmap
Discovered open port 445/tcp on 172.16.4.22
Discovered open port 3389/tcp on 172.16.4.22
Example 8 — Save raw packet capture while scanning
sudo masscan -p80 10.10.10.0/24 --rate 2000 --pcap results.pcap
[creates results.pcap for later analysis in Wireshark]
Example 9 — Sharded scan split across two machines (machine 1 of 2)
sudo masscan -p1-65535 10.0.0.0/8 --shard 1/2 --rate 20000
Scanning 1/2 shard of 10.0.0.0/8...
Discovered open port 22/tcp on 10.4.3.1
Example 10 — Dry-run list scan (no packets sent)
masscan -p80 192.168.1.0/28 -sL
192.168.1.1
192.168.1.2
192.168.1.3
...
7. Common Use Cases
- Internet-scale or enterprise-scale port scanning where speed is critical.
- Initial fast sweep of large IP ranges before handing narrowed results to Nmap for deep inspection.
- Continuous asset discovery scans in large environments.
- Bug bounty and external attack surface mapping across huge CIDR blocks.
- Research into global service exposure (e.g., counting hosts with a specific open port).
8. Automation with Bash
#!/bin/bash
# fast_then_deep.sh - masscan for speed, then nmap for depth
TARGET_RANGE="10.10.0.0/16"
RATE=20000
OUT="masscan_results.txt"
echo "[*] Running Masscan sweep..."
sudo masscan -p1-65535 "$TARGET_RANGE" --rate "$RATE" -oG "$OUT"
echo "[*] Extracting live IP:port pairs..."
grep "Host:" "$OUT" | awk '{print $2, $4}' | sed 's#/open.*##' > live_ports.txt
echo "[*] Feeding results into Nmap for service detection..."
while read -r ip port; do
nmap -sV -p"$port" "$ip" -oN "nmap_${ip}.txt"
done < live_ports.txt
9. Tips and Best Practices
- Always run as root (raw socket access required) and use
sudo. - Start with a conservative
--rateon shared/production networks — very high rates can act like a DoS and saturate links or switch tables. - Use
--router-macexplicitly on networks where ARP resolution for the gateway may be unreliable. - Masscan’s
-sV-style deep service detection is limited; pair it with Nmap for accurate version fingerprinting. - Use
--excludefileto protect sensitive or out-of-scope hosts during large sweeps. - Save results in a resumable format for very long scans that might be interrupted.
10. Troubleshooting
- No results returned at all: verify the correct interface with
-eand confirm--router-macis correct. - “FAIL: failed to detect router” error: manually supply
--router-mac <gateway-mac>. - Excessive packet loss / missed opens: lower
--rate, as the sending NIC or downstream switch may be dropping packets. - Permission denied: run with
sudo, since raw packet crafting requires elevated privileges. - Scan seems to hang at “waiting for responses”: increase
--waitseconds to catch delayed replies.
11. References
- GitHub repository: https://github.com/robertdavidgraham/masscan
- Kali Linux tool page: https://www.kali.org/tools/masscan/
- Robert Graham’s blog on Masscan’s internet-scale scanning: http://blog.erratasec.com/