Provided by: doscan_0.3.1-3_amd64 bug

NAME

       doscan - Denial Of Service Capable Auditing of Networks

SYNOPSIS

       doscan options prefix...

DESCRIPTION

       doscan  is a tool to discover TCP services ony our network.  It is designed for scanning a
       single ports on a large network.  (There are better tools for scanning  many  ports  on  a
       small set of hosts, for example nmap(8).)

       The  prefix  parameter  instructs  doscan  to  scan  all addresses in this prefix.  Prefix
       notation is, as usual, A.B.C.D/L, where A.B.C.D is an IP address in dotted-quad  notation,
       and  L  is a prefix length from 1 to 32.  If the /L part is omitted, /32 is assumed (and a
       single host is scanned).

       doscan uses a random scatter technology to distribute the load across the network.  Within
       a  given  prefix,  hosts  are  not  scanned  sequentially,  but  in  a random-looking, but
       reproducible order.  As a result, doscan will not stress-test the network edge  (just  the
       next hop).  (The prefixes themselves are scanned in order.)

OPTIONS

       The --port option is mandatory, all other options are optional.

       -a timeout, --add-timeout timeout
       -A count, --add-burst count
              These  options  specify  the  timeout  (in milliseconds) before new connections are
              added, and the number of new connections or hosts   to  add  in  one  burst.   Each
              timeout  millisecond,  count  new  hosts  are  contacted.   (The  per-host  timeout
              controlled by the --timeout option is independent.  It specifies the  timeout  once
              the first packet has been sent.)

       -b count, --banner count
              doscan  reads  at  most count bytes from the remote host.  The exact effect of this
              option varies among protocol modules, see the PROTOCOL MODULES section for details.

       -c count, --connections count
              At most count connections are  established  in  parallel.  See  CAVEATS  below  for
              problems  resulting  from  system  file  descriptor  limits,  and  instructions for
              choosing  this  parameter.   By  default,  at  most  50  parallel  connections  are
              established.

       -E, --no-epoll
              Do  not  use  the  epoll  kernel  interface  even  if  it's  available  (useful for
              debugging).

       -f, --file name
              doscan reads prefixes from the file name, in addition to  the  command  line.   The
              file  shall contain one prefix per line.  See the DESCRIPTION section above for the
              prefix format.  To better distribute scanning of long prefix lists,  all  prefixies
              are reorded randomly if the --file option is used.

       -i, --indicator
              Display a progress indicator.  If doscan is invoked with this option, the number of
              connections which have been established so far, the total number of addresses to be
              scanned,  the  number  of currently active connections, and the number of hosts for
              which a report entry has been generated are displayed periodically.

       -n, --net-errors
              Instructs doscan to report network  errors  even  if  they  prevent  a  connection.
              Normally, such errors are suppressed.

       -o format, --output format
              This  option  changes the format which doscan uses to report its findings.  See the
              OUTPUT FORMAT section below for details.

       -p port, --port port
              The --port option controls to which TCP port doscan connects when scanning a host.

       --protocol Istring, -P Istring
              Chooses  the  protocol  module  string.   See  the  PROTOCOL  MODULES  section  for
              information on available protocol modules.

       --send string, -s string
       --receive regexp, -r regexp
              The  effects  of  these  options  depend  on the protocol module.  See the PROTOCOL
              MODULES section for details.

       --style style, -S style
              This option controls the output style.  See the OUTPUT FORMAT section for details.

       -t timeout, --timeout timeout
              This option sets the connect timeout to timeout milliseconds.  If this time  passes
              without a successfully established connection, doscan skips the hosts.

       -v, --verbose
              Turn on additional reporting to standard error.

       -h, --help
              Display help message and exit.

       -V, --version
              Output version information and exit.

