An effective Nmap scripting engine requires more than just a Lua interpreter. Users need easy access to the information Nmap has learned about the target hosts. This data is passed as arguments to the NSE script's action method. The arguments, host and port, are Lua tables which contain information on the target against which the script is executed. If a script matched a hostrule, it gets only the host table, and if it matched a portrule it gets both host and port. The following list describes each variable in these two tables.

To allow for efficient and parallelizable network I/O, NSE provides an interface to Nsock, the Nmap socket library. The smart callback mechanism Nsock uses is fully transparent to NSE scripts. The main benefit of NSE's sockets is that they never block on I/O operations, allowing many scripts to be run in parallel. The I/O parallelism is fully transparent to authors of NSE scripts. In NSE you can either program as if you were using a single non-blocking socket or you can program as if your connection is blocking. Even blocking I/O calls return once a specified timeout has been exceeded. Two flavors of Network I/O are supported: connect-style and raw packet.

require("nmap")

local socket = nmap.new_socket()
socket:set_timeout(1000)
try = nmap.new_try(function() socket:close() end)
try(socket:connect(host.ip, port.number))
try(socket:send("login"))
response = try(socket:receive())
socket:close()

NSE scripts should usually return a table representing their output, one that is nicely organized and has thoughtfully chosen keys. Such a table will be automatically formatted for screen output and will be stored as nested elements in XML output. Having XML output broken down logically into keys and values makes it easier for other tools to make use of script output. It is possible for a script to return only a string, but doing so is deprecated. In the past, scripts could only return a string, and their output was simply copied to the XML as a blob of text–this is now known as “unstructured output”.

Suppose a script called user-list returns a table as shown in this code sample. The following paragraphs show how it appears in normal and XML output.

local output = stdnse.output_table()
output.hostname = "slimer"
output.users = {}
output.users[#output.users + 1] = "root"
output.users[#output.users + 1] = "foo"
output.users[#output.users + 1] = "bar"
return output

A Lua table is converted to a string for normal output. The way this works is: each nested table gets a new level of indentation. Table entries with string keys are preceded by the key and a colon; entries with integer keys simply appear in order. Unlike normal Lua tables, which are unordered, a table that comes from stdnse.output_table will keep its keys in the order they were inserted. Example 9.4, “Automatic formatting of NSE structured output” shows how the example table appears in normal output.

PORT     STATE SERVICE
1123/tcp open  unknown
| user-list:
|   hostname: slimer
|   users:
|     root
|     foo
|_    bar

The XML representation of a Lua table is constructed as follows. Nested table become table elements. Entries of tables that are not themselves tables become elem elements. Entries (whether table or elem) with string keys get a key attribute (e.g. <elem key="username">foo</elem>); entries with integer keys have no key element and their key is implicit in the order in which they appear.

In addition to the above, whatever normal output the script produces (even if automatically generated) is copied to the output attribute of the script element. Newlines and other special characters will be encoded as XML character entities, for example 
. Example 9.5, “NSE structured output in XML” shows how the example table appears in XML.

<script id="t" output="&#xa;hostname: slimer&#xa;users: &#xa;  root&#xa;  foo&#xa;  bar">
  <elem key="hostname">slimer</elem>
  <table key="users">
    <elem>root</elem>
    <elem>foo</elem>
    <elem>bar</elem>
  </table>
</script>

Some scripts need more control their normal output. This is the case, for example, with scripts that need to display complex tables. For complete control over the output, these scripts may do either of these things:

The resulting string will be used in normal output, and the table will be used in XML as usual. The formatted string may contain newline characters to appear as multiple lines.

If the above code example were modified in this way to return a formatted string,

local output = stdnse.output_table()
output.hostname = "slimer"
output.users = {}
output.users[#output.users + 1] = "root"
output.users[#output.users + 1] = "foo"
output.users[#output.users + 1] = "bar"
local output_str = string.format("hostname: %s\n", output.hostname)
output_str = output_str .. "\n" .. stringaux.strjoin(", ", output.users)
return output, output_str

then the normal output would appear as follows:

PORT     STATE SERVICE
1123/tcp open  unknown
| user-list:
|   hostname: slimer
|_  users: root, foo, bar

2012-09-07T23:37:42+00:00
2012-09-07T23:37:42+02:00

2012-09-07T23:37:42

datetime.format_timestamp(os.time(), 0) --> "2012-09-07T23:37:42+00:00"

NSE provides an exception handling mechanism which is not present in the base Lua language. It is tailored specifically for network I/O operations, and follows a functional programming paradigm rather than an object-oriented one. The nmap.new_try API method is used to create an exception handler. This method returns a function which takes a variable number of arguments that are assumed to be the return values of another function. If an exception is detected in the return values (the first return value is false), then the script execution is aborted and no output is produced. Optionally, you can pass a function to new_try which will be called if an exception is caught. The function would generally perform any required cleanup operations.

Example 9.6 shows cleanup exception handling at work. A new function named catch is defined to simply close the newly created socket in case of an error. It is then used to protect connection and communication attempts on that socket. If no catch function is specified, execution of the script aborts without further ado—open sockets will remain open until the next run of Lua's garbage collector. If the verbosity level is at least one or if the scan is performed in debugging mode, a description of the uncaught error condition is printed on standard output. Note that it is currently not easily possible to group several statements in one try block.

local result, socket, try, catch

result = ""
socket = nmap.new_socket()
catch = function() 
socket:close() 
end
try = nmap.new_try(catch)

try(socket:connect(host.ip, port.number))
result = try(socket:receive_lines(1))
try(socket:send(result))

Writing a function which is treated properly by the try/catch mechanism is straightforward. The function should return multiple values. The first value should be a Boolean which is true upon successful completion of the function and false (or nil) otherwise. If the function completed successfully, the try construct consumes the indicator value and returns the remaining values. If the function failed then the second returned value must be a string describing the error condition. Note that if the value is not nil or false it is treated as true so you can return your value in the normal case and return nil, <error description> if an error occurs.

Scripts can share information by storing values in a register, which is a special table that can be accessed by all scripts. There is a global registry with the name nmap.registry, shared by all scripts. Each host additionally has its own registry called host.registry, where host is the host table passed to a script. Information in the registries is not stored between Nmap executions.

The global registry persists throughout an entire scan session. Scripts can use it, for example, to store values that will later be displayed by a postrule script. The per-host registries, on the other hand, only exist while a host is being scanned. They can be used to send information from one script to another one that runs against the same host. When possible, use the per-host registry; this not only saves you from having to make key names unique across hosts, but also allows the memory used by the registry to be reclaimed when it is no longer needed.

Here are examples of using both registries:

Because every script can write to the global registry table, it is important to make the keys you use unique, to avoid overwriting the keys of other scripts (or the same script running in parallel).

Scripts that use the results of another script must declare it using the dependencies variable to make sure that the earlier script runs first.