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
Script Format
Prev Chapter 9. Nmap Scripting Engine Next

Script Format

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.

id Field

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.

description Field

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

author Field

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.

license Field

This field describes the license applied to the script. All scripts currently shipped with Nmap contain:

license = "Same as Nmap--See http://nmap.org/book/man-legal.html"

See the section called “NSE Script License and Community Contributions” for further details on contributing NSE scripts to Nmap.

runlevel Field

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”

Port and Host Rules

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”

Action

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”


Prev Up Next
Usage and Examples Home Script Language
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]