Library stdnse

Standard Nmap Scripting Engine functions. This module contains various handy functions that are too small to justify modules of their own.

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/stdnse.lua

Functions

base ()

Returns the base coroutine of the running script.

clock_ms ()

Returns the current time in milliseconds since the epoch

clock_us ()

Returns the current time in microseconds since the epoch

debug (level, fmt, ...)

Prints a formatted debug message if the current debugging level is greater than or equal to a given level.

format_mac (mac)

Format a MAC address as colon-separated hex bytes.

format_output (status, data, indent)

This function is deprecated.

fromhex (hex)

Decode a hexadecimal string to raw bytes

get_hostname (host)

Get the best possible hostname for the given host. This can be the target as given on the commandline, the reverse dns name, or simply the ip address.

get_script_args (..., Arguments)

Parses the script arguments passed to the --script-args option.

get_timeout (host, max_timeout, min_timeout)

Returns a conservative timeout for a host

make_buffer (socket, sep)

Return a wrapper closure around a socket that buffers socket reads into chunks separated by a pattern.

module (name, ...)

Module function that mimics some behavior of Lua 5.1 module function.

new_thread (main, ...)

This function allows you to create worker threads that may perform network tasks in parallel with your script thread.

output_table ()

Return a table that keeps elements in order of insertion.

parse_timespec (timespec)

Parses a time duration specification, which is a number followed by a unit, and returns a number of seconds.

pretty_printer (obj, printer)

A pretty printer for Lua objects.

print_debug (level, fmt, ...)

Deprecated version of debug(), kept for now to prevent the script id from being printed twice. Scripts should use debug() and not pass SCRIPT_NAME

print_verbose (level, fmt, ...)

Deprecated version of verbose(), kept for now to prevent the script id from being printed twice. Scripts should use verbose() and not pass SCRIPT_NAME

registry_add_array (subkeys, value, allow_duplicates)

Add an item to an array in the registry, creating all sub-keys if necessary.

registry_add_table (subkeys, key, value, allow_duplicates)

Similar to registry_add_array, except instead of adding a value to the end of an array, it adds a key:value pair to the table.

registry_get (subkeys)

Retrieve an item from the registry, checking if each sub-key exists. If any key doesn't exist, return nil.

seeall (env)

Change environment to load global variables.

silent_require ()

The Lua Require Function with errors silenced.

sleep (t)

Sleeps for a given amount of time.

string_or_blank (string, blank)

Either return the string itself, or return "<blank>" (or the value of the second parameter) if the string was blank or nil.

tobinary (n)

Converts the given number, n, to a string in a binary number format (12 becomes "1100"). Leading 0s not stripped.

tohex (s, options)

Encode a string or integer in hexadecimal (12 becomes "c", "AB" becomes "4142").

tooctal (n)

Converts the given number, n, to a string in an octal number format (12 becomes "14").

verbose (level, fmt, ...)

Prints a formatted verbosity message if the current verbosity level is greater than or equal to a given level.

Functions

base ()

Returns the base coroutine of the running script.

A script may be resuming multiple coroutines to facilitate its own collaborative multithreading design. Because there is a "root" or "base" coroutine that lets us determine whether the script is still active (that is, the script did not end, possibly due to an error), we provide this stdnse.base function that will retrieve the base coroutine of the script. This base coroutine is the coroutine that runs the action function.

The base coroutine is useful for many reasons but here are some common uses:

  • We want to attribute the ownership of an object (perhaps a network socket) to a script.
  • We want to identify if the script is still alive.

Return value:

coroutine Returns the base coroutine of the running script.
clock_ms ()

Returns the current time in milliseconds since the epoch

Return value:

The current time in milliseconds since the epoch
clock_us ()

Returns the current time in microseconds since the epoch

Return value:

The current time in microseconds since the epoch
debug (level, fmt, ...)

Prints a formatted debug message if the current debugging level is greater than or equal to a given level.

This is a convenience wrapper around nmap.log_write. The first optional numeric argument, level, is used as the debugging level necessary to print the message (it defaults to 1 if omitted). All remaining arguments are processed with Lua's string.format function.

If known, the output includes some context based information: the script identifier and the target ip/port (if there is one). If the debug level is at least 2, it also prints the base thread identifier and whether it is a worker thread or the controller thread.

Parameters

level
Optional debugging level.
fmt
Format string.
...
Arguments to format.
format_mac (mac)

Format a MAC address as colon-separated hex bytes.

Parameters

mac
The MAC address in binary, such as host.mac_addr

