MASSCAN(8)

📦
version 1.3.2 · 2 versions
, in alpine 3.24, arch rolling, epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💅 MASSCAN(8) — like, the manual page, bestie ✨

okay so real talk, this is masscan from section 8 of the manual (that's the sysadmin-y section, iykyk 🫶). buckle up.

🌸 NAME 🌸

masscan — Fast scan of the Internet 🚀

✨ SYNOPSIS ✨

masscan <ip addresses/ranges> -p ports options

like, that's the whole vibe. you give it addresses, you give it ports, you sprinkle some options on top. done. 💅

🦋 DESCRIPTION 🦋

so masscan is an Internet-scale port scanner, no cap. it's the tool you reach for when you wanna do large scale surveys of the Internet, or honestly just poke around your own internal networks — both slay equally. 💖

here's the part that makes everyone gasp: the default transmit rate is only 100 packets/second (lowkey chill, respectful, doesn't wanna be rude 🌸) but it can optionally go as fast as 25 million packets/second. twenty-five. million. 🔥 that's a rate sufficient to scan the entire Internet in 3 minutes for one port. three minutes. the way that's genuinely iconic. 😭👑

bestie, just know that's what it can do, not what it does by default. we'll get into the flags later, don't worry 🧚

more parts coming, don't go anywhere 💜

✨ OPTIONS ✨

Okay bestie, this is the part where masscan shows you everything it can do, and honestly? It's a lot. Grab a snack 🍓 — we're going through all of it, nothing skipped, nothing glossed over. iykyk.

  • <ip/range> — literally anything on the command line that isn't prefixed with a - gets treated as an IP address or a range. There are three valid formats, and you gotta pick one of them:
    1. a single IPv4 address, like "192.168.0.1" 🎯
    2. a range, like "10.0.0.1-10.0.0.100"
    3. a CIDR address, like "0.0.0.0/0" (yes, the whole entire internet, no cap)

At least one target must be specified — no targets, no scan, periodt. You can give multiple targets though! Either as multiple options separated by space, or comma-separated as one single option, like 10.0.0.0/8,192.168.0.1. Slay 💅

  • --range <ip/range> — same target range spec as above, except it's a named parameter instead of an unnamed one. Same vibe, different outfit.
  • -p <ports>, --ports <ports> — tells masscan which port(s) to scan, bestie. A single port? -p80. A range of ports? -p 20-25. A whole list of ports/ranges? -p80,20-25. And yes, UDP ports are welcome to the party too: --ports U:161,U:1024-1100. 🎀
  • --banners — asks masscan to grab banners, like HTTP server versions, HTML title fields, and so forth. Heads up though: only a few protocols are supported. It's giving ✨limited edition✨.
  • --rate <packets-per-second> — sets the desired rate for transmitting packets 🔥. This can be very small numbers, like 0.1 for transmitting packets at a rate of one every 10 seconds, or very large numbers like 10000000, which attempts to transmit at 10 million packets/second. In my experience, Windows can do 250 thousand packets per second, and the latest versions of Linux can do 2.5 million packets per second. The PF_RING driver is what you need to get to 25 million packets/second 👑
  • -c <filename>, --conf <filename> — reads in a configuration file. The format of the configuration file is described below, so keep reading, babe.
  • --resume <filename> — the same as --conf, except a few options are automatically set, such as --append-output. The format of the configuration file is described below. It's the "pick up where we left off" energy 🌸
  • --echo — don't run anything, just dump the current configuration to a file. That file can then be used with the -c option. The format of this output is described below under 'CONFIGURATION FILE'. Look ma, no scanning 🙈
  • -e <ifname>, --adapter <ifname> — use the named raw network interface, such as "eth0" or "dna1". If you don't specify one, the first network interface found with a default gateway will be used. It'll just pick for you, main character energy.
  • --adapter-ip <ip-address> — send packets using this IP address. If not specified, then the first IP address bound to the network interface will be used. Instead of a single IP address, a range may be specified.
