Library `stdnse`

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

Source: http://nmap.org/svn/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
date_to_timestamp (date, offset)	Convert a date table into an integer timestamp. Unlike os.time, this does not assume that the date table represents a local time. Rather, it takes an optional offset number of seconds representing the time zone, and returns the timestamp that would result using that time zone as local time. If the offset is omitted or 0, the date table is interpreted as a UTC date. For example, 4:00 UTC is the same as 5:00 UTC+1: date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}) --> 14400 date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}, 0) --> 14400 date_to_timestamp({year=1970,month=1,day=1,hour=5,min=0,sec=0}, 16060) --> 14400 And 4:00 UTC+1 is an earlier time: date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}, 16060) --> 10800
format_difftime (t2, t1)	Format the difference between times `t2` and `t1` into a string in one of the forms (signs may vary): 0s -4s +2m38s -9h12m34s +5d17h05m06s -2y177d10h13m20s The string shows `t2` relative to `t1`; i.e., the calculation is `t2` minus `t1`.
format_output (status, data, indent)	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.
format_timestamp (t, offset)	Format a date and time (and optional time zone) for structured output.
generate_random_string (len, charset)	Generate a random string. You can either provide your own charset or the function will use a default one which is [A-Z].
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.
in_port_range (port, port_range)	Checks if the port is in the port range For example, calling: `in_port_range({number=31337,protocol="udp"},"T:15,50-75,U:31334-31339")` would result in a true value
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. 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.
print_debug (level, fmt, ...)	Prints a formatted debug message if the current debugging level is greater than or equal to a given level.
print_verbose (level, fmt, ...)	Prints a formatted verbosity message if the current verbosity level is greater than or equal to a given level.
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.
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.
strjoin (delimiter, list)	Join a list of strings with a separator string.
strsplit (pattern, text)	Split a string at a given delimiter, which may be a pattern.
tobinary (n)	Converts the given number, n, to a string in a binary number format (12 becomes "1100").
tohex (s, options)	Encode a string or number 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").

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

date_to_timestamp (date, offset)

Convert a date table into an integer timestamp. Unlike os.time, this does not assume that the date table represents a local time. Rather, it takes an optional offset number of seconds representing the time zone, and returns the timestamp that would result using that time zone as local time. If the offset is omitted or 0, the date table is interpreted as a UTC date. For example, 4:00 UTC is the same as 5:00 UTC+1:

date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0})          --> 14400
date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}, 0)       --> 14400
date_to_timestamp({year=1970,month=1,day=1,hour=5,min=0,sec=0}, 1*60*60) --> 14400

And 4:00 UTC+1 is an earlier time:

date_to_timestamp({year=1970,month=1,day=1,hour=4,min=0,sec=0}, 1*60*60) --> 10800

Parameters

date:
offset:

format_difftime (t2, t1)

Format the difference between times t2 and t1 into a string in one of the forms (signs may vary):

0s
-4s
+2m38s
-9h12m34s
+5d17h05m06s
-2y177d10h13m20s

The string shows t2 relative to t1; i.e., the calculation is t2 minus t1.

Parameters

format_output (status, data, indent)

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 callling from a script.

Return value:

nil, if data is empty, otherwise a multiline string.

format_timestamp (t, offset)

Format a date and time (and optional time zone) for structured output.

Formatting is done according to RFC 3339 (a profile of ISO 8601), except that a time zone may be omitted to signify an unspecified local time zone. Time zones are given as an integer number of seconds from UTC. Use 0 to mark UTC itself. Formatted strings with a time zone look like this:

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

Without a time zone they look like this:

format_timestamp(os.time())          --> "2012-09-07T23:37:42"

This function should be used for all dates emitted as part of NSE structured output.

Parameters

t:
offset:

generate_random_string (len, charset)

Generate a random string. You can either provide your own charset or the function will use a default one which is [A-Z].

Parameters

len: Length of the string we want to generate.
charset: Charset that will be used to generate the string.

Return value:

A random string of length len consisting of characters from charset if one was provided, otherwise charset defaults to [A-Z] letters.

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.

in_port_range (port, port_range)

Checks if the port is in the port range For example, calling: in_port_range({number=31337,protocol="udp"},"T:15,50-75,U:31334-31339") would result in a true value

Parameters

port: a port structure containing keys port number(number) and protocol(string)
port_range: a port range string in Nmap standard format (ex. "T:80,1-30,U:31337,21-25")

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:

Data from socket reads or nil on EOF or error.
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");

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:

co The base coroutine of the worker thread.
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.

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

Parameters

level: Optional debugging level.
fmt: Format string.
...: Arguments to format.

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

Parameters

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

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);

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

strjoin (delimiter, list)

Join a list of strings with a separator string.

This is Lua's table.concat function with the parameters swapped for coherence.

Parameters

delimiter: String to delimit each element of the list.
list: Array of strings to concatenate.

Usage:

stdnse.strjoin(", ", {"Anna", "Bob", "Charlie", "Dolores"})
--> "Anna, Bob, Charlie, Dolores"

Return value:

Concatenated string.

strsplit (pattern, text)

Split a string at a given delimiter, which may be a pattern.

Parameters

pattern: Pattern that separates the desired strings.
text: String to split.

Usage:

stdnse.strsplit(",%s*", "Anna, Bob, Charlie, Dolores")
--> { "Anna", "Bob", "Charlie", "Dolores" }

Return value:

Array of substrings without the separating pattern.

tobinary (n)

Converts the given number, n, to a string in a binary number format (12 becomes "1100").

Parameters

n: Number to convert.

Return value:

String in binary format.

tohex (s, options)

Encode a string or number 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 specifiying 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.

Sponsors

NSEDoc

Categories

Scripts (show 437)(437)Scripts (437)

Libraries (show 106)(106)Libraries (106)

Library stdnse

Functions

Functions

Return value:

Return value:

Return value:

Parameters

Parameters

Parameters

Return value:

Parameters

Parameters

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

Parameters

Parameters

Return values:

Parameters

Usage:

See also:

Parameters

Usage:

Return values:

Return value:

Parameters

Usage:

Return value:

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Usage:

See also:

Usage:

Parameters

Usage:

Parameters

Return value:

Parameters

Usage:

Return value:

Parameters

Usage:

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

Parameters

Return value:

Nmap Site Navigation

Library `stdnse`