1MASSCAN(8) MASSCAN(8)
2
6 masscan - Fast scan of the Internet
7
9 masscan <ip addresses/ranges> -p ports options
10
12 masscan is an Internet-scale port scanner, useful for large scale sur‐
13 veys of the Internet, or of internal networks. While the default trans‐
14 mit rate is only 100 packets/second, it can optional go as fast as 25
15 million packets/second, a rate sufficient to scan the Internet in 3
16 minutes for one port.
17
19 • <ip/range>: anything on the command-line not prefixed with a ´-´ is
20 assumed to be an IP address or range. There are three valid for‐
21 mats. The first is a single IPv4 address like "192.168.0.1". The
22 second is a range like "10.0.0.1-10.0.0.100". The third is a CIDR
23 address, like "0.0.0.0/0". At least one target must be specified.
24 Multiple targets can be specified. This can be specified as multi‐
25 ple options separated by space, or can be separated by a comma as a
26 single option, such as 10.0.0.0/8,192.168.0.1.
27 • --range <ip/range>: the same as target range spec described above,
29 except as a named parameter instead of an unnamed one.
30 • -p <ports, --ports <ports>: specifies the port(s) to be scanned. A
32 single port can be specified, like -p80. A range of ports can be
33 specified, like -p 20-25. A list of ports/ranges can be specified,
34 like -p80,20-25. UDP ports can also be specified, like --ports
35 U:161,U:1024-1100.
36 • --banners: specifies that banners should be grabbed, like HTTP
38 server versions, HTML title fields, and so forth. Only a few proto‐
39 cols are supported.
40 • --rate <packets-per-second>: specifies the desired rate for trans‐
42 mitting packets. This can be very small numbers, like 0.1 for
43 transmitting packets at rates of one every 10 seconds, for very
44 large numbers like 10000000, which attempts to transmit at 10 mil‐
45 lion packets/second. In my experience, Windows and can do 250 thou‐
46 sand packets per second, and latest versions of Linux can do 2.5
47 million packets per second. The PF_RING driver is needed to get to
48 25 million packets/second.
49 • -c <filename>, --conf <filename>: reads in a configuration file.
51 The format of the configuration file is described below.
52 • --resume <filename>: the same as --conf, except that a few options
54 are automatically set, such as --append-output. The format of the
55 configuration file is described below.
56 • --echo: don´t run, but instead dump the current configuration to a
58 file. This file can then be used with the -c option. The format of
59 this output is described below under ´CONFIGURATION FILE´.
60 • -e <ifname>, --adapter <ifname>: use the named raw network inter‐
62 face, such as "eth0" or "dna1". If not specified, the first network
63 interface found with a default gateway will be used.
64 • --adapter-ip <ip-address>: send packets using this IP address. If
66 not specified, then the first IP address bound to the network in‐
67 terface will be used. Instead of a single IP address, a range may
68 be specified. NOTE: The size of the range must be an even power of
69 2, such as 1, 2, 4, 8, 16, 1024 etc. addresses.
70 • --adapter-port <port>: send packets using this port number as the
72 source. If not specified, a random port will be chosen in the range
73 40000 through 60000. This port should be filtered by the host fire‐
74 wall (like iptables) to prevent the host network stack from inter‐
75 fering with arriving packets. Instead of a single port, a range can
76 be specified, like 40000-40003. NOTE: The size of the range must be
77 an even power of 2, such as the example above that has a total of 4
78 addresses.
79 • --adapter-mac <mac-address>: send packets using this as the source
81 MAC address. If not specified, then the first MAC address bound to
82 the network interface will be used.
83 • --router-mac <mac address>: send packets to this MAC address as the
85 destination. If not specified, then the gateway address of the net‐
86 work interface will be ARPed.
87 • --ping: indicates that the scan should include an ICMP echo re‐
89 quest. This may be included with TCP and UDP scanning.
90 • --exclude <ip/range>: blacklist an IP address or range, preventing
92 it from being scanned. This overrides any target specification,
93 guaranteeing that this address/range won´t be scanned. This has the
94 same format as the normal target specification.
95 • --excludefile <filename>: reads in a list of exclude ranges, in the
97 same target format described above. These ranges override any tar‐
98 gets, preventing them from being scanned.
99 • --append-output: causes output to append to file, rather than over‐
101 writing the file.
102 • --iflist: list the available network interfaces, and then exits.
104 • --retries: the number of retries to send, at 1 second intervals.
106 Note that since this scanner is stateless, retries are sent regard‐
107 less if replies have already been received.
108 • --nmap: print help about nmap-compatibility alternatives for these
110 options.
111 • --pcap-payloads: read packets from a libpcap file containing pack‐
113 ets and extract the UDP payloads, and associate those payloads with
114 the destination port. These payloads will then be used when sending
115 UDP packets with the matching destination port. Only one payload
116 will be remembered per port. Similar to --nmap-payloads.
117 • --nmap-payloads <filename>: read in a file in the same format as
119 the nmap file nmap-payloads. This contains UDP payload, so that we
120 can send useful UDP packets instead of empty ones. Similar to
121 --pcap-payloads.
122 • --http-user-agent <user-agent>: replaces the existing user-agent
124 field with the indicated value when doing HTTP requests.
125 • --open-only: report only open ports, not closed ports.
127 • --pcap <filename>: saves received packets (but not transmitted
129 packets) to the libpcap-format file.
130 • --packet-trace: prints a summary of those packets sent and re‐
132 ceived. This is useful at low rates, like a few packets per second,
133 but will overwhelm the terminal at high rates.
134 • --pfring: force the use of the PF_RING driver. The program will
136 exit if PF_RING DNA drvers are not available.
137 • --resume-index: the point in the scan at when it was paused.
139 • --resume-count: the maximum number of probes to send before exit‐
141 ing. This is useful with the --resume-index to chop up a scan and
142 split it among multiple instances, though the --shards option might
143 be better.
144 • --shards <x>/<y>: splits the scan among instances. x is the id for
146 this scan, while y is the total number of instances. For example,
147 --shards 1/2 tells an instance to send every other packet, starting
148 with index 0. Likewise, --shards 2/2 sends every other packet, but
149 starting with index 1, so that it doesn´t overlap with the first
150 example.
151 • --rotate <time>: rotates the output file, renaming it with the cur‐
153 rent timestamp, moving it to a separate directory. The time is
154 specified in number of seconds, like "3600" for an hour. Or, units
155 of time can be specified, such as "hourly", or "6hours", or
156 "10min". Times are aligned on an even boundary, so if "daily" is
157 specified, then the file will be rotated every day at midnight.
158 • --rotate-offset <time>: an offset in the time. This is to accommo‐
160 date timezones.
161 • --rotate-dir <directory>: when rotating the file, this specifies
163 which directory to move the file to. A useful directory is
164 /var/log/masscan.
165 • --seed <integer>: an integer that seeds the random number genera‐
167 tor. Using a different seed will cause packets to be sent in a dif‐
168 ferent random order. Instead of an integer, the string time can be
169 specified, which seeds using the local timestamp, automatically
170 generating a differnet random order of scans. If no seed specified,
171 time is the default.
172 • --regress: run a regression test, returns ´0´ on success and ´1´ on
174 failure.
175 • --ttl <num>: specifies the TTL of outgoing packets, defaults to
177 255.
178 • --wait <seconds>: specifies the number of seconds after transmit is
180 done to wait for receiving packets before exiting the program. The
181 default is 10 seconds. The string forever can be specified to never
182 terminate.
183 • --offline: don´t actually transmit packets. This is useful with a
185 low rate and --packet-trace to look at what packets might´ve been
186 transmitted. Or, it´s useful with --rate 100000000 in order to
187 benchmark how fast transmit would work (assuming a zero-overhead
188 driver). PF_RING is about 20% slower than the benchmark result from
189 offline mode.
190 • -sL: this doesn´t do a scan, but instead creates a list of random
192 addresses. This is useful for importing into other tools. The op‐
193 tions --shard, --resume-index, and --resume-count can be useful
194 with this feature.
195 • --interactive: show the results in realtime on the console. It has
197 no effect if used with --output-format or --output-filename.
198 • --output-format <fmt>: indicates the format of the output file,
200 which can be xml, binary, grepable, list, or JSON. The option
201 --output-filename must be specified.
202 • --output-filename <filename>: the file which to save results to. If
204 the parameter --output-format is not specified, then the default of
205 xml will be used.
206 • -oB <filename>: sets the output format to binary and saves the out‐
208 put in the given filename. This is equivelent to using the --out‐
209 put-format and --output-filename parameters. The option --readscan
210 can then be used to read the binary file. Binary files are much
211 smaller than their XML equivelents, but require a separate step to
212 convert back into XML or another readable format.
213 • -oX <filename>: sets the output format to XML and saves the output
215 in the given filename. This is equivelent to using the --out‐
216 put-format xml and --output-filename parameters.
217 • -oG <filename>: sets the output format to grepable and saves the
219 output in the given filename. This is equivelent to using the
220 --output-format grepable and --output-filename parameters.
221 • -oJ <filename>: sets the output format to JSON and saves the output
223 in the given filename. This is equivelent to using the --out‐
224 put-format json and --output-filename parameters.
225 • -oL <filename>: sets the output format to a simple list format and
227 saves the output in the given filename. This is equivelent to using
228 the --output-format list and --output-filename parameters.
229 • --readscan <binary-files>: reads the files created by the -oB op‐
231 tion from a scan, then outputs them in one of the other formats,
232 depending on command-line parameters. In other words, it can take
233 the binary version of the output and convert it to an XML or JSON
234 format.
235
239 The configuration file uses the same parameter names as on the command‐
240 line, but without the -- prefix, and with an = sign between the name
241 and the value. An example configuration file might be:
242 # targets
246 range = 10.0.0.0/8,192.168.0.0/16
247 range = 172.16.0.0/14
248 ports = 20-25,80,U:53
249 ping = true
250 # adapter
252 adapter = eth0
253 adapter-ip = 192.168.0.1
254 router-mac = 66-55-44-33-22-11
255 # other
257 exclude-file = /etc/masscan/exludes.txt
258 By default, the program will read default configuration from the file
262 /etc/masscan/masscan.conf. This is useful for system-specific settings,
263 such as the --adapter-xxx options. This is also useful for excluded IP
264 addresses, so that you can scan the entire Internet, while skipping
265 dangerous addresses, like those owned by the DoD, and not make an acci‐
266 dental mistake.
267
269 When the user presses ctrl-c, the scan will stop, and the current state
270 of the scan will be saved in the file ´paused.conf´. The scan can be
271 resumed with the --resume option:
272 # masscan --resume paused.conf
276 The program will not exit immediately, but will wait a default of 10
280 seconds to receive results from the Internet and save the results be‐
281 fore exiting completely. This time can be changed with the --wait op‐
282 tion.
283
285 The following example scans all private networks for webservers, and
286 prints all open ports that were found.
287 # masscan 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12 -p80 --open-only
291 The following example scans the entire Internet for DNS servers, grab‐
295 bing their versions, then saves the results in an XML file.
296 # masscan 0.0.0.0/0 --excludefile no-dod.txt -pU:53 --banners --output-filename dns.xml
300 You should be able to import the XML into databases and such.
304 The following example reads a binary scan results file called
306 bin-test.scan and prints results to console.
307 # masscan --readscan bin-test.scan
311 The following example reads a binary scan results file called
315 bin-test.scan and creates an XML output file called bin-test.xml.
316 # masscan --readscan bin-test.scan -oX bin-test.xml
320
324 Let´s say that you want to scan the entire Internet and spread the scan
325 across three machines. Masscan would be launched on all three machines
326 using the following command-lines:
327 # masscan 0.0.0.0/0 -p0-65535 --shard 1/3
331 # masscan 0.0.0.0/0 -p0-65535 --shard 2/3
332 # masscan 0.0.0.0/0 -p0-65535 --shard 3/3
333 An alternative is with the "resume" feature. A scan has an internal in‐
337 dex that goes from zero to the number of ports times then number of IP
338 addresses. The following example shows splitting up a scan into chunks
339 of a 1000 items each:
340 # masscan 0.0.0.0/0 -p0-65535 --resume-index 0 --resume-count 1000
344 # masscan 0.0.0.0/0 -p0-65535 --resume-index 1000 --resume-count 1000
345 # masscan 0.0.0.0/0 -p0-65535 --resume-index 2000 --resume-count 1000
346 # masscan 0.0.0.0/0 -p0-65535 --resume-index 3000 --resume-count 1000
347 A script can use this to split smaller tasks across many other ma‐
351 chines, such as Amazon EC2 instances. As each instance completes a job,
352 the script might send a request to a central coordinating server for
353 more work.
354
356 When scanning TCP using the default IP address of your adapter, the
357 built-in stack will generate RST packets. This will prevent banner
358 grabbing. There are are two ways to solve this. The first way is to
359 create a firewall rule to block that port from being seen by the stack.
360 How this works is dependent on the operating system, but on Linux this
361 looks something like:
362 # iptables -A INPUT -p tcp -i eth0 --dport 61234 -j DROP
366 Then, when scanning, that same port must be used as the source:
370 # masscan 10.0.0.0/8 -p80 --banners --adapter-port 61234
374 An alternative is to "spoof" a different IP address. This IP address
378 must be within the range of the local network, but must not otherwise
379 be in use by either your own computer or another computer on the net‐
380 work. An example of this would look like:
381 # masscan 10.0.0.0/8 -p80 --banners --adapter-ip 192.168.1.101
385 Setting your source IP address this way is the preferred way of running
389 this scanner.
390
392 This scanner is designed for large-scale surveys, of either an organi‐
393 zation, or of the Internet as a whole. This scanning will be noticed by
394 those monitoring their logs, which will generate complaints.
395 If you are scanning your own organization, this may lead to you being
397 fired. Never scan outside your local subnet without getting permission
398 from your boss, with a clear written declaration of why you are scan‐
399 ning.
400 The same applies to scanning the Internet from your employer. This is
402 another good way to get fired, as your IT department gets flooded with
403 complaints as to why your organization is hacking them.
404 When scanning on your own, such as your home Internet or ISP, this will
406 likely cause them to cancel your account due to the abuse complaints.
407 One solution is to work with your ISP, to be clear about precisely what
409 we are doing, to prove to them that we are researching the Internet,
410 not "hacking" it. We have our ISP send the abuse complaints directly to
411 us. For anyone that asks, we add them to our "--excludefile", black‐
412 listing them so that we won´t scan them again. While interacting with
413 such people, some instead add us to their whitelist, so that their
414 firewalls won´t log us anymore (they´ll still block us, of course, they
415 just won´t log that fact to avoid filling up their logs with our
416 scans).
417 Ultimately, I don´t know if it´s possible to completely solve this
419 problem. Despite the Internet being a public, end-to-end network, you
420 are still "guilty until proven innocent" when you do a scan.
421
423 While not listed in this document, a lot of parameters compatible with
424 nmap will also work.
425
427 nmap(8), pcap(3)
428
430 This tool was written by Robert Graham. The source code is available at
431 https://github.com/robertdavidgraham/masscan.
432 January 2014 MASSCAN(8)