Nmap Security Scanner
*Ref Guide
Security Lists
Security Tools
Site News
Advertising
About/Contact
Credits
Sponsors





Intro Reference Guide Book Install Guide
Download Changelog Zenmap GUI Docs
Bug Reports OS Detection Propaganda Related Projects
In the Movies In the News
Usage and Examples
Prev Chapter 9. Nmap Scripting Engine Next

Usage and Examples

While NSE has a complex implementation for efficiency, it is strikingly easy to use. Simply specify -sC to enable the most common scripts. Or specify the --script option to choose your own scripts to execute by providing categories, script file names, or the name of directories full of scripts you wish to execute. You can customize some scripts by providing arguments to them via the --script-args option. The two remaining options, --script-trace and --script-updatedb, are generally only used for script debugging and development.

Script Categories

NSE scripts define a list of categories they belong to. Currently defined categories are safe, intrusive, malware, version, discovery and vulnerability. By default, Nmap runs all scripts in either the safe or intrusive categories. Categories are not case sensitive. The following list describes each category.

safe

Scripts which weren't designed to crash services, use large amounts of network bandwidth or other resources, or exploit security holes. These are less likely to offend remote sysadmins. Of course (as with all other Nmap features) we cannot guarantee that they won't ever cause adverse reactions. Most of these perform general network discovery. Examples are echoTest (sends a string to the UDP echo service) and showHTMLTitle (grabs the title from a web page).

intrusive

These are not intended to crash or damage anything, but are more likely to leave suspicious logs or otherwise arouse sysadmin ire. Scripts which attempt to login to services with default passwords fall into this class.

malware

These scripts test if the target platform is infected by malware or backdoors.

version

This category cannot be selected explicitly. It is only run if -sV was supplied. The scripts in this category are an extension to the version detection service. Their output cannot be distinguished from version detection output and they do not produce script scanning output.

discovery

These scripts try to actively learn more about the network by querying public registries, SNMP-enabled devices, directory services, and the like.

vulnerability

These scripts check for a specific vulnerability and report results only if it is found.

Arguments to Scripts

You can pass arguments to NSE scripts via the --script-args option. The script-arguments generally are name-value pairs, which are provided to the script as a Lua table called args inside the nmap.registry with the names as keys for the corresponding values. The values can either be strings or tables. Subtables can be used to pass arguments to scripts with a finer granularity (e.g. pass different usernames for different scripts). A typical nmap invocation with script arguments may look like:

$ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com}

which would result in the Lua table:

{user="foo",pass="bar",anonFTP={pass=nobody@foobar.com}}

You could therefore access the username ("foo") inside your script as local username= nmap.registry.args.user . As a general rule the subtables used to override options for scripts should be named as the script's id, since otherwise scripts can't know where to search for their arguments.

Command-line Arguments

These are the five command line arguments specific to script-scanning:

-sC

Performs a script scan using the default set of scripts. It is equivalent to --script=safe,intrusive.

--script <script-categories|directory|filename|all>

Runs a script scan (like -sC) with the scripts you have chosen rather than the defaults. Arguments can be script categories, single scripts or directories with scripts which are to be run against the target hosts instead of the default set. Nmap will try to interpret the arguments at first as categories and afterwards as files or directories. Absolute paths are used as is, relative paths are searched in the following places until found: --datadir/; $(NMAPDIR)/; ~user/nmap/ (not searched on Windows); NMAPDATADIR/ or ./. A scripts/ subdirectory is also tried in each of these. Give the argument all to execute all scripts in the Nmap script database.

If a directory is specified and found, Nmap loads all NSE scripts (any filenames ending with .nse) from that directory. They must have the filename extension nse. Nmap does not recurse into subdirectories to find scripts. When individual file names are specified, the file extension does not have to be nse.

Nmap scripts are stored in a scripts subdirectory of the Nmap data directory (see the --datadir option) by default. Scripts are indexed in a database stored in scripts/script.db. The database lists all of the scripts in each category. A single script may be in several categories.

--script-args

provides arguments to the scripts. See the section called “Arguments to Scripts” for a detailed explanation.

--script-trace

This option is similar to --packet-trace, but works at the application level rather than packet by packet. If this option is specified, all incoming and outgoing communication performed by scripts is printed. The displayed information includes the communication protocol, source and target addresses, and the transmitted data. If more than 5% of transmitted data is unprintable, hex dumps are given instead.

--script-updatedb

This option is only useful if you have added or removed NSE scripts from the default scripts directory, or if you have changed any of the scripts' categories fields. This field contains categories such as safe and discovery which the script belongs to. Categories may be specified with the --script option. For efficiency reasons, NSE generates a script.db file which maps categories to the scripts they contain. If you changed tag directives or added/removed scripts, run nmap --script-updatedb.

Some of the Nmap options have effects on script scans. The most prominent of these is -sV. A version scan executes the scripts in the version category. The scripts in this category are slightly different than other scripts. Their output blends in with the version scan and they do not produce any script scan output.

Another option which has effect on the scripting engine is -A. The aggressive mode of Nmap implies the option -sC.

Usage Examples

Simple script scan.

$ nmap -sC hostname

Tracing a specific script.

$ nmap --script=./showSSHVersion.nse --script-trace hostname


Prev Up Next
Chapter 9. Nmap Scripting Engine Home Script Format
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]