Provided by: masscan_1.0.3-95-gb395f18~ds0-2_amd64 
NAME
masscan - Fast scan of the Internet
SYNOPSIS
masscan <ip addresses/ranges> -p ports options
DESCRIPTION
masscan is an Internet-scale port scanner, useful for large scale surveys of the Internet,
or of internal networks. While the default transmit 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.
OPTIONS
• <ip/range>: anything on the command-line not prefixed with a ´-´ is assumed to be an
IP address or range. There are three valid formats. 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 multiple 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 <ip/range>: the same as target range spec described above, except as a named
parameter instead of an unnamed one.
• -p <ports, --ports <ports>: 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 U:161,U:1024-1100.
• --banners: specifies that banners should be grabbed, like HTTP server versions, HTML
title fields, and so forth. Only a few protocols are supported.
• --rate <packets-per-second>: specifies the desired rate for transmitting 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
million packets/second. In my experience, Windows and can do 250 thousand 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 <filename>, --conf <filename>: reads in a configuration file. The format of the
configuration file is described below.
• --resume <filename>: 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 <ifname>, --adapter <ifname>: use the named raw network interface, such as "eth0"
or "dna1". If not specified, the first network interface found with a default gateway
will be used.
• --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.
• --adapter-port <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 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.
• --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.
• --ping: indicates that the scan should include an ICMP echo request. This may be
included with TCP and UDP scanning.
• --exclude <ip/range>: 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 <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.
• --append-output: causes output to append to file, rather than overwriting 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 regardless if replies have already been
received.
• --nmap: print help aobut nmap-compatibility alternatives for these options.
• --pcap-payloads: read packets from a libpcap file containing packets 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 <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.
• --http-user-agent <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 <filename>: saves received packets (but not transmitted packets) to the
libpcap-format file.
• --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.
• --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 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.
• --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.
• --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.
• --rotate-offset <time>: an offset in the time. This is to accommodate timezones.
• --rotate-dir <directory>: when rotating the file, this specifies which directory to
move the file to. A useful directory is /var/log/masscan.
• --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.
• --regress: run a regression test, returns ´0´ on success and ´1´ on failure.
• --ttl <num>: specifies the TTL of outgoing packets, defaults to 255.
• --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.
• --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.
• -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.
• --interactive: show the results in realtime on the console. It has no effect if used
with --output-format or --output-filename.
• --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.
• --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.
• -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 mush smaller than their XML equivelents, but require a separate step to
convert back into XML or another readable format.
• -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.
CONFIGURATION FILE FORMAT
The configuration file uses the same parameter names as on the commandline, but without
the -- prefix, and with an = sign between the name and the value. An example configuration
file might be:
# 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. 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 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 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 index 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 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 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
nmap(8), pcap(3)
AUTHORS
This tool was written by Robert Graham. The source code is available at
https://github.com/robertdavidgraham/masscan.
January 2014 MASSCAN(8)