Provided by: masscan_1.0.3-95-gb395f18~ds0-2_i386 bug

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)