TopGit
GitHub Repo Review

masscan: an asynchronous Internet-scale port scanner

MTopGit review image for robertdavidgraham/masscan
Review by Topgit.dev for robertdavidgraham/masscan, with GitHub repository stats and README context.
Quick verdict

masscan is the right call the moment nmap starts taking hours instead of minutes: it swaps nmap's careful, stateful scanning for a stateless SYN blast a single machine can throw at huge address ranges. It's brutally fast at plain port discovery, but its own TCP/IP stack means banner grabbing and anything past "is this port open" needs extra plumbing nmap users never have to think about.

Stars
★ 26.1k
Forks
⑂ 3.2k
Language
C
License
AGPL-3.0
Topic
—
Updated
Oct 2026
Homepage
—
GitHub

What is masscan?

masscan is an asynchronous TCP port scanner that transmits SYN packets independently of any per-host connection state, the same design lineage the README cites as scanrand, unicornscan, and ZMap. Instead of nmap's one-thread-per-target approach, it runs separate transmit and receive threads against its own self-contained TCP/IP stack, which is what lets it push packet rates nmap was never built for.

What makes masscan different

  • ✓Runs an asynchronous engine with separate transmit and receive threads instead of nmap's one-connection-at-a-time model; the README describes masscan as being to nmap what nginx is to Apache.
  • ✓Randomizes scan order by encrypting the index variable rather than scanning sequentially, so packets spread evenly across a target range instead of hammering one subnet first.
  • ✓Supports sharding a single scan across multiple machines, network adapters, or source IPs, splitting the address range between them.
  • ✓Can be stopped with ctrl-c and resumed later from the same index, and retransmits dropped packets using the packet rate as the retry offset.
  • ✓Ships nmap-compatible flags and an nmap-inspired XML output format on purpose, plus a --nmap flag that lists further compatible options.
  • ✓Optional PF_RING DNA driver support bypasses the kernel for packet transmit, one of three techniques the README credits for its scalability alongside a user-mode TCP stack and mutex-free ring synchronization.
How this repository's GitHub stars have grown over time. Source: star-history.com.View the star history ↗

When to reach for masscan

  • •Sweeping a large internal network, such as several /8s, for open ports in minutes instead of the hours nmap would need on the same range.
  • •Internet-wide port-discovery research, using --excludefile to blacklist ranges you're not supposed to touch before you start.
  • •A fast first pass ahead of nmap: find live ports across a big range with masscan, then point nmap's deeper service and version detection only at hosts that answered.
  • •Firewall and rate-limit testing on your own network, since the README warns that a default full-rate scan can overwhelm a local segment.

Building and installing masscan

On Debian/Ubuntu: run `sudo apt-get --assume-yes install git make gcc`, then `git clone https://github.com/robertdavidgraham/masscan`, `cd masscan`, and `make` (or `make -j` for a faster multi-threaded build; the README notes this needs more than 2 gigs of RAM, so it can break on something as small as a Raspberry Pi). `make install` puts the binary on your PATH; skip it and the compiled binary just sits in `masscan/bin`. Windows builds via the VS10 Visual Studio project or, under MinGW, plain `make` -- Cygwin is explicitly called out as not working. macOS builds with the Xcode4 project or command-line `make`, and the README notes x86 binaries run about as fast under ARM emulation. FreeBSD uses `gmake` instead of `make`. For anything else, the README's fallback is compiling every source file directly: `cc src/*.c -o bin/masscan`.

Running your first scan

A basic scan looks like `masscan -p80,8000-8100 10.0.0.0/8 2603:3001:2d00:da00::/112`, which checks port 80 plus the 8000-8100 range -- 102 ports total -- across both an IPv4 and an IPv6 subnet, printing results to stdout. `--echo` dumps your full configuration so you can save it and replay it later with `-c`. For banner grabbing (FTP, HTTP, IMAP4, memcached, POP3, SMTP, SSH, SSL, SMBv1, SMBv2, Telnet, RDP, VNC) add `--banners`, but expect the local OS to interfere: masscan's separate TCP/IP stack means the kernel answers the target's SYN-ACK with an RST before masscan can read anything, so you need `--source-ip` on a spare address, or a firewall rule dropping a chosen `--source-port`, first. Results write out as XML (`-oX`), masscan's own compact binary format (readable back with `--readscan`), nmap-style grepable output (`-oG`), JSON (`-oJ`), or a plain list (`-oL`).

