doscan - Denial Of Service Capable Auditing of Networks
doscan options prefix...
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
parameter instructs doscan
to scan all addresses in
this prefix. Prefix notation is, as usual, A.B.C.D/L
is an IP address in dotted-quad notation, and L
prefix length from 1 to 32. If the /L
part is omitted, /32
assumed (and a single host is scanned).
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
stress-test the network edge (just the next hop). (The prefixes themselves are
scanned in order.)
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
- -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
- -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
- --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.
supports several protocol modules. By default, the generic
module is used, but you can choose another module using the
option. The effect of the --banner
options depends on the protocol module. Available modules
- This module causes doscan to connect to HTTP
servers, send a request, and collect the server identification from the
- 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
- 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
- The --banner option is not supported by this
- 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.
- 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
- This module is intended for generic TCP service probing and
- 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
- 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.
- 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
- 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.
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
following substitions are supported
- A literal percent character.
- The address of the remote host.
- The banner return by the host.
- 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.
- 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
- 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.
- A verbatim ASCII LF (newline) character.
- The time when the information was gathered, measured in
seconds since the scanning started.
- The time when the information was gathered, in local
- 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
denotes an ASCII HTAB character.
option supports the following arguments:
- The output is sorted by the IP address of the scanned host.
(This is the default.)
- The output is not sorted and appears in the order the hosts
- 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.
- 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
Scan for SSH servers and record the banners (usually containing version
information about the SSH server).
- doscan --banner 200 --receive '(.*?)\r?\n$' --port 25
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.
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
privileges. For example, in bash
(1), you can invoke
- ulimit -n 10030
to raise the descriptor limit to 10030. You can then pass --connections
. (Some file descriptors are not used for scanning,
but have to be open nonetheless, and count towards the ulimit -n
On Linux-based systems, you might have to adjust some sysctl
control system-wide descriptor limits. Refer to sysctl.conf
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.
was written by Florian Weimer.
(5) (on GNU/Linux
systems), shell documentation for the ulimit