⚠️ NOTE: the size of the range must be an even power of 2, such as 1, 2, 4, 8, 16, 1024 etc. addresses. Not vibes-optional, fr fr.
  • --adapter-port <port> — send packets using this port number as the source. If not specified, a random port gets chosen in the range 40000 through 60000. This port should be filtered by the host firewall (like iptables) to prevent the host network stack from interfering with arriving packets. Instead of a single port, a range can be specified, like 40000-40003.
⚠️ NOTE: the size of the range must be an even power of 2, such as the example above that has a total of 4 addresses. Same rule, no exceptions 💀
  • --adapter-mac <mac-address> — send packets using this as the source MAC address. If not specified, then the first MAC address bound to the network interface will be used. 🦋
  • --router-mac <mac address> — send packets to this MAC address as the destination. If not specified, then the gateway address of the network interface will be ARPed. It'll go ask, don't worry.
  • --ping — indicates the scan should include an ICMP echo request. This may be included with TCP and UDP scanning. Multitasking icon 💖
  • --exclude <ip/range> — blacklists an IP address or range, preventing it from being scanned. This overrides any target specification, guaranteeing that this address/range won't be scanned. Same format as the normal target specification. It's the "not you, bestie" list 🙅‍♀️
  • --excludefile <filename> — reads in a list of exclude ranges, in the same target format described above. These ranges override any targets, preventing them from being scanned. Same protective energy, just from a file.
  • --append-output — causes output to append to the file rather than overwriting it. No deleting your old receipts 🧾
  • --iflist — list the available network interfaces, and then exit. Short king behavior: in and out 🌈
  • --retries — the number of retries to send, at 1 second intervals. Note that since this scanner is stateless, retries are sent regardless of whether replies have already been received. It's not being rude, it genuinely doesn't remember 💀
  • --nmap — print help about nmap-compatibility alternatives for these options. For my fellow recovering nmap girlies 🫶
  • --pcap-payloads — read packets from a libpcap file containing packets, extract the UDP payloads, and associate those payloads with the destination port. These payloads will then be used when sending UDP packets with the matching destination port. Only one payload will be remembered per port. Similar to --nmap-payloads. Memory of a goldfish but make it useful 🐠
  • --nmap-payloads <filename> — read in a file in the same format as the nmap file nmap-payloads. This contains UDP payload, so that we can send useful UDP packets instead of empty ones. Similar to --pcap-payloads. Give the packets something to say ✨
  • --http-user-agent <user-agent> — replaces the existing user-agent field with the indicated value when doing HTTP requests. Costume change for your packets 🎭
  • --open-only — report only open ports, not closed ports. We're not doing negative energy today 💅
  • --pcap <filename> — saves received packets (but not transmitted packets) to the libpcap-format file. Receipts only, no sent folder 💌
  • --packet-trace — prints a summary of those packets sent and received. This is useful at low rates, like a few packets per second, but will overwhelm the terminal at high rates. Like, it will absolutely flood your screen, bestie 🌊
  • --pfring — force the use of the PF_RING driver. The program will exit if PF_RING DNA drivers are not available. All or nothing, periodt.
  • --resume-index — the point in the scan at when it was paused. Bookmark behavior 🔖
  • --resume-count — the maximum number of probes to send before exiting. This is useful with the --resume-index to chop up a scan and split it among multiple instances, though the --shards option might be better. Options, options 🎀
  • --shards <x>/<y> — splits the scan among instances. x is the id for this scan, while y is the total number of instances. For example, --shards 1/2 tells an instance to send every other packet, starting with index 0. Likewise, --shards 2/2 sends every other packet, but starting with index 1, so that it doesn't overlap with the first example. Teamwork makes the dream work 🧚
  • --rotate <time> — rotates the output file, renaming it with the current timestamp, moving it to a separate directory. The time is specified in number of seconds, like "3600" for an hour. Or, units of time can be specified, such as "hourly", or "6hours", or "10min". Times are aligned on an even boundary, so if "daily" is specified, then the file will be rotated every day at midnight. Midnight rotation is so aesthetic 🌙
  • --rotate-offset <time> — an offset in the time. This is to accommodate timezones. Because time zones are chaos 😭
  • --rotate-dir <directory> — when rotating the file, this specifies which directory to move the file to. A useful directory is /var/log/masscan. Put it somewhere tidy 💜
  • --seed <integer> — an integer that seeds the random number generator. Using a different seed will cause packets to be sent in a different random order. Instead of an integer, the string time can be specified, which seeds using the local timestamp, automatically generating a differnet random order of scans. If no seed specified, time is the default. Random but reproducibly random, iconic.
  • --regress — run a regression test, returns '0' on success and '1' on failure. Pass or fail, no in-between ⭐
  • --ttl <num> — specifies the TTL of outgoing packets, defaults to 255. Keep it alive as long as possible, honestly.
  • --wait <seconds> — specifies the number of seconds after transmit is done to wait for receiving packets before exiting the program. The default is 10 seconds. The string forever can be specified to never terminate. Forever is a long time, bestie 🫶
  • --offline — don't actually transmit packets. This is useful with a low rate and --packet-trace to look at what packets might've been transmitted. Or, it's useful with --rate 100000000 in order to benchmark how fast transmit would work (assuming a zero-overhead driver). PF_RING is about 20% slower than the benchmark result from offline mode. Practice mode, basically 🎮
  • -sL — this doesn't do a scan, but instead creates a list of random addresses. This is useful for importing into other tools. The options --shard, --resume-index, and --resume-count can be useful with this feature. Generator era ✨
  • --interactive — show the results in realtime on the console. It has no effect if used with --output-format or --output-filename. Live, laugh, watch it happen 👀
  • --output-format <fmt> — indicates the format of the output file, which can be xml, binary, grepable, list, or JSON. The option --output-filename must be specified. No file, no format, that's the rule.
  • --output-filename <filename> — the file which to save results to. If the parameter --output-format is not specified, then the default of xml will be used. Default queen 👑
  • -oB <filename> — sets the output format to binary and saves the output in the given filename. This is equivelent to using the --output-format and --output-filename parameters. The option --readscan can then be used to read the binary file. Binary files are much smaller than their XML equivelents, but require a separate step to convert back into XML or another readable format. Small file, extra homework 💀
  • -oX <filename> — sets the output format to XML and saves the output in the given filename. This is equivelent to using the --output-format xml and --output-filename parameters.
  • -oG <filename> — sets the output format to grepable and saves the output in the given filename. This is equivelent to using the --output-format grepable and --output-filename parameters.
  • -oJ <filename> — sets the output format to JSON and saves the output in the given filename. This is equivelent to using the --output-format json and --output-filename parameters.
  • -oL <filename> — sets the output format to a simple list format and saves the output in the given filename. This is equivelent to using the --output-format list and --output-filename parameters.
  • --readscan <binary-files> — reads the files created by the -oB option from a scan, then outputs them in one of the other formats, depending on command-line parameters. In other words, it can take the binary version of the output and convert it to an XML or JSON format. Glow-up pipeline 🔥

