***** LOCALSCAN -- A frontend to nmap ***** Scripted in Perl 5 by Dylan Greene (trevise@u.washington.edu) Last modified Thursday, 20 January 2000
USAGE: localscan.pl [space-delimited list of subnet ranges]
Nmap is a pretty cool portscanner written by Fyodor (fyodor@dhp.com). It's available at http://www.insecure.org/ and is required for this script to run. (Localscan is just a frontend!) :)
Localscan also requires Perl 5, available at http://www.perl.com/
Some way to send email had also better be installed. Most *nix distributions come with this functionality.
Localscan assumes that Perl is in /usr/bin.
INTRODUCTION
The purpose of localscan is to make the lives of administrators easier. At it's heart, localscan is simply a list of "ignore this host/port combo" rules designed to reduce the amount of useless information returned by nmap scans of a given subnet.
I administer a largish lab at a largish higher educational institution (which shall remain unnamed!), and about three months ago I found it necessary to start running a portscanner against my subnet every so often. Now, while it was relatively easy to cobble something together that would do this and mail the results of the scan to me, I found that my inbox was being filled with inanity. Lots of valid services were present, and the few invalid services were hard to pick out. So I put together a quick-and-dirty filter and released it internally as local_scan 1.0a. Not surprisingly, no one used it. :) This was partially because I was (am!) still learning Perl.
After the initial disappointment, I sat down and started rewriting, with the end result being what you just downloaded. :) Localscan 2.0 is much easier for the non-Perl person (yes, there are a few of them out there) to use. All the "interesting" user-configurable parameters are now contained in a plaintext external datafile called localscan.conf.
You should have received four files in this tarball.
* This readme file
* A "quickstart" guide
* Localscan.pl, the actual script
* Make_conf.pl, a script to generate the localscan.conf file
SETTING UP LOCALSCAN
You need to download and install nmap and Perl if you haven't already. URLs for this are at the top of this document.
Make_conf.pl should be run once before you try to run localscan itself. That script creates the localscan.conf file which holds all the configuration information for localscan, and it also does a small amount of configuration of the localscan.pl script itself.
The syntax of the localscan.conf file is fairly straightforward. It's a text file with five possible field types--one type per line. The five fields are:
subnet holds the subnet (more on this later!) to scan mailto contains the address to be passed to the mail command allclr Boolean--do you want to be informed if nothing's found? ignore indicates a host and port(s) to ignore in the scan nmap the path to nmap (eg, "/usr/local/bin") # a comment
The "subnet", "mailto", "allclr", and nmap fields are required and exclusive; you may only have one of each in the localscan.conf file.
The "ignore" and "#" fields are not required and not exclusive; you can have as many as you want in the localscan.conf file, or none at all.
Let's look at a sample localscan.conf file:
----- BEGIN SAMPLE LOCALSCAN.CONF -----
subnet 69.69.69.0 69.69.30.1-150
mailto someadmin@somedomain.org
allclr yes
nmap /usr/local/bin
# Ignore the web servers on the following machines:
ignore 69.69.69.1 80
ignore 69.69.69.2 http
ignore somemachine.somedomain.org 80
ignore othermachine.somedomain.org http
# Ignore telnet and ftp server on this machine: ignore 69.69.69.3 21 23
# This machine has lots of open ports and is a pain. Ignore it, too: ignore 69.69.69.4 ALL
----- END SAMPLE LOCALSCAN.CONF -----
Now, starting from the top, the subnet is defined to be the /24 (class C) range of 69.69.69.1-254, and the range of addresses between 69.69.30.1 through 69.69.30.150. For more information on specifying subnets of varying complexity (or segments of subnets) see the nmap documentation. Note that you can put as many subnet ranges as you'd like in the "subnet" line, as long as they're delimited by spaces. The syntax of the subnet field in localscan.conf is identical (strangely enough!). (One exception: localscan cannot as yet accept "*" characters on the command line--this is easy to fix; I just haven't gotten to it yet!)
Next, the mailto field defines the destination mail address to which localscan reports will be mailed. In this case, reports will be sent to someadmin@somedomain.org
The third line sets the allclr field. This field has two possible values, "yes", or "no" (with no quotes). If this field is set to "yes", localscan will send mail each time it's run, even if there are no out-of-the-ordinary services to report. (Essentially, it's an "everything's okay!" report.) This can get annoying. If the allclr field is set to "no", localscan will only send mail to the mailto address if unknown services are detected.
The next line is blank; blank lines are perfectly permissible. After that comes a commented line. Note that you cannot comment out /part/ of a line; you can only comment out entire lines.
Now for the meat. The next four lines specify host/port pairs to ignore. Note that the host can be specified in two ways, as can the port. The separator between the fields needs to be whitespace. I use spaces (and so does make_conf.pl), but you can just as easily use tabs. If you have more than one port to ignore on a given host, you can append it using spaces, as shown.
The next line demonstrates how to ignore all output from a given host. The keyword "ALL" is the only supported instance of wildcards (with the exception of quasi-wildcards in the subnet field--again, see the nmap documentation). Make_conf.pl will never put "ALL" in localscan.conf; it will only appear if /you/ put it in yourself.
Everything in localscan.conf is case-sensitive.
RUNNING MAKE_CONF.PL
Although you can write localscan.conf yourself, I have included a handy little script under the name make_conf.pl which will create localscan.conf for you. You MUST run make_conf.pl at least once from the subdirectory containing localscan.conf before you can use the localscan.pl script.
First of all, you need to be running as a user which has access to write to the local directory. Run make_conf.pl from the prompt by typing
% ./make_conf.pl
Make_conf.pl will prompt you for the subnet to scan (again, see the nmap documentation), the email address to mail reports to, whether you want to receive "all clear" messages, and the location of nmap. Then it will quietly run nmap against the subnet you've specified. All host/port pairs returned from that scan will be entered into localscan.conf as "ignore" options. The idea here is that you run this when your subnet is in a "known good" condition. It might not be a bad idea to run nmap once beforehand to check the state of your network, or to scrutinize the generated localscan.conf file!
If you already have output from nmap that you'd like to use to generate localscan.conf (say you did something like
% nmap -sT '69.69.69.1-172' > subnet_state.data
earlier today), you can pass that data file to make_conf.pl by including it as the first (and only) argument:
% ./make_conf.pl subnet_state.data
Make_conf.pl will prompt you for the email address, subnet, all clear state, and nmap path, and then generate localscan.conf. It will (attempt to) overwrite any existing localscan.conf file, so be sure to save older copies if you think you might need them!
Note that make_conf.pl will give you a list of IP addresses and port numbers. It will not generate a list of host and service names, although those are valid formats for the localscan.conf file.
RUNNING LOCALSCAN.PL
Once you've run make_conf.pl, all you should need to do is execute the localscan.pl script. I run it periodically via cron, which works quite well. Be sure that the user you run it under has permissions to write to the localscan directory (as localscan does create one temporary datafile while it's running), and to execute mail, the Perl interpreter, and nmap. It would also be a good idea to set the interval of repetition to something greater than the time it takes to scan the subnet. (In other words, don't have two instances of localscan running simultaneously, unless they're running from separate directories. Otherwise, you risk overwriting the temporary datafile that localscan creates.)
If you want, you can specify subnet(s) on the command line when invoking localscan.pl. The syntax is:
% localscan.pl 69.69.69.0 69.69.69.1-150
You can specify as many subnet(s) (ranges) as you'd like on the command line, as long as they're space-delimited. If you do this, the subnets you specify on the command line will be used instead of the subnets listed in localscan.conf.
MISCELLANEOUS
If you like localscan and feel like stroking my ego, please drop me a line at trevise@u.washington.edu. Contrariwise, if you think that localscan has somehow broken your system/network, please don't try to sue. Localscan is released "as is" with no warranties, implied or otherwise (under the GPL, in fact). Besides, I'm a grad student and therefore perpetually impoverished--you can't really sue me for what I don't have. :)
Localscan is released under the GPL. If you use localscan or bits of localscan in a place where it's likely to be noticed, I'd appreciate it if you'd give me credit. :)
Speaking of credit, kudos to Larry Wall and the PerlDev team, and to Fyodor (fyodor@dhp.com), the creator of nmap! Great work, guys!