NSE scripts consist of four descriptive fields, a port or host rule defining when the script should be executed, and an action block containing the actual script instructions. All six of these are Lua variables that are assigned to. Their names must be lowercase as shown here.
The script's id
field is displayed in the Nmap output
table if the script produces any output. It should be unique so users
can identify exactly which script file produced a message. IDs
should be kept short to conserve space in Nmap output, while
still being meaningful enough for users to recognize. Some
good examples are RIPE query
, HTML
title
, and Kibuv worm
.
The description describes what the script is testing for and
any critical notes the user must be aware of. A good example
example is this user contributed recursive DNS script
description “Checks whether a nameserver on UDP port 53
allows queries for third party names. It is expected that
recursion will be enabled on your own internal
nameserver.”
The author
field contains the script authors name and contact information. If you are worried about spam, you might want to omit or obscure your email address, or give your home page URL instead. This optional field is not used by NSE, but is important for giving script authors due credit or blame.
This optional field determines script execution order. When
this section is absent the run level defaults to 1.0. A script
with the run level 1.0 is run before any scripts with runlevel
set to
2.5
, which in turn runs before any scripts
with runlevel 2.55
. No particular order
is guaranteed for scripts with the same run level. One
application of run levels is allowing scripts to depend on
each other. If script A
relies on some
information gathered by script B
, give
B
a lower run level than
A
. Script B
can store
information in the NSE registry for A
to
retrieve later. For information on the NSE registry see to
the section called “The Registry”
There are two types of rules: host rules
which run only once against a target IP and port
rules which run against individual ports on a
target. A rule is a Lua function which takes a host and a
port table as arguments and returns a boolean. If the rule
evaluates to true
, the script action
is performed. Otherwise the action is skipped. Port rules are
only matched against TCP or UDP ports in the
open
, open|filtered
or
unfiltered
states. Host rules are matched exactly once against every
scanned host. The action, like the rule, is a Lua function,
which takes a host and port table as arguments. If the script is
matched using a host rule, then nil
is passed instead of a port table. Example rules are shown in
the section called “The Rule”
The action is the heart of an NSE script. It contains all of
the instructions to be executed when the script's port or host
rule triggers. It is a Lua function which returns either
nil
or a string. If a string is returned,
it is printed along with the script ID in (if it is a service
script) or below (if it is a host script) the Nmap port table.
If the script returns nil
, no output is
produced. All variables in the
action and rule segments must be declared local
. For an
example of an NSE action refer to the section called “The Mechanism”