• : anything on the command-line not prefixed with a ´-´ is
assumed to be an IP address or range. There are three valid for‐
mats. The first is a single IPv4 address like "192.168.0.1". The
second is a range like "10.0.0.1-10.0.0.100". The third is a CIDR
address, like "0.0.0.0/0". At least one target must be specified.
Multiple targets can be specified. This can be specified as multi‐
ple options separated by space, or can be separated by a comma as a
single option, such as 10.0.0.0/8,192.168.0.1.
• --range : the same as target range spec described above,
except as a named parameter instead of an unnamed one.
• -p : specifies the port(s) to be scanned. A
single port can be specified, like -p80. A range of ports can be
specified, like -p 20-25. A list of ports/ranges can be specified,
like -p80,20-25. UDP ports can also be specified, like --ports
• --banners: specifies that banners should be grabbed, like HTTP
server versions, HTML title fields, and so forth. Only a few proto‐
cols are supported.
• --rate : specifies the desired rate for trans‐
mitting packets. This can be very small numbers, like 0.1 for
transmitting packets at rates of one every 10 seconds, for very
large numbers like 10000000, which attempts to transmit at 10 mil‐
lion packets/second. In my experience, Windows and can do 250 thou‐
sand packets per second, and latest versions of Linux can do 2.5
million packets per second. The PF_RING driver is needed to get to
25 million packets/second.
• -c , --conf : reads in a configuration file.
The format of the configuration file is described below.
• --resume : the same as --conf, except that a few options
are automatically set, such as --append-output. The format of the
configuration file is described below.
• --echo: don´t run, but instead dump the current configuration to a
file. This file can then be used with the -c option. The format of
this output is described below under ´CONFIGURATION FILE´.
• -e , --adapter : use the named raw network inter‐
face, such as "eth0" or "dna1". If not specified, the first network
interface found with a default gateway will be used.
• --adapter-ip : send packets using this IP address. If
not specified, then the first IP address bound to the network in‐
terface 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.
• --adapter-port : send packets using this port number as the
source. If not specified, a random port will be chosen in the range
40000 through 60000. This port should be filtered by the host fire‐
wall (like iptables) to prevent the host network stack from inter‐
fering 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
• --adapter-mac : 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 : send packets to this MAC address as the
destination. If not specified, then the gateway address of the net‐
work interface will be ARPed.
• --ping: indicates that the scan should include an ICMP echo re‐
quest. This may be included with TCP and UDP scanning.
• --exclude : blacklist an IP address or range, preventing
it from being scanned. This overrides any target specification,
guaranteeing that this address/range won´t be scanned. This has the
same format as the normal target specification.
• --excludefile : reads in a list of exclude ranges, in the
same target format described above. These ranges override any tar‐
gets, preventing them from being scanned.
• --append-output: causes output to append to file, rather than over‐
writing the file.
• --iflist: list the available network interfaces, and then exits.
• --retries: the number of retries to send, at 1 second intervals.
Note that since this scanner is stateless, retries are sent regard‐
less if replies have already been received.
• --nmap: print help aobut nmap-compatibility alternatives for these
• --pcap-payloads: read packets from a libpcap file containing pack‐
ets and 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.
• --nmap-payloads : 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
• --http-user-agent : replaces the existing user-agent
field with the indicated value when doing HTTP requests.
• --open-only: report only open ports, not closed ports.
• --pcap : saves received packets (but not transmitted
packets) to the libpcap-format file.
• --packet-trace: prints a summary of those packets sent and re‐
ceived. This is useful at low rates, like a few packets per second,
but will overwhelm the terminal at high rates.
• --pfring: force the use of the PF_RING driver. The program will
exit if PF_RING DNA drvers are not available.
• --resume-index: the point in the scan at when it was paused.
• --resume-count: the maximum number of probes to send before exit‐
ing. This is useful with the --resume-index to chop up a scan and
split it among multiple instances, though the --shards option might
• --shards /: 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
The configuration file uses the same parameter names as on the command‐
line, but without the -- prefix, and with an = sign between the name
and the value. An example configuration file might be:
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 = eth0
adapter-ip = 192.168.0.1
router-mac = 66-55-44-33-22-11
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. This is also useful for excluded IP
addresses, so that you can scan the entire Internet, while skipping
dangerous addresses, like those owned by the DoD, and not make an acci‐
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 be‐
fore exiting completely. This time can be changed with the --wait op‐
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, grab‐
bing 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
Let´s say that 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 in‐
dex that goes from zero to the number of ports times then 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 ma‐
chines, such as Amazon EC2 instances. As each instance completes a job,
the script might send a request to a central coordinating server for
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 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 net‐
work. 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 is designed for large-scale surveys, of either an organi‐
zation, 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 scan‐
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", black‐
listing 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
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.
masscan is an Internet-scale port scanner, useful for large scale sur‐
veys of the Internet, or of internal networks. While the default trans‐
mit rate is only 100 packets/second, it can optional go as fast as 25
million packets/second, a rate sufficient to scan the Internet in 3
minutes for one port.