Return value:

The MAC address in XX:XX:XX:XX:XX:XX format
format_output (status, data, indent)

This function is deprecated.

Please use structured NSE output instead: https://nmap.org/book/nse-api.html#nse-structured-output

Takes a table of output on the commandline and formats it for display to the user.

This is basically done by converting an array of nested tables into a string. In addition to numbered array elements, each table can have a 'name' and a 'warning' value. The 'name' will be displayed above the table, and 'warning' will be displayed, with a 'WARNING' tag, if and only if debugging is enabled.

Here's an example of a table:

  local domains = {}
  domains['name'] = "DOMAINS"
  table.insert(domains, 'Domain 1')
  table.insert(domains, 'Domain 2')

  local names = {}
  names['name'] = "NAMES"
  names['warning'] = "Not all names could be determined!"
  table.insert(names, "Name 1")

  local response = {}
  table.insert(response, "Apple pie")
  table.insert(response, domains)
  table.insert(response, names)

  return stdnse.format_output(true, response)

With debugging enabled, this is the output:

  Host script results:
  |  smb-enum-domains:
  |    Apple pie
  |    DOMAINS
  |      Domain 1
  |      Domain 2
  |    NAMES (WARNING: Not all names could be determined!)
  |_     Name 1

Parameters

status
A boolean value dictating whether or not the script succeeded. If status is false, and debugging is enabled, 'ERROR' is prepended to every line. If status is false and debugging is disabled, no output occurs.
data
The table of output.
indent
Used for indentation on recursive calls; should generally be set to nil when calling from a script.

Return value:

nil, if data is empty, otherwise a multiline string.
fromhex (hex)

Decode a hexadecimal string to raw bytes

The string can contain any amount of whitespace and capital or lowercase hexadecimal digits. There must be an even number of hex digits, since it takes 2 hex digits to make a byte.

Parameters

hex
A string in hexadecimal representation

Return values:

  1. A string of bytes or nil if string could not be decoded
  2. Error message if string could not be decoded
get_hostname (host)

Get the best possible hostname for the given host. This can be the target as given on the commandline, the reverse dns name, or simply the ip address.

Parameters