PROTOCOL MODULES

       doscan supports several protocol modules.  By default, the generic tcp module is used, but
       you can choose another module using the --protocol option.  The effect  of  the  --banner,
       --send and --receive options depends on the protocol module.  Available modules include:

       http   This  module  causes doscan to connect to HTTP servers, send a request, and collect
              the server identification from the response.

              The --banner option specifies the maximum receive buffer size.  It defaults to 4000
              bytes.

              The --send option specifies the request that is send to the server.  The string can
              include C escape sequences to send control characters.  By default, the request GET
              / HTTP/1.0\r\n\r\n (that is, GET / HTTP/1.0 followed by the four characters CR, LF,
              CR, LF) is sent.

              The --receive option is not supported by this protocol module.

       http_proxy
              This protocol module probes  hosts  for  open  HTTP  proxies.   The  --port  option
              controls the port that is probed.  The required --receive option must be an integer
              in the range from 1 to 65534, the number specifies the port on which doscan listens
              for  the  connections  from open proxies.  The required --send option specifies the
              HTTP request method, either "GET" or "CONNECT".

              The --banner option is not supported by this protocol module.

              Warning: In the worst case, the amount of file descriptors is  slightly  more  than
              twice  the  number of parallel connections given by the --connections options.  The
              additional file descriptors are used by doscan's HTTP server component  to  process
              the connections from open proxies.

              See the EXAMPLES section for some convenient combinations of those otions.

       ident_check
              This  protocol  module  reports  hosts  which  have  TCP  service  listening on the
              specified port which is not a proper IDENT/AUTH daemon.  It is most useful  with  a
              --port  113  command  line  argument.   None  of the --banner, --receive and --send
              options are supported.

       tcp    This module is intended for generic TCP service probing and fingerprinting.

              The --banner option controls  the  maximum  length  of  banner  strings  which  are
              collected.   If  its  argument is zero or if the option is not specified, no banner
              strings are collected.  In this case, doscan closes connections  immediately  after
              they have been established (which results in an increased scanning rate).

              After  establishing  a connection, doscans sends the string specified by the --send
              option to the remote host.  The string can contain the  usual  C  escape  sequences
              (including \000), to send non-printable characters.

              The  --receive  option  specifies  a Perl-compatible regular expression (PCRE), and
              doscan uses it to analyze  the  data  returned  by  a  remote  host.   The  regular
              expression  may contain at least one capturing subpattern, it is always anchored at
              the beginning  of  the  received  data.  The  character  .   (period)  matches  all
              characters  (including  newline).   $  (dollar  sign)  matches  the very end of the
              received data (which may, however, still be incomplete).   See  pcrepattern(3)  for
              details about the syntax of Perl-compatible regular expression.

              The  --receive  regular expression is used by doscan for several purposes.  If data
              is received from a remote host, and if the regular expression ends with  $,  doscan
              immediately  closes  the  connection if all the data received so far from this host
              matches the regular expression.   (doscan  assumes  that  the  reply  is  complete;
              increased  scanning  speed is the result.)  When a connection is terminated for any
              reason, doscan checks if the regular expression matches the collected data.  If  it
              doesn't, a no match error is recorded (if no other error occured).  If it does, and
              the  regular  expression  contains  a  capturing  subpattern,  that  subpattern  is
              recorded.  Otherwise, the whole data is recorded.

              In  order  to  use the --receive option, you have to specify the --banner option as
              well.

       udp    This module is a generic UDP scanner, as far such a thing is possible.  It sends up
              to five UDP packets (whose payload is controlled by the mandatory --send option) to
              the specified port.  Replies are collected.  The --banner option  is  implicit  and
              set  to the maximum payload size. Retransmission is stopped when the first reply is
              received.

              In verbose mode (with both --verbose and  --net-errors  options),  a  warning  like
              "stray UDP packet from 192.0.2.4:7" is printed to standard error when an unexpected
              UDP packets is received.  Packets to sent to network or broadcast adresses  trigger
              such  packets,  and  poorly implemented UDP services on multi-homed machines answer
              with a different source IP address.

