masscan - Man Page

Fast scan of the Internet

Examples (TL;DR)

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

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.

Info

January 2014