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, vuln, auth and default. Category names 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 scripts that cannot be classified in the safe category because the risks are too high that they will crash the target system, use up significant resources on the target host (such as bandwidth or CPU time), or otherwise be perceived as malicious by the target's system administrators.
malware: These scripts test whether the target platform is infected by malware or backdoors.
version: The scripts in this category are an extension to the version detection option and cannot be selected explicitly. They are selected to run only if version detection (-sV) was requested. Their output cannot be distinguished from version detection output and they do not produce service or host script results.
discovery: These scripts try to actively learn more about the network by querying public registries, SNMP-enabled devices, directory services, and the like.
vuln: These scripts check for specific known vulnerabilities and generally only report results if they are found.
auth: These scripts try to determine authentication credentials on the target system, often through a brute-force attack.
default: These scripts are the default set and are run when using -sC, -A or --script without any arguments. This category can also be specified explicitly like any other using --script=default.

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=default. Some of the scripts in this category are considered intrusive and should not be run against a target network without permission.

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

Runs a script scan (like -sC) using the comma-separated list of script categories, individual scripts, or directories containing scripts, rather than the default set. Nmap first tries to interpret the arguments as categories, then (if that fails) as files or directories. A script or directory of scripts may be specified as an absolute or relative path. Absolute paths are used as supplied. Relative paths are searched for in the following places until found: --datadir/; $NMAPDIR/; ~/.nmap/ (not searched on Windows); NMAPDATADIR/ or ./. A scripts/ subdirectory is also tried in each of these.

If a directory is specified and found, Nmap loads all NSE scripts (any filenames ending with .nse) from that directory. Filenames without the nse extension are ignored. Nmap does not search recursively into subdirectories to find scripts. If 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 by default (see Chapter 14, Understanding and Customizing Nmap Data Files). For efficiency, scripts are indexed in a database stored in scripts/script.db. which lists the category or categories in which each script belongs. Give the argument all to execute all scripts in the Nmap script database.

Malicious scripts are not run in a sandbox and thus could damage your system or invade your privacy. Never run scripts from third parties unless you trust the authors or have carefully audited the scripts yourself.

--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 updates the script database found in scripts/script.db which is used by Nmap to determine the available default scripts and categories. It is only necessary to update the database if you have added or removed NSE scripts from the default scripts directory or if you have changed the categories of any script. This option is generally used by itself: 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 advanced/aggressive mode of Nmap implies the option -sC.

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, otherwise scripts won't know where to retrieve their arguments.

Usage Examples

A simple script scan using the default set of scripts

$ nmap -sC example.com

Tracing a specific script.

$ nmap --script=./showSSHVersion.nse --script-trace example.com

All scripts in a subdirectory named mycustomscripts in addition to all of Nmap's included scripts which are in the safe category.

$ nmap --script=mycustomscripts,safe example.com