.\" doscan - Denial Of Service Capable Auditing of Networks
.\" Copyright (C) 2003 Florian Weimer
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
.\"
.TH DOSCAN 1 2003-07-27 "" ""
.SH NAME
doscan \- Denial Of Service Capable Auditing of Networks
.SH SYNOPSIS
.B doscan
.I options prefix...
.SH DESCRIPTION
.B 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
.BR nmap "(8).)"
.PP
The
.I prefix
parameter instructs
.B doscan
to scan all addresses in this prefix.  Prefix notation is, as usual,
.IR A.B.C.D/L ,
where
.I A.B.C.D
is an IP address in dotted-quad notation, and
.I L
is a prefix length from 1 to 32.  If the
.I /L
part is omitted,
.I /32
is assumed (and a single host is scanned).
.PP
.B 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,
.B doscan
will not stress-test the network edge (just the next hop).
(The prefixes themselves are scanned in order.)
.SH OPTIONS
The
.B --port
option is mandatory, all other options are optional.
.TP
.B -a \fItimeout\fP, --add-timeout \fItimeout\fP
.PD 0
.TP
.B -A \fIcount\fP, --add-burst \fIcount\fP
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
.I timeout
millisecond,
.I count
new hosts are contacted.  (The per-host timeout controlled by the
.B --timeout
option is independent.  It specifies the timeout once the first packet
has been sent.)
.PD
.TP
.B -b \fIcount\fP, --banner \fIcount\fP
.B doscan
reads at most
.I count
bytes from the remote host.  The exact effect of this option varies
among protocol modules, see the
.SM
.B "PROTOCOL MODULES"
section for details.
.TP
.B -c \fIcount\fP,  --connections \fIcount\fP
At most
.I count
connections are established in parallel. See
.SM
.B 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.
.TP
.B -E, --no-epoll
Do not use the
.B epoll
kernel interface even if it's available (useful for debugging).
.TP
.B -f, --file \fIname\fP
.B doscan
reads prefixes from the file
.IR name ,
in addition to the command line.  The file shall contain one prefix
per line.  See the
.SM
.B DESCRIPTION
section above for the prefix format.  To better distribute scanning of
long prefix lists, all prefixies are reorded randomly if the
.B --file
option is used.
.TP
.B -i, --indicator
Display a progress indicator.  If
.B 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.
.TP
.B -n, --net-errors
Instructs
.B doscan
to report network errors even if they prevent a connection.  Normally,
such errors are suppressed.
.TP
.B -o \fIformat\fP, --output \fIformat\fP
This option changes the format which
.B doscan
uses to report its findings.  See the
.SM
.B "OUTPUT FORMAT"
section below for details.
.TP
.B -p \fIport\fP, --port \fIport\fP
The
.B --port
option controls to which TCP port
.B doscan
connects when scanning a host.
.TP
.B --protocol \Istring\fP, -P \Istring\fP
Chooses the protocol module
.IR string .
See the
.SM
.B "PROTOCOL MODULES"
section for information on available protocol modules.
.TP
.B --send \fIstring\fP, -s \fIstring\fP
.PD 0
.TP
.B --receive \fIregexp\fP, -r \fIregexp\fP
.PD
The effects of these options depend on the protocol module.  See the
.SM
.B "PROTOCOL MODULES"
section for details.
.TP
.B --style \fIstyle\fP, -S \fIstyle\fP
This option controls the output style.  See the
.SM
.B "OUTPUT FORMAT"
section for details.
.TP
.B -t \fItimeout\fP, --timeout \fItimeout\fP
This option sets the connect timeout to
.I timeout
milliseconds.  If this time passes without a successfully established
connection,
.B doscan
skips the hosts.
.TP
.B -v, --verbose
Turn on additional reporting to standard error.
.TP
.B -h, --help
Display help message and exit.
.TP
.B -V, --version
Output version information and exit.
.SH "PROTOCOL MODULES"
.B doscan
supports several protocol modules.  By default, the generic
.B tcp
module is used, but you can choose another module using the
.B --protocol
option.  The effect of the
.BR --banner ,
.BR --send
and
.B --receive
options depends on the protocol module.  Available modules include:
.TP
.B http
This module causes
.B doscan
to connect to HTTP servers, send a request, and collect the server
identification from the response.
.IP
The
.B --banner
option specifies the maximum receive buffer size.  It defaults to 4000
bytes.
.IP
.B
The
.B --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
.B GET / HTTP/1.0\er\en\er\en
(that is,
.B GET / HTTP/1.0
followed by the four characters CR, LF, CR, LF) is sent.
.IP
The
.B --receive
option is not supported by this protocol module.
.TP
.B http_proxy
This protocol module probes hosts for open HTTP proxies.  The
.B --port
option controls the port that is probed.  The required
.B --receive
option must be an integer in the range from 1 to 65534, the number
specifies the port on which
.B doscan
listens for the connections from open proxies.  The required
.B --send
option specifies the HTTP request method, either "GET" or "CONNECT".
.IP
The
.B --banner
option is not supported by this protocol module.
.IP
.B Warning:
In the worst case, the amount of file descriptors is slightly more
than twice the number of parallel connections given by the
.B --connections
options.  The additional file descriptors are used by
.BR doscan 's
HTTP server component to process the connections
.I from
open proxies.
.IP
See the
.SM
.B "EXAMPLES"
section for some convenient combinations of those otions.
.TP
.B ident_check
This protocol module reports hosts which have TCP service listening
on the specified port which is
.I not
a proper IDENT/AUTH daemon.
It is most useful with a
.B --port 113
command line argument.
None of the
.BR --banner ,
.B --receive
and
.B --send
options are supported.
.TP
.B tcp
This module is intended for generic TCP service probing and
fingerprinting.
.IP
The
.B --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,
.B doscan
closes connections immediately after they have been established
(which results in an increased scanning rate).
.IP
After establishing a connection,
.B doscans
sends the string specified by the
.B --send
option to the remote host.  The string can contain the usual C escape
sequences (including
.BR \e000 ),
to send non-printable characters.
.IP
The
.B --receive
option specifies a Perl-compatible regular expression (PCRE),
and
.B 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
.B .
(period) matches all characters (including newline).
.B $
(dollar sign) matches the very end of the received data (which may,
however, still be incomplete).  See
.BR pcrepattern (3)
for details about the syntax of Perl-compatible regular expression.
.IP
The
.B --receive
regular expression is used by
.B doscan
for several purposes.  If data is received from a remote host, and if
the regular expression ends with
.BR $ ,
.B doscan
immediately closes the connection if all the data received so far from
this host matches the regular expression.
.RB ( doscan
assumes that the reply is complete; increased scanning speed is the
result.)  When a connection is terminated for any reason,
.B doscan
checks if the regular expression matches the collected data.  If it
doesn't, a
.B 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.
.IP
In order to use the
.B --receive
option, you have to specify the
.B --banner
option as well.
.TP
.B 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
.B --send
option) to the specified port.  Replies are collected.  The
.B --banner
option is implicit and set to the maximum payload size. Retransmission
is stopped when the first reply is received.
.IP
In verbose mode (with both
.B --verbose
and
.B --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.
.SH "OUTPUT FORMAT"
.B doscan
prints all gathered data about scanned prefixes to standard output,
just before the program terminates.  The output format can be changed
with the
.B --output
option.  The
.I format
argument of this option is a string which includes
.B %
substitions, similar to
.BR printf (3).
The following substitions are supported
.TP
.B %%
A literal percent character.
.TP
.B %a
The address of the remote host.
.TP
.B %b
The banner return by the host.
.TP
.B %e
The error code as a string, empty if no error occurred while scanning
the host.
.IP
This is either a system error constant (such as
ECONNREFUSED), or the string
.B unknown
(unknown error code).
If the
.B --receive
option is active and the received data does not match the specified
regular expresion, and no other error has occured, the column contains
.BR "no match" .
.TP
.B %E
The numeric error code corresponding to the
.B %e
error message, or zero if no error occurred.  Negativ error numbers
are returned for internal errors (such as a failed match against the
.B --receive
regular expression).
.TP
.B %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
.B %n
together with
.BR "--style unsorted" .
.TP
.B %N
A verbatim ASCII LF (newline) character.
.TP
.B %r
The time when the information was gathered, measured in seconds since
the scanning started.
.TP
.B %t
The time when the information was gathered, in local
time.
.TP
.B %T
Same as
.BR %t ,
but in UTC (also known as GMT).
.TP
.B %%
A verbatim percent sign (%).
.PP
The default value for the
.B --output
option is
.BR %T\et%a\et%e\et%b ,
where
.B \et
denotes an ASCII HTAB character.
.PP
The
.B --style
or
.B -S
option supports the following arguments:
.TP
.B sort-by-host
The output is sorted by the IP address of the scanned host. (This is
the default.)
.TP
.B unsorted
The output is not sorted and appears in the order the hosts responded.
.IP
Caution: Do not use this style together with an
.B --output
argument which includes
.BR %n ,
and do not pipe the output of
.B 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.
.PP
In all cases except
.BR unsorted ,
output is delayed just before the termination of the program.
.SH EXAMPLES
.IP
.B doscan --banner 100 --port 13 192.0.2.1
.PP
Prints the time on the host 192.0.2.1 (if it runs a daytime server).
.IP
.B doscan --banner 100 --receive '(.*)\en$' --port 22 192.0.2.0/24
.PP
Scan for SSH servers and record the banners (usually containing
version information about the SSH server).
.IP
.B doscan --banner 200 --receive '(.*?)\er?\en$' --port 25 192.0.2.0/24
.PP
Scan for SMTP servers and record their greeting messages.  Works for
FTP as well, with
.B --port 21
instead of
.BR "--port 25" .
.IP
.PD 0
.B doscan --banner 2000 --send 'GET / HTTP/1.0\er\en\er\en' \e
.IP "" 1in
.B --receive '.*?\enServer: *([^\er\en]*) *\er?\en.*$' \e
.IP "" 1in
.B --port 80 192.0.2.0/24
.PD
.PP
Scan for HTTP servers and record their version strings.
.IP
.PD 0
.B doscan --protocol http_proxy --port 3128 \e
.IP "" 1in
.B --send GET --receive 80 192.0.2.0/24
.PD
.PP
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.
.PP
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.
.IP
.PD 0
.B doscan --protocol http_proxy --port 8080 \e
.IP "" 1in
.B --send CONNECT --receive 443 192.0.2.0/24
.PD
.PP
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.
.SH CAVEATS
The most important option for tuning is
.BR --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).
.PP
To increase the number of connections your system can process, you
usually have to raise the corresponding
.B ulimit
value in your shell, which requires
.B root
privileges.  For example, in
.BR bash "(1),"
you can invoke
.IP
.B ulimit -n 10030
.PP
to raise the descriptor limit to 10030.  You can then pass
.B --connections 10000
to
.BR doscan .
(Some file descriptors are not used for scanning, but have to be open
nonetheless, and count towards the
.B ulimit -n
limit.)
.PP
On Linux-based systems, you might have to adjust some
.B sysctl
values which control system-wide descriptor limits.
Refer to
.BR sysctl.conf "(5),"
the
.B Documentation
directory in the Linux source tree, or the source code itself for
details.
.PP
Note, however, that if you increase the number of parallel
connections beyond a certain value, you will
.I 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
.B doscan
tries to split the load across your whole network, this obviously
fails if the next hop cannot bear the traffic.
.SH AUTHOR
.B doscan
was written by Florian Weimer.
.SH "SEE ALSO"
.BR nmap "(8),"
.BR pcrepattern "(3),"
.BR sysctl.conf "(5) (on GNU/Linux systems),"
shell documentation for the
.B ulimit
interface

\" arch-tag: 1a72ffd2-3d51-4e2b-b6ad-616cfc53df75