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.