💖 CONFIGURATION FILE FORMAT 💖

okay so the config file is literally the same parameter names as the command line, but without the -- prefix, and with an = sign between the name and the value. An example config file might look like this, bestie:

# targets
range = 10.0.0.0/8,192.168.0.0/16
range = 172.16.0.0/14
ports = 20-25,80,U:53
ping = true

# adapter
adapter = eth0
adapter-ip = 192.168.0.1
router-mac = 66-55-44-33-22-11

# other
exclude-file = /etc/masscan/exludes.txt

By default, the program will read default configuration from the file /etc/masscan/masscan.conf. This is useful for system-specific settings, such as the --adapter-xxx options. It’s also useful for excluded IP addresses, so you can scan the entire Internet while skipping dangerous addresses, like those owned by the DoD, and not make an accidental mistake. 🫶

🎀 CONTROL-C BEHAVIOR 🎀

When the user presses Ctrl+C, the scan will stop, and the current state of the scan will be saved in the file paused.conf. The scan can be resumed with the --resume option:

# masscan --resume paused.conf

The program will not exit immediately, but will wait a default of 10 seconds to receive results from the Internet and save the results before exiting completely. This time can be changed with the --wait option. ⏳

✨ SIMPLE EXAMPLES ✨

The following example scans all private networks for webservers, and prints all open ports that were found:

# masscan 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12 -p80 --open-only