host
The host table (or a string that'll simply be returned).

Return value:

The best possible hostname, as a string.
get_script_args (..., Arguments)

Parses the script arguments passed to the --script-args option.

Parameters

...
 
Arguments
Script arguments to check.

Usage:

--script-args 'script.arg1=value,script.arg3,script-x.arg=value'
local arg1, arg2, arg3 = get_script_args('script.arg1','script.arg2','script.arg3')
     => arg1 = "value"
     => arg2 = nil
     => arg3 = 1

--script-args 'displayall,unsafe,script-x.arg=value,script-y.arg=value'
local displayall, unsafe = get_script_args('displayall','unsafe')
     => displayall = 1
     => unsafe     = 1

--script-args 'dns-cache-snoop.mode=timed,dns-cache-snoop.domains={host1,host2}'
local mode, domains = get_script_args('dns-cache-snoop.mode',
                                      'dns-cache-snoop.domains')
     => mode    = "timed"
     => domains = {"host1","host2"}

Return value:

Arguments values.
get_timeout (host, max_timeout, min_timeout)

Returns a conservative timeout for a host

If the host parameter is a NSE host table with a times.timeout attribute, then the return value is the host timeout scaled according to the max_timeout. The scaling factor is defined by a linear formula such that (max_timeout=8000, scale=2) and (max_timeout=1000, scale=1)

Parameters

host
The host object to base the timeout on. If this is anything but a host table, the max_timeout is returned.
max_timeout
The maximum timeout in milliseconds. This is the default timeout used if there is no host.times.timeout. Default: 8000
min_timeout
The minimum timeout in milliseconds that will be returned. Default: 1000

Usage:

assert(host.times.timeout == 1.3)
 assert(get_timeout() == 8000)
 assert(get_timeout(nil, 5000) == 5000)
 assert(get_timeout(host) == 2600)
 assert(get_timeout(host, 10000, 3000) == 3000)

Return value:

The timeout in milliseconds, suitable for passing to set_timeout
make_buffer (socket, sep)

Return a wrapper closure around a socket that buffers socket reads into chunks separated by a pattern.

This function operates on a socket attempting to read data. It separates the data by sep and, for each invocation, returns a piece of the separated data. Typically this is used to iterate over the lines of data received from a socket (sep = "\r?\n"). The returned string does not include the separator. It will return the final data even if it is not followed by the separator. Once an error or EOF is reached, it returns nil, msg. msg is what is returned by nmap.receive_lines.

Parameters

socket
Socket for the buffer.
sep
Separator for the buffered reads.

Return values:

  1. Data from socket reads or nil on EOF or error.
  2. Error message, as with receive_lines.
module (name, ...)

Module function that mimics some behavior of Lua 5.1 module function.

This convenience function returns a module environment to set the _ENV upvalue. The _NAME, _PACKAGE, and _M fields are set as in the Lua 5.1 version of this function. Each option function (e.g. stdnse.seeall) passed is run with the new environment, in order.

Parameters

name
The module name.
...
Option functions which modify the environment of the module.

Usage:

  _ENV = stdnse.module(name, stdnse.seeall, require "strict");

See also:

new_thread (main, ...)

This function allows you to create worker threads that may perform network tasks in parallel with your script thread.

Any network task (e.g. socket:connect(...)) will cause the running thread to yield to NSE. This allows network tasks to appear to be blocking while being able to run multiple network tasks at once. While this is useful for running multiple separate scripts, it is unfortunately difficult for a script itself to perform network tasks in parallel. In order to allow scripts to also have network tasks running in parallel, we provide this function, stdnse.new_thread, to create a new thread that can perform its own network related tasks in parallel with the script.

The script launches the worker thread by calling the new_thread function with the parameters:

  • The main Lua function for the script to execute, similar to the script action function.
  • The variable number of arguments to be passed to the worker's main function.

The stdnse.new_thread function will return two results:

  • The worker thread's base (main) coroutine (useful for tracking status).
  • A status query function (described below).

The status query function shall return two values:

  • The result of coroutine.status using the worker thread base coroutine.
  • The error object thrown that ended the worker thread or nil if no error was thrown. This is typically a string, like most Lua errors.

Note that NSE discards all return values of the worker's main function. You must use function parameters, upvalues or environments to communicate results.

You should use the condition variable (nmap.condvar) and mutex (nmap.mutex) facilities to coordinate with your worker threads. Keep in mind that Nmap is single threaded so there are no (memory) issues in synchronization to worry about; however, there is resource contention. Your resources are usually network bandwidth, network sockets, etc. Condition variables are also useful if the work for any single thread is dynamic. For example, a web server spider script with a pool of workers will initially have a single root html document. Following the retrieval of the root document, the set of resources to be retrieved (the worker's work) will become very large (an html document adds many new hyperlinks (resources) to fetch).

Parameters

main
The main function of the worker thread.
...
The arguments passed to the main worker thread.

Usage:

local requests = {"/", "/index.html", --[[ long list of objects ]]}

function thread_main (host, port, responses, ...)
 local condvar = nmap.condvar(responses);
 local what = {n = select("#", ...), ...};
 local allReqs = nil;
 for i = 1, what.n do
   allReqs = http.pGet(host, port, what[i], nil, nil, allReqs);
 end
 local p = assert(http.pipeline(host, port, allReqs));
 for i, response in ipairs(p) do responses[#responses+1] = response end
 condvar "signal";
end

function many_requests (host, port)
 local threads = {};
 local responses = {};
 local condvar = nmap.condvar(responses);
 local i = 1;
 repeat
   local j = math.min(i+10, #requests);
   local co = stdnse.new_thread(thread_main, host, port, responses,
       table.unpack(requests, i, j));
   threads[co] = true;
   i = j+1;
 until i > #requests;
 repeat
   condvar "wait";
   for thread in pairs(threads) do
     if coroutine.status(thread) == "dead" then threads[thread] = nil end
   end
 until next(threads) == nil;
 return responses;
end

Return values:

  1. co The base coroutine of the worker thread.
  2. info A query function used to obtain status information of the worker.
output_table ()

Return a table that keeps elements in order of insertion.

The pairs function, called on a table returned by this function, will yield elements in the order they were inserted. This function is meant to be used to construct output tables returned by scripts.

Reinserting a key that is already in the table does not change its position in the order. However, removing a key by assigning to nil and then doing another assignment will move the key to the end of the order.

Return value:

An ordered table.
parse_timespec (timespec)

Parses a time duration specification, which is a number followed by a unit, and returns a number of seconds.

The unit is optional and defaults to seconds. The possible units (case-insensitive) are

  • ms: milliseconds,
  • s: seconds,
  • m: minutes,
  • h: hours.
In case of a parsing error, the function returns nil followed by an error message.

Parameters

timespec
A time specification string.

Usage:

parse_timespec("10") --> 10
parse_timespec("10ms") --> 0.01
parse_timespec("10s") --> 10
parse_timespec("10m") --> 600
parse_timespec("10h") --> 36000
parse_timespec("10z") --> nil, "Can't parse time specification \"10z\" (bad unit \"z\")"

Return value:

A number of seconds, or nil followed by an error message.
pretty_printer (obj, printer)

A pretty printer for Lua objects.

Takes an object (usually a table) and prints it using the printer function. The printer function takes a sole string argument and will be called repeatedly.

Parameters

obj
The object to pretty print.
printer
The printer function.

Deprecated version of debug(), kept for now to prevent the script id from being printed twice. Scripts should use debug() and not pass SCRIPT_NAME

Parameters

level
 
fmt
 
...
 

Deprecated version of verbose(), kept for now to prevent the script id from being printed twice. Scripts should use verbose() and not pass SCRIPT_NAME

Parameters

level
 
fmt
 
...
 
registry_add_array (subkeys, value, allow_duplicates)

Add an item to an array in the registry, creating all sub-keys if necessary.

For example, calling: registry_add_array({'192.168.1.100', 'www', '80', 'pages'}, 'index.html') Will create nmap.registry['192.168.1.100'] as a table, if necessary, then add a table under the 'www' key, and so on. 'pages', finally, is treated as an array and the value given is added to the end.

Parameters

subkeys
 
value
 
allow_duplicates
 
registry_add_table (subkeys, key, value, allow_duplicates)

Similar to registry_add_array, except instead of adding a value to the end of an array, it adds a key:value pair to the table.

Parameters

subkeys
 
key
 
value
 
allow_duplicates
 
registry_get (subkeys)

Retrieve an item from the registry, checking if each sub-key exists. If any key doesn't exist, return nil.

Parameters

subkeys
 
seeall (env)

Change environment to load global variables.

Option function for use with stdnse.module. It is the same as package.seeall from Lua 5.1.

Parameters

env
Environment to change.

Usage:

 _ENV = stdnse.module(name, stdnse.seeall);

See also:

silent_require ()

The Lua Require Function with errors silenced.

See the Lua manual for description of the require function. This modified version allows the script to quietly fail at loading if a required library does not exist.

Usage:

stdnse.silent_require "openssl"
sleep (t)

Sleeps for a given amount of time.

This causes the program to yield control and not regain it until the time period has elapsed. The time may have a fractional part. Internally, the timer provides millisecond resolution.

Parameters

t
Time to sleep, in seconds.

Usage:

stdnse.sleep(1.5)
string_or_blank (string, blank)

Either return the string itself, or return "<blank>" (or the value of the second parameter) if the string was blank or nil.

Parameters

string
The base string.
blank
The string to return if string was blank

Return value:

Either string or, if it was blank, blank
tobinary (n)

Converts the given number, n, to a string in a binary number format (12 becomes "1100"). Leading 0s not stripped.

Parameters

n
Number to convert.

Return value:

String in binary format.
tohex (s, options)

Encode a string or integer in hexadecimal (12 becomes "c", "AB" becomes "4142").

An optional second argument is a table with formatting options. The possible fields in this table are

  • separator: A string to use to separate groups of digits.
  • group: The size of each group of digits between separators. Defaults to 2, but has no effect if separator is not also given.

Parameters

s
String or number to be encoded.
options
Table specifying formatting options.

Usage:

stdnse.tohex("abc") --> "616263"
stdnse.tohex("abc", {separator = ":"}) --> "61:62:63"
stdnse.tohex("abc", {separator = ":", group = 4}) --> "61:6263"
stdnse.tohex(123456) --> "1e240"
stdnse.tohex(123456, {separator = ":"}) --> "1:e2:40"
stdnse.tohex(123456, {separator = ":", group = 4}) --> "1:e240"

Return value:

String in hexadecimal format.
tooctal (n)

Converts the given number, n, to a string in an octal number format (12 becomes "14").

Parameters

n
Number to convert.

Return value:

String in octal format.
verbose (level, fmt, ...)

Prints a formatted verbosity message if the current verbosity level is greater than or equal to a given level.

This is a convenience wrapper around nmap.log_write. The first optional numeric argument, level, is used as the verbosity level necessary to print the message (it defaults to 1 if omitted). All remaining arguments are processed with Lua's string.format function.

If known, the output includes some context based information: the script identifier. If the verbosity level is at least 2, it also prints the target ip/port (if there is one)

Parameters

level
Optional verbosity level.
fmt
Format string.
...
Arguments to format.