Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MASSCAN(8)							    MASSCAN(8)

       masscan - Fast scan of the Internet

       masscan <ip addresses/ranges> -p	ports options

       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.

       o   <ip/range>: 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 "". The
	   second is a range like "". The third is  a  CIDR
	   address,  like  "".	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,

       o   --range <ip/range>: the same	as target range	spec described	above,
	   except as a named parameter instead of an unnamed one.

       o   -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

       o   --banners:  specifies  that	banners	 should	 be grabbed, like HTTP
	   server versions, HTML title fields, and so forth. Only a few	proto-
	   cols	are supported.

       o   --rate  <packets-per-second>: 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.

       o   -c <filename>, --conf <filename>: reads in  a  configuration	 file.
	   The format of the configuration file	is described below.

       o   --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.

       o   --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'.

       o   -e  <ifname>,  --adapter <ifname>: 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.

       o   --adapter-ip	 <ip-address>:	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.

       o   --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 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

       o   --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.

       o   --router-mac	<mac address>: send packets to this MAC	address	as the
	   destination.	If not specified, then the gateway address of the net-
	   work	interface will be ARPed.

       o   --ping: indicates that the scan should include  an  ICMP  echo  re-
	   quest. This may be included with TCP	and UDP	scanning.

       o   --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.

       o   --excludefile <filename>: 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.

       o   --append-output: causes output to append to file, rather than over-
	   writing the file.

       o   --iflist: list the available	network	interfaces, and	then exits.

       o   --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.

       o   --nmap:  print help about nmap-compatibility	alternatives for these

       o   --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.

       o   --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

       o   --http-user-agent  <user-agent>:  replaces  the existing user-agent
	   field with the indicated value when doing HTTP requests.

       o   --open-only:	report only open ports,	not closed ports.

       o   --pcap <filename>: saves  received  packets	(but  not  transmitted
	   packets) to the libpcap-format file.

       o   --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.

       o   --pfring:  force  the  use  of the PF_RING driver. The program will
	   exit	if PF_RING DNA drvers are not available.

       o   --resume-index: the point in	the scan at when it was	paused.

       o   --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
	   be better.

       o   --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

       o   --rotate <time>: rotates the	output file, renaming it with the cur-
	   rent	 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.

       o   --rotate-offset  <time>: an offset in the time. This	is to accommo-
	   date	timezones.

       o   --rotate-dir	<directory>: when rotating the	file,  this  specifies
	   which  directory  to	 move  the  file  to.  A  useful  directory is

       o   --seed <integer>: an	integer	that seeds the random  number  genera-
	   tor.	Using a	different seed will cause packets to be	sent in	a dif-
	   ferent 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.

       o   --regress: run a regression test, returns '0' on success and	'1' on

       o   --ttl <num>:	specifies the TTL of  outgoing	packets,  defaults  to

       o   --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

       o   --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.

       o   -sL:	 this  doesn't do a scan, but instead creates a	list of	random
	   addresses. This is useful for importing into	other tools.  The  op-
	   tions  --shard,  --resume-index,  and  --resume-count can be	useful
	   with	this feature.

       o   --interactive: show the results in realtime on the console. It  has
	   no effect if	used with --output-format or --output-filename.

       o   --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.

       o   --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.

       o   -oB <filename>: sets	the output format to binary and	saves the out-
	   put in the given filename. This is equivelent to using  the	--out-
	   put-format  and --output-filename parameters. The option --readscan
	   can then be used to read the	binary file.  Binary  files  are  much
	   smaller  than their XML equivelents,	but require a separate step to
	   convert back	into XML or another readable format.

       o   -oX <filename>: sets	the output format to XML and saves the	output
	   in  the  given  filename.  This  is	equivelent to using the	--out-
	   put-format xml and --output-filename	parameters.

       o   -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.

       o   -oJ <filename>: sets	the output format to JSON and saves the	output
	   in  the  given  filename.  This  is	equivelent to using the	--out-
	   put-format json and --output-filename parameters.

       o   -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.

       o   --readscan <binary-files>: reads the	files created by the  -oB  op-
	   tion	 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

       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:

	   # targets
	   range =,
	   range =
	   ports = 20-25,80,U:53
	   ping	= true

	   # adapter
	   adapter = eth0
	   adapter-ip =
	   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 acci-
       dental mistake.

       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 -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 --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 -p0-65535 --shard 1/3
	   # masscan -p0-65535 --shard 2/3
	   # masscan -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 -p0-65535 --resume-index	0 --resume-count 1000
	   # masscan -p0-65535 --resume-index	1000 --resume-count 1000
	   # masscan -p0-65535 --resume-index	2000 --resume-count 1000
	   # masscan -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
       more work.

       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	-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	-p80 --banners --adapter-ip

       Setting your source IP address this way is the preferred	way of running
       this scanner.

       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.

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

       nmap(8),	pcap(3)

       This tool was written by	Robert Graham. The source code is available at

				 January 2014			    MASSCAN(8)


Want to link to this manual page? Use this URL:

home | help