--- name: "doscan" section: "1" platform: "linux" package: "doscan" version: "0.3.3-1.2" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/doscan" --- # doscan(1) Denial Of Service Capable Auditing of Networks ## 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)](/pcrepattern/3.md) 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)](/printf/3.md). 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)](/bash/1.md), 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)](/sysctl.conf/5.md), 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)](/pcrepattern/3.md), [**sysctl.conf**(5)](/sysctl.conf/5.md) (on GNU/Linux systems), shell documentation for the **ulimit** interface