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
Nmap Scripting Engine (NSE)
Prev Chapter 15. Nmap Reference Guide Next

Nmap Scripting Engine (NSE)

The Nmap Scripting Engine (NSE) combines the efficiency of Nmap's network handling with the versatility of the lightweight scripting language Lua, thus providing innumerable opportunities. A more extensive documentation of the NSE (including its API) can be found at: http://nmap.org/book/nse.html The target of the NSE is to provide Nmap with a flexible infrastructure for extending its capabilities and offering its users a simple way of creating customized tests. Uses for the NSE include (but definitely are not limited to):

Enhanced version detection (category version)—While Nmap already offers its Service and Version detection system, which is unmatched in terms of efficiency and scope, this power has its downside when it comes to services requiring more complex probes. The Skype-Protocol version 2 for instance can be identified by sending 2 independent probes to it, which the builtin system is not laid out for: a simple NSE-script can do the job and update the port's service information.

Malware-detection (categories malware and backdoor)- Both attackers and worms often leave backdoors—be it in form of SMTP-servers listening on uncommon ports mostly used by spammers for mail relay, or in form of an FTP-server giving crackers access to critical data. A few lines of Lua code can help to identify those loopholes easily.

Vulnerability Detection (category vulnerability)- NSE's capacity in detecting risks ranges from checking for default passwords on Apache distributions to testing whether a SMTP-server supports relaying mail from arbitrary domains.

Network Discovery and Information Gathering (categories safe, intrusive and discovery)—By providing you with a scripting language and a really efficient asynchronous network API on the one hand and the information gathered during earlier stages of a scan on the other hand the NSE is suited to write client programs for the services listening on a target machine. These clients may collect information like: listings of available NFS/SMB/RPC shares, the number of channels of an irc-network or currently logged on users.

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 of the above mentioned categories. To maintain the matching from scripts to categories a file called script.db is installed along with the distributed scripts. Therefore, if you, for example, want to see if a machine is infected by any worm Nmap provides a script for you can simply run nmap --script=malware target-ip and check the output afterwards. The version scripts are always run implicitly when a script-scan is requested. The script.db is a Lua-script itself and can be updated through the --script-updatedb option.

A NSE-script basically is a chunk of Lua-code which has (among some informational fields, like name, id and categories) 2 functions: a test whether the particular script should be run against a certain host or port (called a hostrule or portrule respectively) and an action to be carried out if the test returns true. Scripts have access to most information gathered by Nmap during earlier stages. For each host this includes the IP address, hostname and (if available) operating system. If a script is targeted at a port it has access to the portnumber, the protocol (tcp, udp or ssl), the service running behind that port, and optionally information from a version-scan. NSE scripts by convention have an nse extension. Although you are not required to follow this for the moment, this may change in the future. Nmap will issue a warning if a file has any other extension. More extensive documentation on the NSE, including a description of its API can be found at http://nmap.org/book/nse.html

-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 with the nse extension) 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 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 <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 ‘}’. Subtables make it possible to override arguments for specific scripts (e.g. when you want to provide different login/password pairs for different scripts). For example, you could pass the comma-separated arguments: user=bar,password=foo, and anonFTP={password=nobody@foobar.com}. If you want to override an option to a script, you should index the subtable with the script's id, since this is the only way the script knows about its special argument.

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

--script-updatedb

updates the script database which stores a mapping from category tags to filenames. The database is a Lua script which is interpreted once to choose a set of scripts from the categories provided to the --script argument. It should be run if you have changed the categories field of a script, if you have added new scripts or if you have removed scripts from the scripts/ directory.


Prev Up Next
OS Detection Home Timing and Performance
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]