Masscan Deployment & Usage Guide

Masscan is an Internet-scale asynchronous TCP port scanner capable of transmitting 10 million packets per second. This guide covers installation, configuration, and safe deployment practices.

1. Prerequisites

System Requirements

Operating System: Linux (primary target), macOS, FreeBSD, or Windows
Privileges: Root or sudo access required for raw socket operations
Compiler: GCC or Clang
Build Tools: git, make
Network: Dedicated or properly firewalled network interface recommended for high-speed scanning

Platform-Specific Dependencies

Debian/Ubuntu:

sudo apt-get --assume-yes install git make gcc

macOS:

Xcode Command Line Tools
Or use Homebrew: brew install git make gcc

FreeBSD:

pkg install gmake git

Windows:

Visual Studio 2010+ (for VS project), or
MinGW-w64 (for make command)

2. Installation

Clone and Build

git clone https://github.com/robertdavidgraham/masscan
cd masscan

Standard Build:

make

Parallel Build (Faster, requires 2GB+ RAM):

make -j

FreeBSD:

gmake

The binary is created at masscan/bin/masscan.

System Installation (Linux/macOS)

sudo make install

This installs the binary to /usr/local/bin or equivalent.

Verify Installation

masscan --version

3. Configuration

Basic Configuration File

Generate a template configuration:

masscan -p80,8000-8100 10.0.0.0/8 --echo > scan.conf

Run using the configuration file:

sudo masscan -c scan.conf --rate 1000

Critical: TCP/IP Stack Isolation

Masscan uses its own ad hoc TCP/IP stack. You must isolate it from the operating system's stack to prevent RST packets from killing connections, especially when using --banners.

Option A: Dedicated Source IP (Recommended)

Assign an unused IP address on your local subnet:

sudo masscan 10.0.0.0/8 -p80 --banners --source-ip 192.168.1.200

Option B: Firewall Source Port (Linux)

Block the OS from handling return traffic on specific ports:

# Check OS ephemeral port range to avoid conflicts
cat /proc/sys/net/ipv4/ip_local_port_range
# Example output: 32768 60999

# Choose ports outside this range (e.g., 61000+ or below 32768)
sudo iptables -A INPUT -p tcp --dport 61000:61050 -j DROP
sudo iptables -A INPUT -p tcp --dport 40000:40050 -j DROP

# Run scan with source port range
sudo masscan 10.0.0.0/8 -p80 --banners --source-port 61000

Persisting iptables rules:

sudo apt-get install iptables-persistent
sudo netfilter-persistent save

Option C: Packet Filter (macOS/BSD)

Check port ranges:

sysctl net.inet.ip.portrange.first net.inet.ip.portrange.last

FreeBSD/older macOS (ipfw):

sudo ipfw add 1 deny tcp from any to any 40000 in
sudo masscan 10.0.0.0/8 -p80 --banners --source-port 40000

Newer macOS/OpenBSD (pf): Edit /etc/pf.conf:

block in proto tcp from any to any port 40000:40015

Enable:

sudo pfctl -f /etc/pf.conf
sudo pfctl -e

Rate Limiting

Prevent overwhelming your upstream:

# 10,000 packets per second
sudo masscan 10.0.0.0/8 -p80 --rate 10000

Exclusions

Create an exclusion file for sensitive networks:

echo "10.0.0.0/8" > exclude.txt
echo "192.168.0.0/16" >> exclude.txt
sudo masscan 0.0.0.0/0 -p80 --excludefile exclude.txt

4. Build & Run

Development Build

For debugging (adds symbols, no optimization):

make DEBUG=1

Production Scanning

Basic network scan:

sudo masscan -p80,443,8080 192.168.1.0/24 --rate 1000

Full Internet scan (requires 10Gbps+ NIC and proper tuning):

sudo masscan 0.0.0.0/0 -p0-65535 --max-rate 10000000 -oX internet-scan.xml

IPv6 scanning:

sudo masscan 2603:3001:2d00:da00::/112 -p80,443 --source-ip 2603:3001:2d00:da00::100

Banner grabbing:

# Requires firewall rules or --source-ip as described in section 3
sudo masscan 10.0.0.0/8 -p21,22,80,443 --banners --source-port 61000

Output formats:

-oX scan.xml      # XML format (like nmap)
-oG scan.gnmap    # Grepable format
-oL scan.list     # List format
-oJ scan.json     # JSON format

5. Deployment

Bare Metal (Recommended for High Speed)

For 10M+ packets/second:

NIC: Intel 10Gbps+ with DPDK support (though masscan works with standard sockets)
CPU: Multi-core for --shard distributed scanning
RAM: 2GB+ for compilation, minimal for runtime
Network: Dedicated upstream, unshared with production traffic

Cloud Deployment

AWS/Azure/GCP Considerations:

Instance Type: Choose "10 Gigabit" or higher network performance
Security Groups: Outbound allow-all required; inbound rules don't affect transmission
Source IP: Use --source-ip <instance-ip> to ensure return traffic routes correctly
Rate Limiting: Cloud providers often throttle; start with --rate 100000 and scale up

Docker Deployment:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y git make gcc
RUN git clone https://github.com/robertdavidgraham/masscan && cd masscan && make && make install
ENTRYPOINT ["masscan"]

Run with required privileges:

docker build -t masscan .
docker run --rm --cap-add=NET_RAW --cap-add=NET_ADMIN --network host masscan 10.0.0.0/8 -p80

Distributed Scanning

Split workload across multiple machines:

# Machine 1
sudo masscan 0.0.0.0/0 -p80 --shard 1/4 --rate 2500000

# Machine 2
sudo masscan 0.0.0.0/0 -p80 --shard 2/4 --rate 2500000

6. Troubleshooting

Build Issues

Error: make: cc: Command not found

# Debian/Ubuntu
sudo apt-get install build-essential

# macOS
xcode-select --install

Raspberry Pi: Build fails with out of memory Use limited parallelism:

make -j2

Runtime Issues

Permission denied (raw sockets) Masscan requires root for raw socket access:

sudo masscan [options]

Note: Do not set SUID bit on masscan binary (security risk).

"Connection reset by peer" during banner grabbing The OS TCP stack is interfering. You must:

Use --source-ip with an unused IP, OR
Configure iptables/pf to drop packets on the source port (see Section 3)

No packets transmitting Check interface:

sudo masscan 10.0.0.0/8 -p80 --interface eth0

Packet loss at high rates Reduce rate or check NIC/driver capabilities:

# Check for drops
ifconfig eth0 | grep dropped

"Adapter NULL not found" (Windows) Run as Administrator and specify adapter:

masscan.exe 10.0.0.0/8 -p80 --adapter \Device\NPF_{GUID}

Network Conflicts

Accidental network disruption If you scanned your own infrastructure and caused outages:

Flush iptables if you added DROP rules: sudo iptables -F INPUT
Disable pf: sudo pfctl -d
Restart networking service on affected hosts

Scan results inconsistent Ensure --source-port range doesn't overlap with OS ephemeral ports:

# Linux
cat /proc/sys/net/ipv4/ip_local_port_range

# macOS/BSD
sysctl net.inet.ip.portrange.first net.inet.ip.portrange.last

Performance Tuning

Maximize single-machine performance:

Use -j flag during build
Ensure CPU governor is set to performance mode
Disable hyper-threading if clock speed is prioritized over core count
Use --offline flag for testing (no actual transmission)

How to Deploy & Use robertdavidgraham/masscan