OUTPUT FORMAT

       doscan prints all gathered data about scanned prefixes to standard output, just before the
       program  terminates.   The  output  format  can  be changed with the --output option.  The
       format argument of this option is a  string  which  includes  %  substitions,  similar  to
       printf(3).  The following substitions are supported

       %%     A literal percent character.

       %a     The address of the remote host.

       %b     The banner return by the host.

       %e     The error code as a string, empty if no error occurred while scanning the host.

              This  is  either  a  system  error  constant  (such as ECONNREFUSED), or the string
              unknown (unknown error code).  If the --receive option is active and  the  received
              data  does  not  match  the  specified  regular  expresion,  and no other error has
              occured, the column contains no match.

       %E     The numeric error code corresponding to the %e error message, or zero if  no  error
              occurred.  Negativ error numbers are returned for internal errors (such as a failed
              match against the --receive regular expression).

       %n     The host name corresponding to the scanned IP address  (based  on  a  DNS  lookup).
              Note  that this slows down reporting a lot, in general.  For this reason, it is not
              recommended to use %n together with --style unsorted.

       %N     A verbatim ASCII LF (newline) character.

       %r     The time when the information was gathered, measured in seconds since the  scanning
              started.

       %t     The time when the information was gathered, in local time.

       %T     Same as %t, but in UTC (also known as GMT).

       %%     A verbatim percent sign (%).

       The  default  value  for  the --output option is %T\t%a\t%e\t%b, where \t denotes an ASCII
       HTAB character.

       The --style or -S option supports the following arguments:

       sort-by-host
              The output is sorted by the IP address of the scanned host. (This is the default.)

       unsorted
              The output is not sorted and appears in the order the hosts responded.

              Caution: Do not use this style together with an --output  argument  which  includes
              %n,  and  do  not  pipe  the  output  of  doscan to a process which cannot read its
              standard input quickly.  Output is performed synchronously, and if it  is  delayed,
              this might impact the scanning activity.

       In  all  cases  except  unsorted,  output  is  delayed  just before the termination of the
       program.

EXAMPLES

              doscan --banner 100 --port 13 192.0.2.1

       Prints the time on the host 192.0.2.1 (if it runs a daytime server).

              doscan --banner 100 --receive '(.*)\n$' --port 22 192.0.2.0/24

       Scan for SSH servers and record the banners (usually containing version information  about
       the SSH server).

              doscan --banner 200 --receive '(.*?)\r?\n$' --port 25 192.0.2.0/24

       Scan  for  SMTP  servers  and record their greeting messages.  Works for FTP as well, with
       --port 21 instead of --port 25.

              doscan --banner 2000 --send 'GET / HTTP/1.0\r\n\r\n' \
                 --receive '.*?\nServer: *([^\r\n]*) *\r?\n.*$' \
                 --port 80 192.0.2.0/24

       Scan for HTTP servers and record their version strings.

              doscan --protocol http_proxy --port 3128 \
                 --send GET --receive 80 192.0.2.0/24

       Scan for open proxies on TCP port 3128, using the GET HTTP request method.  Try to connect
       back to port 80 on the scanning host.

       It  is  recommended  that  you  use  port  80 for the listening port if you scan using GET
       requests.  For CONNECT requests, port 443 should be used (see below).  Some administrators
       might restrict CONNECT to TCP port 443 (or filter it for the GET request method), so these
       choices give best results.

              doscan --protocol http_proxy --port 8080 \
                 --send CONNECT --receive 443 192.0.2.0/24

       Scan for open proxies on TCP port 8080, using the CONNECT HTTP  request  method.   Try  to
       connect back to port 443 on the scanning host.

CAVEATS

       The most important option for tuning is --connections.  Increasing this option can greatly
       increase scanning performance.  However, there a two  caveats:  Many  connections  require
       many  sockets,  and  your  system might not support so many of them.  Furthermore, a large
       number of parallel connections generates significant numbers of packets, and  a  high  CPU
       load, which can both lead to spurious connection failures (false negatives).

       To  increase  the number of connections your system can process, you usually have to raise
       the corresponding ulimit value  in  your  shell,  which  requires  root  privileges.   For
       example, in bash(1), you can invoke

              ulimit -n 10030

       to  raise the descriptor limit to 10030.  You can then pass --connections 10000 to doscan.
       (Some file descriptors are not used for scanning, but have to  be  open  nonetheless,  and
       count towards the ulimit -n limit.)

       On  Linux-based systems, you might have to adjust some sysctl values which control system-
       wide descriptor limits.  Refer to sysctl.conf(5), the Documentation directory in the Linux
       source tree, or the source code itself for details.

       Note,  however,  that  if you increase the number of parallel connections beyond a certain
       value, you will lose some hosts, that is they will not be reported even  though  they  are
       running  a  service on the scanned port.  Therefore, you should watch both network and CPU
       utilization to detect bottlenecks.  Although the  random  scatter  technique  employed  by
       doscan tries to split the load across your whole network, this obviously fails if the next
       hop cannot bear the traffic.

AUTHOR

       doscan was written by Florian Weimer.

SEE ALSO

       nmap(8), pcrepattern(3), sysctl.conf(5) (on GNU/Linux systems),  shell  documentation  for
       the ulimit interface

                                            2003-07-27                                  DOSCAN(1)