Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DOSCAN(1)							     DOSCAN(1)

       doscan -	Denial Of Service Capable Auditing of Networks

       doscan options prefix...

       doscan  is  a tool to discover TCP services on your network.  It	is de-
       signed for scanning a single ports on a large network.  (There are bet-
       ter  tools for scanning many ports on a small set of hosts, for example

       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

       doscan uses a random scatter technology to distribute the  load	across
       the  network.   Within  a  given	 prefix, hosts are not scanned sequen-
       tially, 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.)

       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 ex-
	      act 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 de-
	      fault, 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  re-
	      orded 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  connec-
	      tion, 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.

       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 de-
       pends on	the protocol module.  Available	modules	include:

       http   This module causes doscan	to connect to HTTP servers, send a re-
	      quest, 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 con-
	      trol 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.

	      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 de-
	      scriptors	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  lis-
	      tening  on  the  specified port which is not a proper IDENT/AUTH
	      daemon.  It is most useful with a	--port 113 command line	 argu-
	      ment.   None  of	the --banner, --receive	and --send options are

       tcp    This module is intended for generic TCP service probing and fin-

	      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	speci-
	      fied 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 expres-
	      sion  (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 charac-
	      ters  (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-compati-
	      ble 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 subpat-
	      tern, that subpattern is recorded.  Otherwise, the whole data is

	      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" 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 ma-
	      chines answer with a different source IP address.

       doscan prints all gathered data about scanned prefixes to standard out-
       put,  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	speci-
	      fied regular expresion, and no other error has occured, the col-
	      umn 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 --re-
	      ceive 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  to-
	      gether 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:

	      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  re-

	      Caution:	Do  not	use this style together	with an	--output argu-
	      ment 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 im-
	      pact the scanning	activity.

       In  all cases except unsorted, output is	delayed	just before the	termi-
       nation of the program.

	      doscan --banner 100 --port 13

       Prints the time on the host (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

       Scan for	HTTP servers and record	their version strings.

	      doscan --protocol	http_proxy --port 3128 \
		 --send	GET --receive 80

       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

       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	 nega-

       To increase the number of connections your system can process, you usu-
       ally 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 --connec-
       tions 10000 to doscan.  (Some file descriptors are not used  for	 scan-
       ning,  but have to be open nonetheless, and count towards the ulimit -n

       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.

       doscan was written by Florian Weimer.

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

				  2003-07-27			     DOSCAN(1)


Want to link to this manual page? Use this URL:

home | help