
                               Warscan 0.7.2
                        An Internet Scanner Dispatch
                                by nocarrier


. Abstract

	Using Warscan anyone can automate efficient large-scale security tests
of any kind on entire networks at a time. Warscan is simply the front end that 
generates IPs and dispatches your testing script. It will take anything from a 
single hostname (which likely defeats its purpose) to a Class A domain IP,
to reading in a file of predefined hosts (IP or domain).


. Explanation

	Warscan is not an exploit of any resource, by any means. It is simply 
a vehicle for automating any test exploit in an efficient, timely, and large-
scale manner. Much in the same style of IPD, Warscan can retrieve its list of 
hosts from a flat text file, or instead you can ask it to generate the hosts 
for you. Once it has its hostlist, it will then call the script you specify
(inside Warscan) with a single argument of the hostname to scan. 

	So what does this mean? Basically, anyone with a security exploit can
automate their exploit over large numbers of hosts in a relatively short 
amount of time.


. Features

 . Can create and work in different directories unique to the scan ('-d').
 . Load hostnames from a file, or generate hostnames (IP) for you (Class A-C).
 . Using the '%' operator, you can construct enumerated DNS's, 'dial%.isp.com'.
    Warscan generates '%'s when you specify incomplete IP addresses, such as
    a Class A, B, or C specification. See the EXAMPLES file for a better 
    idea of what this means.
 . Save final list of hosts (if generated) for later use ('-o'). Default is
    'servers', in the current directory. If the file in the working directory
    cannot be opened, a last ditch effort at '/tmp/servers' is made. 
 . Mass Parallel Ping $MaxPing ('-P') hosts at a time, and weed out 
    non-responsive ips from the target server list. It is recommended that the 
    Ping Timeout ('-t') be raised gradually if '-P' is increased past 25.
 . Mass Parallel Scan $MaxScan hosts at a time recursively (IPD).
 . Ping scan only ('-p'). Does an 'fping' of specified hosts/networks. The
    number of hosts to ping in parallel can be manipulated with the '-P' 
    switch.
 . Ability to call specified script ('-s') with arguments. '-A' specifies 
    arguments After, '-B' specifies arguments Before. Enclose multiple 
    arguments in quotes. See the EXAMPLES file for ideas on how to use this.
 . Interrupted scans will attempt to save any worthy information already 
    retrieved. This means if you break in the middle of the Verify phase, the 
    verified servers will still be saved to file. If you break out of the
    Probe phase, the list of unscanned servers will be dumped to file.


. Requirements

 . PERL 5.004 or greater
 . Standard PERL library (POSIX::, Getopt::Std, Socket, Cwd) 
 . *NIX environment 
   (NOTE: An attempt to port Warscan to Win32 Perl has been made, and failed.
          Win32 Perl does not support fork(), which is the basis of multiple
          scans. If anyone tries to make use of Win32 Threads, please let me
          know.)


. Parameters

	The following is just a simply explanation/discussion of the various