Strengths

  • ✓On Linux without virtualization the README puts its transmit rate in the millions of packets per second, fast enough that ranges nmap would take hours on finish in minutes.
  • ✓The CLI is deliberately nmap-shaped -- -p, -oX, --randomize-hosts -- so existing nmap muscle memory mostly transfers.
  • ✓--echo dumps every option to a reusable config file, and -c reloads it, handy for repeating a huge scan exactly.
  • ✓Five output formats (xml, binary, grepable, json, list) cover both quick grepping and machine parsing.
  • ✓Sharding lets you split one scan across several machines, NICs, or source IPs.

Known limitations and gotchas

  • △Its own ad hoc TCP/IP stack means the local OS RSTs the connection before masscan can grab a banner unless you set a spare --source-ip or firewall your chosen --source-port first -- not something you hit with an ordinary scanner.
  • △No default ports: leave off -p and you get nothing useful, unlike nmap's built-in top-ports fallback.
  • △Targets must be literal IPs or CIDR ranges -- no DNS names, and none of nmap's shorthand notation like 10.0.0-255.0-255.
  • △The README's own warning is that a full-rate scan can overwhelm your local network segment, so it's not something to run carelessly from a shared connection.
  • △AGPL-3.0 licensing applies, which carries copyleft obligations worth checking before folding masscan into a closed-source product or service.

masscan vs nmap, ZMap, and unicornscan

nmap -- the default choice for scanning a handful of hosts in depth; slower over huge ranges since it tracks state per target, and masscan borrows its CLI flags and XML format on purpose.ZMap -- the same asynchronous, stateless design as masscan for Internet-wide sweeps; the README lists it directly among masscan's design predecessors.unicornscan -- an earlier asynchronous scanner the README credits as a direct influence on masscan's architecture.

Frequently asked questions

Why is masscan grabbing banners not working on Linux?

Banner grabbing fails on Linux because masscan runs its own separate TCP/IP stack. When a target replies with a SYN-ACK, Linux's own kernel stack sees it too and immediately fires back an RST, killing the connection before masscan can read the banner. Fix it with a spare --source-ip, or firewall your --source-port with an iptables DROP rule so Linux never sees the reply.

What rate should I use to avoid overwhelming my network with masscan?

masscan defaults to a safe but slow 100 packets per second. The README's own warning is that pushing the rate up -- its examples go as high as --max-rate 100000 -- can overwhelm your local network segment, and IPv6 scans are riskier since they concentrate traffic on one target subnet instead of spreading across many. Raise --rate gradually and watch your own link.

Can masscan scan the entire IPv4 Internet?

masscan can scan the entire IPv4 Internet -- that's its design goal, and the README's own example command is `masscan 0.0.0.0/0 -p0-65535`. At the default 100 packets/second rate that's impractically slow, but raising the rate with --max-rate (the README's example uses 100000) brings a full scan of one port down to about 10 hours, per the README.

How do I exclude IP ranges from a masscan Internet-wide scan?

Use masscan's --excludefile option, pointing it at a text file listing the ranges to skip, for example `masscan 0.0.0.0/0 -p0-65535 --excludefile exclude.txt`. This matters for Internet-wide scans because parts of the Internet react badly to being probed, and some networks add scanning IPs to ban lists, so excluding sensitive ranges first is standard practice.

Does masscan work on Windows and macOS?

masscan runs on Windows and macOS as well as Linux, its primary target platform. Windows builds via the VS10 Visual Studio project or plain `make` under MinGW (Cygwin doesn't work), and macOS builds with the Xcode4 project or command-line `make`. The README notes both platforms top out around 300,000 packets per second, well below what Linux reaches without virtualization.

What output formats does masscan support for scan results?

masscan supports five output formats: XML (-oX), its own compact binary format (re-readable with --readscan), nmap-style grepable output (-oG), JSON (-oJ), and a simple list format (-oL) with one open port per line. Binary is the most disk-efficient for huge scans; XML and JSON suit downstream parsing.

The problem it solves

Large-scale recon runs into a hard scaling wall: nmap's stateful, one-connection-at-a-time model, which makes it precise against a single host, does not scale to scanning a /8 or the full IPv4 range in any reasonable time. masscan exists specifically to strip per-target state out of the scan loop so port discovery across huge address ranges stops being an overnight job.

Who should try it — and who should skip

Try masscan if you're a security researcher or network engineer who needs open-port data across a /8, a cloud provider's whole range, or the public Internet, and you're comfortable working entirely at the command line with raw sockets and no default ports to fall back on. Skip it if you're auditing a handful of hosts and want service or version detection, OS fingerprinting, or scripting -- that's nmap's job, and masscan doesn't attempt any of it.

Source & attribution

Facts and quotes in this review are drawn from the robertdavidgraham/masscan GitHub repository (github.com/robertdavidgraham/masscan), its README and repo metadata.

GitHub data · last synced Aug 15, 2026Reviewed by Henry
← Back to TopGit

Is masscan worth your time?

ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of masscan.

GitHub