1MASSCAN(8)                                                          MASSCAN(8)
2
3
4

NAME

6       masscan - Fast scan of the Internet
7

SYNOPSIS

9       masscan <ip addresses/ranges> -p ports options
10

DESCRIPTION

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

OPTIONS

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
28--range <ip/range>: the same as target range spec described  above,
29           except as a named parameter instead of an unnamed one.
30
31-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
37--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
41--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
50-c <filename>, --conf <filename>: reads in  a  configuration  file.
51           The format of the configuration file is described below.
52
53--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
57--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
61-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
65--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
71--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
80--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
84--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
88--ping: indicates that the scan should include  an  ICMP  echo  re‐
89           quest. This may be included with TCP and UDP scanning.
90
91--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
96--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
100--append-output: causes output to append to file, rather than over‐
101           writing the file.
102
103--iflist: list the available network interfaces, and then exits.
104
105--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
109--nmap:  print help about nmap-compatibility alternatives for these
110           options.
111
112--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
118--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
123--http-user-agent  <user-agent>:  replaces  the existing user-agent
124           field with the indicated value when doing HTTP requests.
125
126--open-only: report only open ports, not closed ports.
127
128--pcap <filename>: saves  received  packets  (but  not  transmitted
129           packets) to the libpcap-format file.
130
131--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
135--pfring:  force  the  use  of the PF_RING driver. The program will
136           exit if PF_RING DNA drvers are not available.
137
138--resume-index: the point in the scan at when it was paused.
139
140--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
145--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
152--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
159--rotate-offset  <time>: an offset in the time. This is to accommo‐
160           date timezones.
161
162--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
166--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
173--regress: run a regression test, returns ´0´ on success and ´1´ on
174           failure.
175
176--ttl <num>: specifies the TTL of  outgoing  packets,  defaults  to
177           255.
178
179--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
184--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
191-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
196--interactive: show the results in realtime on the console. It  has
197           no effect if used with --output-format or --output-filename.
198
199--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
203--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
207-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
214-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
218-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
222-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
226-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
230--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
236
237

CONFIGURATION FILE FORMAT

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
243
244
245           # 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
251           # adapter
252           adapter = eth0
253           adapter-ip = 192.168.0.1
254           router-mac = 66-55-44-33-22-11
255
256           # other
257           exclude-file = /etc/masscan/exludes.txt
258
259
260
261       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

CONTROL-C BEHAVIOR

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
273
274
275           # masscan --resume paused.conf
276
277
278
279       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

SIMPLE EXAMPLES

285       The following example scans all private networks  for  webservers,  and
286       prints all open ports that were found.
287
288
289
290           # masscan 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12 -p80 --open-only
291
292
293
294       The  following example scans the entire Internet for DNS servers, grab‐
295       bing their versions, then saves the results in an XML file.
296
297
298
299           # masscan 0.0.0.0/0 --excludefile no-dod.txt -pU:53 --banners --output-filename dns.xml
300
301
302
303       You should be able to import the XML into databases and such.
304
305       The  following  example  reads  a  binary  scan  results  file   called
306       bin-test.scan and prints results to console.
307
308
309
310           # masscan --readscan bin-test.scan
311
312
313
314       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
317
318
319           # masscan --readscan bin-test.scan -oX bin-test.xml
320
321
322

ADVANCED EXAMPLES

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
328
329
330           # 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
334
335
336       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
341
342
343           # 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
348
349
350       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

SPURIOUS RESETS

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
363
364
365           # iptables -A INPUT -p tcp -i eth0 --dport 61234 -j DROP
366
367
368
369       Then, when scanning, that same port must be used as the source:
370
371
372
373           # masscan 10.0.0.0/8 -p80 --banners --adapter-port 61234
374
375
376
377       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
382
383
384           # masscan 10.0.0.0/8 -p80 --banners --adapter-ip 192.168.1.101
385
386
387
388       Setting your source IP address this way is the preferred way of running
389       this scanner.
390

ABUSE COMPLAINTS

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
396       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
401       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
405       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
408       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
418       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

COMPATIBILITY

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

SEE ALSO

427       nmap(8), pcap(3)
428

AUTHORS

430       This tool was written by Robert Graham. The source code is available at
431       https://github.com/robertdavidgraham/masscan.
432
433
434
435                                 January 2014                       MASSCAN(8)
Impressum