Nmap Scripting Engine (NSE)

The Nmap Scripting Engine (NSE) is one of Nmap's most powerful and flexible features. It allows users to write (and share) simple scripts (using the Lua programming language, ) to automate a wide variety of networking tasks. Those scripts are executed in parallel with the speed and efficiency you expect from Nmap. Users can rely on the growing and diverse set of scripts distributed with Nmap, or write their own to meet custom needs.

Tasks we had in mind when creating the system include network discovery, more sophisticated version detection, vulnerability detection. NSE can even be used for vulnerability exploitation.

To reflect those different uses and to simplify the choice of which scripts to run, each script contains a field associating it with one or more categories. Currently defined categories are safe, intrusive, malware, version, discovery, vuln, auth, and default. These are all described in the section called “Script Categories”.

The Nmap Scripting Engine is described in detail in Chapter 9, Nmap Scripting Engine and is controlled by the following options:

-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 <name1>=<value1>,<name2>={<name3>=<value3>},<name4>=<value4>

Lets you provide arguments to NSE scripts. Arguments are passed as name=value pairs. The provided argument is processed and stored inside a Lua table, to which all scripts have access. The names are taken as strings (which must be alphanumeric values) and used as keys inside the argument-table. Values are either strings or tables themselves (surrounded by ‘{’ and ‘}’). For example, you could pass the comma-separated arguments: user=bar,pass=foo,whois={whodb=nofollow+ripe}. String arguments are potentially used by several scripts; subtables are normally used by only one script. In scripts that take a subtable, the subtable is usually named after the script (like whois in this example).

--script-trace

This option does what --packet-trace does, just one ISO layer higher. If this option is specified all incoming and outgoing communication performed by a script is printed. The displayed information includes the communication protocol, the source, the target and the transmitted data. If more than 5% of all transmitted data is not printable, then the trace output is in a hex dump format. Specifying --packet-trace enables script tracing too.

--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.