Movatterモバイル変換

An effective Nmap scripting engine requires more than just aLua interpreter. Users need easy access to the informationNmap has learned about the target hosts. This data is passedas arguments to the NSE script'saction method. The arguments,host andport, are Lua tables which containinformation on the target against which the script isexecuted. If a script matched a hostrule, it gets only thehost table, and if it matched a portrule itgets bothhost andport.The following list describes each variable in these two tables.

To allow for efficient and parallelizable network I/O, NSEprovides an interface to Nsock, the Nmap socket library. Thesmart callback mechanism Nsock uses is fully transparent toNSE scripts. The main benefit of NSE's sockets is that theynever 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 isblocking. Even blocking I/O calls return once aspecified 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 calleduser-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 fromstdnse.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 SERVICE1123/tcp open  unknown| user-list:|   hostname: slimer|   users:|     root|     foo|_    bar

The XML representation of a Lua table is constructed as follows. Nested table becometable elements. Entries of tables that are not themselves tables becomeelem elements. Entries (whethertable orelem) with string keys get akey attribute (e.g.<elem key="username">foo</elem>); entries with integer keys have nokey 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 theoutput attribute of thescript 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 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 SERVICE1123/tcp open  unknown| user-list:|   hostname: slimer|_  users: root, foo, bar

2012-09-07T23:37:42+00:002012-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. Thenmap.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 tonew_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 namedcatch 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, catchresult = ""socket = nmap.new_socket()catch = function() socket:close() endtry = 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 istrue upon successful completion of the function andfalse (ornil) 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 notnil orfalse it is treated astrue so you can return your value in the normal case and returnnil,<error description> if an error occurs.

Scripts can share information by storing values in aregister, which is a special table that can beaccessed by all scripts. There is a global registry with the namenmap.registry, shared by all scripts. Each hostadditionally has its own registry calledhost.registry, wherehost is thehost table passed to a script.Information in the registries is not stored between Nmapexecutions.

The global registry persists throughout an entire scan session.Scripts can use it, for example, to store values that will later bedisplayed by a postrule script. The per-host registries, on the otherhand, only exist while a host is being scanned. They can be used to sendinformation from one script to another one that runs against the samehost. When possible, use the per-host registry; this not only saves youfrom having to make key names unique across hosts, but also allows thememory used by the registry to be reclaimed when it is no longerneeded.

Here are examples of using both registries:

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

Scripts that use the results of another script must declare it usingthedependencies variable to make sure that the earlierscript runs first.