DOSCAN(1)

📦 version 0.3.3, in debian bookworm, ubuntu jammy

DOSCAN(1) 💖

Okay bestie, this is the manual page for doscan, and it is a lot. Grab a boba, we're doing this. 💅

NAME ✨

doscan — Denial Of Service Capable Auditing of Networks. That's the whole government name, periodt. 👑

SYNOPSIS 🌸

doscan options prefix...

DESCRIPTION 🦋

Okay so doscan is a tool to discover TCP services on your network. It is designed for scanning a single port on a large network. (There are better tools for scanning many ports on a small set of hosts, for example nmap(8).) Not me saying use the right tool for the right job, but here we are. 💅

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). Slay, simple.

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.) Main character energy, honestly. ✨

OPTIONS 💅

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

  • -a timeout, --add-timeout timeout — this sets the timeout (in milliseconds) before new connections are added. It's part of a duo with -A, so read that one too, bestie.
  • -A count, --add-burst count — this sets 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. The vibes are protocol-dependent, iykyk.
  • -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. Fifty is the default, no cap.
  • -E, --no-epoll — Do not use the epoll kernel interface even if it's available (useful for debugging). Sometimes you gotta turn off the fancy kernel thing, bestie.
  • -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. (Okay the typo is in the original, but you get it. 💀)
  • -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. It's giving live updates. 👑
  • -n, --net-errors — Instructs doscan to report network errors even if they prevent a connection. Normally, such errors are suppressed. Not all errors wanna be seen, but this makes them show up. 😭
  • -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 — The effects of this option depend on the protocol module. See the PROTOCOL MODULES section for details.
  • --receive regexp, -r regexp — The effects of this option 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. No connection? Skipped, periodt.
  • -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 options.

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, doscan 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 packet is received. Packets sent to network or broadcast addresses trigger such packets, and poorly implemented UDP services on multi-homed machines answer with a different source IP address.

✨ OUTPUT FORMAT ✨

okay so when doscan is done and about to dip, it prints literally everything it gathered about the scanned prefixes to standard output. You can switch up the whole vibe with --output. The format argument is a string with % substitutions, kinda like printf(3) but make it scanning. Here's every substitution, no skips:

  • %% — a literal percent character.
  • %a — the address of the remote host.
  • %b — the banner returned by the host.
  • %e — the error code as a string, empty if no error happened while scanning the host.

This is either a system error constant (like ECONNREFUSED), or the string unknown (unknown error code). And if --receive is active and the received data doesn't match the regular expression you specified, and no other error occurred, the column contains no match.

  • %E — the numeric error code that goes with the %e error message, or zero if no error happened. Negative error numbers get returned for internal errors (like a failed match against the --receive regular expression).
  • %n — the host name corresponding to the scanned IP address (based on a DNS lookup). Heads up bestie, this slows down reporting a LOT in general. Which is exactly why it's 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 (%).

(yes, %% really is listed twice in the original and we are NOT gatekeeping it, both entries stay 💅)

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 these 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 that 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 🌈

okay these are the real ones, copy-paste energy:

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. Raising it can greatly increase scanning performance. But there are two caveats, and they are not cute: many connections require many sockets, and your system might not support that many. Also, a large number of parallel connections generates significant numbers of packets plus a high CPU load, and both of those can 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, and that 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 — meaning they will not be reported even though they are running a service on the scanned port. So 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 🦋

and that's the whole page bestie, you ate it 🫶 this version is dated 2003-07-27 and it lives under the name DOSCAN(1) — go scan something responsibly, mwah 💖✨

📦 where this page comes from