The following example scans the entire Internet for DNS servers, grabbing their versions, then saves the results in an XML file:

# masscan 0.0.0.0/0 --excludefile no-dod.txt -pU:53 --banners --output-filename dns.xml

You should be able to import the XML into databases and such. 💾

The following example reads a binary scan results file called bin-test.scan and prints results to console:

# masscan --readscan bin-test.scan

The following example reads a binary scan results file called bin-test.scan and creates an XML output file called bin-test.xml:

# masscan --readscan bin-test.scan -oX bin-test.xml

🦋 ADVANCED EXAMPLES 🦋

Let’s say you want to scan the entire Internet and spread the scan across three machines. Masscan would be launched on all three machines using the following command-lines:

# masscan 0.0.0.0/0 -p0-65535 --shard 1/3
# masscan 0.0.0.0/0 -p0-65535 --shard 2/3
# masscan 0.0.0.0/0 -p0-65535 --shard 3/3

An alternative is with the “resume” feature. A scan has an internal index that goes from zero to the number of ports times the number of IP addresses. The following example shows splitting up a scan into chunks of a 1000 items each:

# masscan 0.0.0.0/0 -p0-65535 --resume-index 0 --resume-count 1000
# masscan 0.0.0.0/0 -p0-65535 --resume-index 1000 --resume-count 1000
# masscan 0.0.0.0/0 -p0-65535 --resume-index 2000 --resume-count 1000
# masscan 0.0.0.0/0 -p0-65535 --resume-index 3000 --resume-count 1000

A script can use this to split smaller tasks across many other machines, such as Amazon EC2 instances. As each instance completes a job, the script might send a request to a central coordinating server for more work. 👑

🌸 SPURIOUS RESETS 🌸

When scanning TCP using the default IP address of your adapter, the built-in stack will generate RST packets. This will prevent banner grabbing. There are two ways to solve this. The first way is to create a firewall rule to block that port from being seen by the stack. How this works is dependent on the operating system, but on Linux this looks something like:

# iptables -A INPUT -p tcp -i eth0 --dport 61234 -j DROP

Then, when scanning, that same port must be used as the source:

# masscan 10.0.0.0/8 -p80 --banners --adapter-port 61234

An alternative is to “spoof” a different IP address. This IP address must be within the range of the local network, but must not otherwise be in use by either your own computer or another computer on the network. An example of this would look like:

# masscan 10.0.0.0/8 -p80 --banners --adapter-ip 192.168.1.101

Setting your source IP address this way is the preferred way of running this scanner. 💅

💀 ABUSE COMPLAINTS 💀

This scanner is designed for large-scale surveys, of either an organization, or of the Internet as a whole. This scanning will be noticed by those monitoring their logs, which will generate complaints.

If you are scanning your own organization, this may lead to you being fired. Never scan outside your local subnet without getting permission from your boss, with a clear written declaration of why you are scanning.

The same applies to scanning the Internet from your employer. This is another good way to get fired, as your IT department gets flooded with complaints as to why your organization is hacking them.

When scanning on your own, such as your home Internet or ISP, this will likely cause them to cancel your account due to the abuse complaints.

One solution is to work with your ISP, to be clear about precisely what we are doing, to prove to them that we are researching the Internet, not “hacking” it. We have our ISP send the abuse complaints directly to us. For anyone that asks, we add them to our --excludefile, blacklisting them so that we won’t scan them again. While interacting with such people, some instead add us to their whitelist, so that their firewalls won’t log us anymore (they’ll still block us, of course, they just won’t log that fact to avoid filling up their logs with our scans).

Ultimately, I don’t know if it’s possible to completely solve this problem. Despite the Internet being a public, end-to-end network, you are still “guilty until proven innocent” when you do a scan. 😭

🌈 COMPATIBILITY 🌈

While not listed in this document, a lot of parameters compatible with nmap will also work. ✨

👑 SEE ALSO 👑

💜 AUTHORS 💜

This tool was written by Robert Graham. The source code is available at https://github.com/robertdavidgraham/masscan.

okay that’s the whole page, bestie — it’s the January 2014 edition of MASSCAN(8), and you absolutely ate that read 💅✨

📦 where this page comes from