switches that Warscan understands.

  . The '%' Meta Character
	Quite simply, wherever a '%' is encountered in the host template
	specification, it will be replaced with 1 to $IPLimit (set by '-L')
	in the host list. You can specify as many as you want.

  . -f <servers>  
	Read in targets from file, 1 per line. If specified, the host template
	is not required, and will be ignored.

  . -s <script>   
	Run script with host list. Default script to run is 'scan'. 
	Warscan will search your $PATH envariable and the working directory
	for the script you specify.

  . -P <num>      
	Number of pings to run in parallel. Default is 10. More is generally 
	better, but not always. Use in good measure; you need good bandwidth
	to really make any intelligent use of more Pings. You should consider
	increasing the Ping Timeout ('-t') gradually along with -P, to give
	Warscan more time to receive responses from hosts.

  . -S <num>      
	Number of scans to run concurrently. The default is 20, and is based 
	on a Pentium 100Mhz CPU running with 64MB of RAM.

  NOTE: Also note the login shell's process limits. Some shells, for instance, 
	limit the number of dispatchable, concurrent user processes to 256. 
	Warscan will dispatch as fast as it can, but if your system is slow, 
	the previously dispatched processes will zombie and linger for up to 
	a minute or longer until the system has an opportunity to clean them 
	up. This means that you could potentially hit your upper limit of 
	allowable CPU processes if you play around with '-S' too much. Warscan
	will continue to plod along, warning you that you are out of 
	processes, until more free up. It will wait one second for every 
	fork() error, in case the problem is that the system is overwhelmed 
	and doesn't have time to clean up. To be clear, however, the host 
	scans that fail as a result of fork() failures are exactly that, 
	failed -- scans were not executed on them.

  . -L <num>      
	Upper limit for IP/DNS generation. The default is 254. Why is it 
	useful to change this value? Well, the immediate reason is for the 
	DNS hostname generation feature of Warscan. For instance, you could 
	specify:

	% warscan dial%.some-isp.com

	and Warscan would generate addresses "dial1.some-isp.com" to 
	"dial254.some-isp.com". Well, using '-L' you could set that limit 
	higher,	if desired. In other situations, you don't want to scan an 
	entire network,	maybe just the first 100 hosts. Well, '-L 100' will 
	do just that.

  . -t <num>      
	Ping timeout. Default is 2 (seconds). As discussed before, if you set
	'-P' to a high number, you want to gradually increase '-t' along with 
	it. 

  . -d <dir>      
	Put results/run in directory 'dir'. Warscan will create <dir> if it 
	does not exist, and then change to that directory. This is useful for 
	scripts	that have file output.

  . -A <str>      
	Argument(s) to pass to the script after the hostname. If specifying 
	multiple arguments, enclose them in quotes. See the EXAMPLES file 
	for a better idea of what is meant.

  . -B <str>      
	Arguments to pass to the script before the hostname. If specifying 
	multiple arguments, enclose them in quotes. Again, see the EXAMPLES 
	file for a better idea of what is meant.

  . -o <file>     
	File to dump verified servers to. Default is "servers". If the file 
	cannot be opened in the working directory, a last ditch effort to open
	the file in the '/tmp' directory will be made. 

  . -n            
	No server dump file. Do not attempt to save any information to file.

  . -p            
	Ping scan only. Don't dispatch a script on the host list, just ping 
	them. 

  . -D            
	Turn on debugging. Increases verbosity.

  . -V            
	Turn off verification. This means that we won't bother to ping hosts.

  . -e
	Extra output. Wait for and print output from scripts. By default 
	Warscan ignores any stdout output from the scripts it dispatches (you 
	will still see stderr output); the key point is to use a little time 
	as possible in scanning the host(s) you specify. This will cause 
	Warscan to wait until the dispatched scripts close their end of the 
	pipe. This is NOT a recommended switch, as processes will seemingly
	hang while waiting to complete.

  . -v            
	Version information. Output version information and exit.

  . -h 
	Print out brief help message detailing options.


. Future

	Planned improvements to Warscan include parallel ping code for UDP and 
TCP sockets, width modifiers for % evaluation (dial002.some-isp.com) and the 
possible merging of pmap (port scanner under development).


. Final Note

	Please understand the driving nature behind Warscan -- Speed and 
Quantity. This program is intended to maximize your system's resources as
much as possible. Be careful when tweaking switches like '-S' and '-P'; you 
could quite possibly kill your system and bring it to a grinding halt.


. Personal Warranty
	
	No warranty is given by the author, express or implied, for this 
program, or the programs that this software runs. The author may not be held 
responsible or liable for the uses, express or implied, of this software and 
other software included, explained, or developed specifically for this 
software. Possession of this software constitutes consent to agreement of 
these terms. 

    See the COPYING file for full licensing and warranty information.


. Acknowledgements

	Thanks to balif and desslok for creating IPD; their idea for recursing
over scans was a good one. Thanks to fyodor for knowing everything about port 
scanning and writing nmap, by far the world's best (free) Internet Port 
Scanner. Thanks to friends who have helped debug and suggest improvements.
Also, thanks to all the #perl gurus on EFnet. 


. Contact

	The author can be reached at nocarrier@darkridge.com, or can be
found lurking on various IRC channels (#perl, ..) on EFnet.

