NAME

nmap-audit - Network auditing with nmap


SYNOPSIS

nmap-audit --config filename [ --ips ip1,..,ipn ] [ --email-to addr ] [ --email-from addr ] [ --email-subject subject ] [ --nmap cmd ] [ --detail { none | low | med | high } ] [ --max-threads n ] [ --no-human ] [ --no-csv ] [ --scan-only | --process-only ] [ --dir-name dir[,dir2..] [ --no-csv-headings ] [ --version ] [ --help ] [ --quiet ]


DESCRIPTION

nmap-audit is a PERL script which makes use of the nmap port scanning software to automate port scan audits. nmap produces a human readable report for each host that contains, among other things, the hostname being scanned and any open ports. Unfortunately, even for a moderately sized network, these reports contain far too much information to process, especially if the network is scanned on a regular basis.

To help mitigate this information overload, nmap-audit was designed to eliminate repeated human processing of any redundant information from one scan to the next. For example, all windows machines may have UDP port 137 open, and as such, the fact that this port is open should not be noted in the otherwise cluttered reports.

nmap-audit was designed to produce large, detailed reports on the first run, thereby forcing a complete audit of the open ports on the network. Following this, only ports which have not been ignored, most likely any newly opened ports, are returned.

Though the complete information from each run of nmap-audit isn't delivered in a typical report, this script provides the necessary functionality to extract this data from any point in time on record, a feature which may prove especially helpful for after-the-fact forensics and other troubleshooting.


OPTIONS

--config filename
CONFIG command line only: Specifies the path the configuration file. This option is required.

--detail filename or detail in config
DETAIL operational: Specifies the level of detail provided in the emailed report. Valid options are either low, medium, or high. Increased level of detail will result in more verbose reports. Note that the detail level has no affect on the data stored during the nmap scan, therefore even if an initial report has the detail set to low, subsequent reports based off the same data may still have an arbitrarily high detail level.

--dir-name directory or dir-name in config
DIR-NAME operational: Specifies the root directory name under which all data generated during a program run will be saved. Inside of this, another directory will be made, one for each date (along with a sequence number to prevent multiple invocations on the same day from interfering with data from a previous run), which will hold a data file for each IP address scanned. When specified in conjunction with the process-only directive, all data in any subdirectory of the supplied .dir-name. will be used. Therefore, this value may need to be changed if one of several scans under the same base directory must be isolated.

--email-from address or email-from in config
EMAIL-FROM operational: Specifies the .from. address in emailed nmap-audit reports.

--email-subject string or email-subject in config
EMAIL-SUBJECT operational: Specifies the subject used in nmap-audit reports.

--email-to address or email-to in config
EMAIL-TO operational: Specifies to whom the nmap-audit report will be emailed after a successful execution of the script.

end group groupname in config
END GROUP ignore: Ends a group definition, which must be followed by the unique name given to the group. Each group opened using the group directive must be closed by an end group line.

group groupname in config
GROUP ignore: Begins a group definition, which must be followed by a unique group name. Each group definition that's opened must be closed with the end group directive.

hostname string
HOSTNAME ignore: One of three valid types that may be used within a group to restrict which hosts are members. Only one of the three types may be used in any single group, but it may be used multiple times. A host which matches any of the conditions will be included in the group (``or'' grouping). The supplied value need only be a substring for a valid match, and wildcards may be specified by using the ``*'' character.

ip address
IP ignore: One of three valid types that may be used within a group to restrict which hosts are members. Only one of the three types may be used in any single group, but it may be used multiple times. A host which matches any of the conditions will be included in the group (.or. grouping). The supplied value may simply be a substring for a Valid match.Wildcards may be specified by using the ``*'' character.

--ips address or ips in config
IPS operational: Used to specify the hosts readyto be scanned. This directive may be used any number of times and each use may have only one IP specified. Valid IPs are a single IP (192.168.1.1), a range of IPs (192.168.1.1-192.168.2.100), or a subnet (192.168.1.0/24). When used in conjunction with the .process-only. directive, the keyword ``all'' can be used to process all IPs for which data exists.

--max-threads number or max-threads in config
MAX-THREADS operational: Specifies the maximum number of nmap processes that will be launched. Though these processes are not launched simultaneously (there is a several second delay minimum between each new process), please adjust this number cautiously to keep the number of nmap processes from overwhelming your system.

--nmap string or nmap in config
NMAP operational: Specifies the command used to run nmap. This must include the full path to the executable if necessary, as well as information pertaining to the scan itself. Do not specify the option to output information (i.e. ``-oN''), since this will be taken care of automatically by the nmap-audit script. For the full documentation on how nmap may be invoked, so its man page.

--no-csv or no-csv in config
NO-CSV operational: Specify with a value of ``1'' if the generated report should not contain the CSV attachment. This attachment can be opened with Excel for powerful data manipulation and is especially helpful when performing an initial audit of the network.

--no-csv-headings or no-csv-headings in config
NO-CSV-HEADINGS operational: Specify if the CSV file attached to the report should not contain column headings. Excel uses these headings to make sorting and identifying the data easier, while other programs may inadvertently treat the headings as data.

--no-human or no-human in config
NO-HUMAN operational: Specify with a value of ``1'' if the generated report should not contain the human readable information. This format is especially useful once the nmap-audit reports are sufficiently small so that only a quick glance at the report is necessary.

os string in config
OS ignore: One of three valid types that may be used within a group to restrict which hosts are members. Only one of the three types may be used in any single group, but it may be used multiple times. A host which matches any of the conditions will be included in the group (.or. grouping). The supplied value need only be a substring for a valid match and wildcards may be specified by using the .*. character.

--process-only or process-only in config
PROCESS-ONLY operational: Specify with a value of .1. if only existing data will be processed. The data to be processed must already exist and its location must be specified with the dir-name directive. If neither scan-only nor process-only are specified, the script will both scan each host and process the new data.

--quiet
QUIET command line only: Specify if no output should be sent to STDOUT during the program run. This option will most likely be wanted when running nmap-audit from cron.

--scan-only or scan-only in config
SCAN-ONLY operational: Specify with a value of ``1'' if only a scan is to be performed. The data generated by the scan can always be processed at a later time. If neither scan-only nor process-only are specified, the script will both scan each host and process the new data.


CONFIGURATION FILE

nmap-audit and nmap are both highly configurable, and options may be specified in either a configuration file, on the command line, or as a combination of the two. Unfortunately, this configurability creates a relatively steep learning curve for a beginner. To help mitigate this, a well commented example configuration is included in the distribution and should be used as a reference in conjunction with the nmap man page

Below is a straightforward example configuration file for the nmap-audit script. Comments follow the same rules as in PERL; any text to the right of ``#'' is ignored.

The file consists of two primary types of configuration options: operational configuration and ignore configuration. Operational configuration, shown in in the first section, consists of directives which tell the nmap-audit program how to run and what limits should be placed on its execution.

Wildcards, denoted by a single asterisk, may be used in any part of the definition. Also, note that besides group restriction by operating system, groups may be separated by hostname or IP address.

############################################################## ######### nmap-audit config options ######

   ## IPS scanning definitions ##
   ips = 192.168.1.0/24

   ## report mailing info ##
   email-to = root@example.com
   email-subject = Host Vulnerability Scanning Results
   email-from = nmap-audit@example.com

   ## The maximum number of nmap threads to be run
   ## simultaneously.  Please begin this with a small
   ## number and slowly increase it to keep your machine
   ## from getting overwhelmed from too many processes
   max-threads = 20
   ## The level of detail to report.  Either low, medium, or high ##
   detail = low
   ## nmap command to be run.  Note that appended to this
   ## is the option to direct the output to a human readable
   ## file.  Therefore, using the '-oN filename' option will
   ## not work in conjunction with the nmap-audit script ##
   #nmap = nmap -sS -sU -v -O -T Polite -p 1-1024    # TCP and UDP scan
   nmap = nmap -sS -v -O -T Polite -p 1-1024        # TCP scan
   ## base directory name where all scanning data will be
   ## stored.  To this name the date of the scan and a
   ## sequence number will be appended to prevent multiple
   ## scans on the same day from overwriting data.  Use the
   ## complete path if executing via cron.
   dir-name = example

##############################################################

############################################################## ######### ignore options ######

## Group of all microsoft operating systems

group windows os = Windows

    ## RPC/DNS Administration ##
    ignore = open        135        loc-srv            tcp
    ignore = open        135        loc-srv            udp
    ## systems management over UDP ##
    ignore = open        137        netbios-ssn    udp            # wins
    ignore = open        138        netbios-ssn    udp            # netbios datagrams
    ignore = open        139        netbios-ssn    tcp            # netbios datagrams
    ## Direct hosting of SMB over TCP/IP ##
    ignore = open        445        microsoft-ds   udp
    ignore = open        445        microsoft-ds   tcp
end group windows

## Group that contains all unix hosts

group unix os = Linux Kernel 2.4.0 - 2.5.20 os = Solaris 2.6 - 2.7 with tcp_strong_iss=2 os = Solaris 2.6 - 7 (SPARC) os = Solaris 8 early access beta through actual release os = Solaris 9 Beta through Release on SPARC

    ignore = open        22        ssh            tcp             # SSH
end group unix

## group that matches all hosts place most general rules ## here

group all hostname = *

    ignore = filtered    *        *        *
    ignore = closed      *        *        *
end group all


EXAMPLES


FILES

Data from each scan completed by nmap is stored in the directory named in the dir-name variable.


SEE ALSO

nmap(1)


CAVEATS

nmap must be run as root when performing some of its scans. Therefore, under many circumstances it may be necessary to run nmap-audit as root when performing a scan (though this should not be necessary when merely processing historical data).

Regular expressions work mostly like in standard PERL, but for a slight restriction on the use of ``*''. Since it has been somewhat overloaded, what would normally be written as ``.*'' in PERL should be written as ``*'' in nmap-audit configuration files. Unfortunately, there is no way to do something like ``\d*'' here, though ``\d+'' is valid.


AUTHOR

Keith Resar <nmap-audit@heavyk.org>


AVAILABILITY

The latest release is available at:
http://heavyk.org/nmap-audit/


HISTORY

  1. 04/7/2003
    Initial public release.