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
| Chapter 9. Nmap Scripting Engine |
## 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”
Usage and Examples |  | Script Language
| [ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]