nmap NSE Library — Nmap Scripting Engine documentation (original) (raw)

Interface with Nmap internals.

The nmap module is an interface with Nmap's internal functions and data structures. The API provides target host details such as port states and version detection results. It also offers an interface to the Nsock library for efficient network I/O.

address_family ()

Returns the address family Nmap is using.

For example, if Nmap is run with the -6 option, then "inet6" is returned.

Usage:

local family = nmap.address_family()

Return value:

The address family as a string ("inet" or "inet6")

bind (addr, port)

Sets the local address of a socket.

This socket method sets the local address and port of a socket. It must be called before connect. The address set by bindoverrides Nmap's source address and port set by the -S and-g options.

Parameters

addr

Address string or nil (optional).

port

Port number or nil (optional).

Usage:

try = nmap.new_try() try(socket:bind(nil, 53)) try(socket:bind("1.2.3.4")) try(socket:bind("2001:db8::1")) try(socket:bind("1.2.3.4", 53))

Return values:

  1. Status (true or false).
  2. Error string (if status is false).

clock ()

Returns the current date and time in seconds.

Usage:

local now = nmap.clock()

Return value:

The number of seconds since the epoch (on most systems this is 01/01/1970) as a floating point value.

clock_ms ()

Returns the current date and time in milliseconds.

Usage:

local now = nmap.clock_ms()

Return value:

The number of milliseconds since the epoch (on most systems this is 01/01/1970).

close ()

Closes an open connection.

On success the function returns true. If the close fails, the function returns false or nil and an error string. Currently the only error message is "Trying to close a closed socket", which is issued if the socket has already been closed.

Sockets are subject to garbage collection. Should you forget to close a socket, it will get closed before it gets deleted (on the next occasion Lua's garbage collector is run). However since garbage collection cycles are difficult to predict, it is considered good practice to close opened sockets.

Usage:

socket:close()

Return values:

  1. Status (true or false).
  2. Error code (if status is false).

See also:

condvar (object)

Create a condition variable for an object.

This function returns a function that works as a Condition Variable for the given object parameter. The object can be any Lua data type exceptnil, Booleans, and Numbers. The Condition Variable (returned function) allows you wait, signal, and broadcast on the condition variable. The Condition Variable function takes only one argument, which must be one of

NSE maintains a weak reference to the Condition Variable so other calls to nmap.condvar with the same object will return the same function (Condition Variable); however, if you discard your reference to the Condition Variable then it may be collected; and, subsequent calls to nmap.condvar with the object will return a different Condition Variable function!

In NSE, Condition Variables are typically used to coordinate with threads created using the stdnse.new_thread facility. The worker threads must wait until work is available that the controller thread (the actual running script) will provide. Once work is created, the controller thread will awaken one or more workers so that the work can be done.

It is important to check the predicate (the test to see if your worker thread should "wait" or not) BEFORE and AFTER the call to wait. You are not guaranteed spurious wakeups will not occur (that is, there is no guarantee your thread will not be awakened when no thread called"signal" or "broadcast" on the condition variable). One important check for your worker threads, before and after waiting, should be to check that the controller thread is still alive. (To check that the controller thread is alive, obtain the "base" thread using stdnse.base and use coroutine.status). You do not want your worker threads to continue when the script has ended for reasons unknown to your worker thread. You are guaranteed that all threads waiting on a condition variable will be awakened if any thread that has accessed the condition variable via nmap.condvar ends for any reason. This is essential to prevent deadlock with threads waiting for another thread to awaken them that has ended unexpectedly.

Parameters

object

Object to create a condition variable for.

Usage:

local myobject = {} local cv = nmap.condvar(myobject) cv "wait" -- waits until another thread calls cv "signal"

Return value:

ConditionVariable Condition variable function.

See also:

connect (host, port, protocol)

Establishes a connection.

This method puts a socket in a state ready for communication. It takes as arguments a host descriptor (a host table, IP address, or hostname), a port descriptor (a port table or number), and optionally a protocol. If given, the protocol must be one of "tcp", "udp" or"ssl". The default value for the protocol isport.protocol if port is a port table, otherwise"tcp".

If host is a host table, it must contain at least one of the keys ip or name. If nameis given, it is used to request the correct certificate in SSL connections. Passing a string instead of a host table acts like host.ip andhost.name were set to the same value. If portis a table, it must contain the number key.

On success the function returns a true value. On failure it returns a false value (false or nil) and an error string. Those strings are taken from the gai_strerror C function. They are (with the error code in parentheses):

Parameters

host

Host table, hostname or IP address.

port

Port table or number.

protocol

"tcp", "udp", or"ssl" (default "tcp", or whatever was set innew_socket).

Usage:

local status, err = socket:connect(host, port) if not status then return string.format("Can't connect: %s", err) end

Return values:

  1. Status (true or false).
  2. Error code (if status is false).

See also:

debugging ()

Returns the debugging level as a non-negative integer.

The debugging level can be set with the -d option.

Usage:

if nmap.debugging() > 0 then ... end

Return value:

The debugging level.

ethernet_close ()

Closes an ethernet interface.

An error ("device is not valid ethernet interface") is thrown in case the provided argument is not valid.

Usage:

dnet:ethernet_close()

See also:

ethernet_open (interface_name)

Opens an ethernet interface for raw packet sending.

An error ("device is not valid ethernet interface") is thrown in case the provided argument is not valid.

Parameters

interface_name

The dnet-style name of the interface to open.

Usage:

dnet:ethernet_open("eth0")

See also:

ethernet_send (packet)

Sends a raw ethernet frame.

The dnet object must be associated with a previously opened interface. The packet must include the IP and ethernet headers. If there was no previous valid call to ethernet_open an error is thrown ("dnet is not valid opened ethernet interface").

Parameters

packet

An ethernet frame to send.

Usage:

dnet:ethernet_send(packet)

See also:

fetchfile (filename)

Searches for the specified file relative to Nmap's search paths and returns a string containing its path if it is found and readable (to the process). Absolute paths and paths relative to the current directory will not be searched.

If the file is not found, not readable, or is a directory, nilis returned.

Parameters

filename

Filename to search for.

Usage:

nmap.fetchfile("nmap-rpc") --> "/usr/local/share/nmap/nmap-rpc"

Return value:

String representing the full path to the file or nil.

get_info ()

Gets information about a socket.

This function returns information about a socket object. It returns five values. If an error occurred, the first value is false ornil and the second value is an error string. Otherwise the first value is true and the remaining 4 values describe both endpoints of the TCP connection. If you put the call inside an exception handler created bynew_try the status value is consumed. The call can be used for example if you want to query an authentication server.

Usage:

local status, lhost, lport, rhost, rport = socket:get_info()

Return values:

  1. Status (true or false).
  2. Local IP address (if status is true) or error string (if status is false).
  3. Local port number (if status is true).
  4. Remote IP address (if status is true).
  5. Remote port number (if status is true).

See also:

get_interface ()

Returns the interface name provided via the -e option.

For example in the pre-scanning ("prerule" scripts) phase if Nmap is run with the -e eth0, then "eth0" will be returned. Other "hostrule" and "portrule" scripts should use the interface field of the host table:host.interface.

The result of this function can be used to get the interface information table, example: nmap.get_interface_info("eth0").

Usage:

local interface_name = nmap.get_interface()

Return value:

A string containing the interface name (dnet-style) on success, or a nil value if the -e option was not used.

get_interface_info (interface_name)

Gets the interface network information.

This function takes a dnet-style interface name and returns a table containing the network information of the interface.

Keys of the returned table:

Parameters

interface_name

The name of the interface.

Usage:

local iface, err = nmap.get_interface_info("eth0")

Return value:

Table containing the network information of the interface on success, or nil and an error message on failures.

get_payload_length ()

Returns the payload data length selected with the --data-length option

Used when a script is crafting ICMP packets and needs to comply with the selected payload data length. If there is no value specified this function returns 0 which is the default length of the ICMP payload for Nmap.

Usage:

local payload_length = nmap.get_payload_length

Return value:

A number containing the value of the payload length

get_port_state (host, port)

Gets a port table for a port on a given host.

This function takes a host table and a port table and returns a port table for the queried port. The port table returned is similar in structure to the ones passed to the hostrule, portrule, andaction functions. If the given port was not scanned the function returns nil.

You can of course reuse the host and port tables passed to a script's rule function. The purpose of this call is to be able to match scripts against more than one open port. For example if the target host has an open port 22 and a running identd server, then you can write a script which will only fire if both ports are open and there is an identification server on port 113. While it is possible to specify IP addresses different to the currently scanned target, the result will only be correct if the target is in the currently scanned group of hosts.

Parameters

host

Host table, containing an ip field.

port

Port table, containing number andprotocol fields.

Usage:

p = nmap.get_port_state({ip="127.0.0.1"}, {number="80", protocol="tcp"})

Return value:

A new port table holding the status and information for the port, or nil.

get_ports (host, port, proto, state)

Iterates over port tables matching protocol and state for a given host

This function takes a host table, previous port table, port protocol and port state to return matching port tables on a host.

The first time you call this function, pass nil for the port parameter to get the first matching port table. From then on, pass the previous port table returned by this function to the port parameter for the next matching port table.

Parameters

host

Host table, containing an ip field

port

Port table, containing a number field; or nilfor first port

proto

Port protocol, such as "tcp"

state

Port state, such as "open"

Usage:

port = nmap.get_ports(host, port, "tcp", "open")

Return value:

Next port table for host, or nil when exhausted

get_ssl_certificate ()

Retrieves the SSL certificate of the peer. The returned value can be accessed like a table and has the following members:

subject = { commonName = "...", countryName = "...", { "2", "5", "4", "15" } = "...", ... }, issuer = { commonName = "...", ... }, pubkey = { type = "rsa", bits = 1024 }, validity = { notBefore = { year = 2020, month = 5, day = 5, hour = 0, min = 0, sec = 0 }, notAfter = { year = 2021, month = 5, day = 5, hour = 0, min = 0, sec = 0 } }, pem = "-----BEGIN CERTIFICATE-----\nMIIFxzCCBK+gAwIBAgIQX02QuADDB7CVj..."

If the pubkey is type "rsa", it will also have anexponent member, containing the public exponent as a bignum. If the type is "ec", it will have an ecdhparams.curve_paramsmember, containing a table with ec_curve_type andcurve keys as strings.

It also has the following member functions:

The "subject" and "issuer" fields hold each distinguished name. Fields with an unknown OID are represented as an array whose elements are the numeric components of the OID, encoded as strings.

The "validity" table has the members "notBefore"and "notAfter". Each of these is a table as returned byos.date("!*t") if the date in the certificate could be parsed, except that they lack the "wday" and "yday"members. If the date could not be parsed, the value will be a string containing the raw byte values of the field. If absent, the value will benil.

The "pem" field contains a PEM-encoded string of the entire contents of the certificate.

Usage:

local s = nmap.new_socket() local status, error = s:connect(host, port, "ssl") if status then local cert = s:get_ssl_certificate() local digest = cert:digest("md5") end

Return value:

A table as described above.

get_ttl ()

Returns the TTL (time to live) value selected by the --ttl option

If there is no value specified or if the value specified with the --ttl option is out of the range 0 to 255 (inclusive) this function returns 64, which is the default TTL for an IP packet. This function would be most useful in crafting packets, which we want to comply with the selected Nmap TTL value.

Usage:

local ttl = nmap.get_ttl()

Return value:

A number containing the TTL value

have_ssl ()

Determines whether Nmap was compiled with SSL support.

This can be used to avoid sending SSL probes when SSL is not available.

Return value:

True if Nmap was compiled with SSL support, false otherwise.

ip_close ()

Closes a raw IPv4 socket.

Usage:

dnet:ip_close()

See also:

ip_open ()

Opens a socket for raw IPv4 packet sending.

Usage:

dnet:ip_open()

See also:

ip_send (packet, dst)

Sends a raw IPv4 or IPv6 packet.

The dnet object must be associated with a previously opened socket. The packet must begin with an IP header. If there was no previous valid call to ip_open an error is thrown.

Parameters

packet

An IP packet to send.

dst

A destination address, as a host table or string. If omitted, the destination address is read from the packet; however this is deprecated, because the packet does not contain the scope ID required to send to certain IPv6 addresses.

Usage:

dnet:ip_send(packet, dst)

See also:

is_privileged ()

Returns whether a script should be able to perform privileged operations

Return value:

True if Nmap is running privileged, false otherwise.

list_interfaces ()

Lists network interfaces

This script enumerates all network interfaces and returns a list of tables containing information about every interface. If an interface has more than one network address configured (such as IPv4, IPv6 link-local, IPv6 public) then the list will have a separate entry for each address.

Keys of each table:

Usage:

local interfaces, err = nmap.list_interfaces()

Return value:

Array of tables containing information about every discovered interface.

log_write (file, string)

Writes to a log file.

Writes string to file ("stdout" or "stderr"). Use stdnse.debug to print debug information based on the debugging level.

Parameters

file

string

See also:

mutex (object)

Create a mutex on an object.

This function returns another function that works as a mutex on the object passed. This object can be any Lua data type except nil, Booleans, and Numbers. The Mutex (the returned function) allows you to lock, try to lock, and release the mutex. The Mutex function takes only one argument, which must be one of

NSE maintains a weak reference to the Mutex function so other calls to nmap.mutex with the same object will return the same function (Mutex); however, if you discard your reference to the Mutex then it may be collected and subsequent calls to nmap.mutex with the object will return a different Mutex!

Parameters

object

Object to create a mutex for.

Usage:

id = "My Script's Unique ID"

local mutex = nmap.mutex(id) function action(host, port) mutex "lock" -- do stuff mutex "done" return script_output end

Return value:

Mutex function which takes one of the following arguments:"lock", "trylock", "done", or"running".

new_dnet ()

Creates a new dnet object, used to send raw packets.

Usage:

local dnet = nmap.new_dnet()

new_socket (protocol, af)

Returns a new NSE socket object.

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. Seemingly blocking I/O calls still return once a specified timeout has been exceeded.

NSE sockets are the recommended way to do network I/O. They supportconnect-style sending and receiving over TCP and UDP (and SSL), as well as raw socket receiving.

Parameters

protocol

a protocol string (optional, defaults to "tcp").

af

an address family string (optional, defaults to nmap.address_family()

Usage:

local socket = nmap.new_socket()

Return value:

A new NSE socket.

See also:

new_try (handler)

Creates a new exception handler.

This function returns an exception handler function. The exception handler is meant to be wrapped around other function calls that may raise an exception. A function raises an exception by making its first return value false and its second return value a message describing the error. When an exception occurs, the exception handler optionally calls a user-provided cleanup function, then terminates the script. When an exception does not occur (the wrapped function's first return value is true), the exception handler strips off the first return value and returns the rest.

The optional cleanup function is passed as the sole argument tonew_try. It can be used to release sockets or other resources before the script terminates.

A function that may raise an exception must follow the return protocol understood by this function: on an exception its return values arefalse or nil followed by an error message; on success its return values are any true value followed by any other results.

Parameters

handler

User cleanup function (optional).

Usage:

local result, socket, try, catch

result = "" socket = nmap.new_socket() catch = function() socket:close() end try = nmap.new_try(catch) try(socket:connect(host, port)) result = try(socket:receive_lines(1)) try(socket:send(result))

pcap_close ()

Closes a pcap device.

Usage:

socket:pcap_close()

See also:

pcap_open (device, snaplen, promisc, bpf)

Opens a socket for raw packet capture.

Parameters

device

The dnet-style interface name of the device you want to capture from.

snaplen

The length of each packet you want to capture (similar to the-s option to tcpdump)

promisc

Boolean value for whether the interface should activate promiscuous mode.

bpf

A string describing a Berkeley Packet Filter expression (like those provided to tcpdump).

Usage:

local socket = nmap.new_socket() socket:pcap_open("eth0", 64, false, "tcp")

See also:

pcap_receive ()

Receives a captured packet.

If an error or timeout occurs, the function returns false and an error message. Otherwise, the function returns true followed by the packet length, layer two header, layer three header and packet capture time.

Usage:

status, plen, l2_data, l3_data, time = socket:pcap_receive()

Return values:

  1. Status (true or false).
  2. The length of the captured packet (this may be smaller than the actual packet length since packets are truncated when the libpcap snaplen parameter is smaller than the total packet length).
  3. Data from the second OSI layer (e.g. ethernet headers).
  4. Data from the third OSI layer (e.g. IPv4 headers).
  5. Packet capture time, as floating point seconds since the epoch

See also:

receive ()

Receives data from an open socket.

The receive method does a non-blocking receive operation on an open socket. On success the function returns true along with the received data. On failure the function returns a false value (false ornil) along with an error string. A failure occurs for example ifreceive is called on a closed socket. The receive call returns to the NSE script all the data currently stored in the receive buffer of the socket. Error conditions are the same as for send.

Usage:

local status, data = socket:receive()

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).

See also:

receive_buf (delimiter, keeppattern)

Reads from a socket using a buffer and an arbitrary delimiter.

This method reads data from the network until it encounters the given delimiter string (or matches the function passed in). This function continues to read from the network until the delimiter is found or the function times out. If data is read beyond the delimiter, that data is saved in a buffer for the next call to receive_buf.

The first argument may be either a pattern or a function. If a pattern, that pattern is used to separate the data. If a function, it must take exactly one parameter (the buffer) and its return values must be in the same format as those of string.find (offsets to the start and the end of the delimiter inside the buffer, or nil if the delimiter is not found). The nselib match.lua module provides functions for matching against regular expressions or byte counts. These functions are suitable as arguments to receive_buf.

NOTE: If a pattern is used, receive_buf will continue to receive data until the pattern matches or there is a timeout. If the service never stops sending non-matching data, receive_buf will never return. Usingmatch.pattern_limit can avoid this by imposing a limit on how many bytes to read before returning the entire non-matching buffer.

The second argument to receive_buf is a Boolean value controlling whether the delimiting string is returned along with the received data (true) or discarded (false).

On success the function returns true along with the received data. On failure the function returns false or nil along with an receive error string. This function may also throw errors for incorrect usage.

Parameters

delimiter

A Lua pattern or a function with return values like those ofstring.find.

keeppattern

Whether to return the delimiter string with any returned data.

Usage:

local status, line = socket:receive_buf("\r?\n", false)

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).

See also:

receive_bytes (n)

Receives bytes from an open connection.

Tries to receive at least n bytes from an open connection. Like in receive_lines, n is the minimum amount of characters we would like to receive. If more arrive, we get all of them. If even one is received then it is returned. If no characters arrive before the operation times out, a "TIMEOUT" error occurs.

The return values and error codes are the same as for send.

Parameters

n

Minimum number of bytes to read.

Usage:

local status, bytes = socket:receive_bytes(1)

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).

See also:

receive_lines (n)

Receives lines from an open connection.

Tries to receive at least n lines from an open connection. A line is a string delimited with \n characters. If no data was was received before the operation times out a "TIMEOUT" error occurs. If even one character was received then it is returned with success. On the other hand, if more than n lines were received, all are returned, not just n. Use stdnse.make_buffer to guarantee only one line is returned per call.

The return values and error codes are the same as for send.

Parameters

n

Minimum number of lines to read.

Usage:

local status, lines = socket:receive_lines(1)

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).

See also:

reconnect_ssl ()

Reconnect the open (connected) socket with SSL.

It is sometimes desirable to request SSL over an established connection. The internal buffers for the socket are cleared when the reconnection is made. Any received data that has not yet been read through a call to receive is lost.

Usage:

local status, err = socket:reconnect_ssl() if not status then return string.format("Can't reconnect with ssl: %s", err) end

resolve (host, family)

Resolves the specified host name using the optional address family and returns a table containing all of the matching addresses.

If no address family is given, resolve() will return all addresses for the name.

Parameters

host

Host name to resolve

family

Address family string (such as "inet") to specify the type of addresses returned

Usage:

local status, t = nmap.resolve("www.kame.net", nmap.address_family())

Return values:

  1. Status (true or false)
  2. Table containing addresses resolved from the host name if status is true, or an error string if status is false

See also:

send (data)

Sends data on an open socket.

This socket method sends the data contained in the data string through an open connection. On success the function returns a true value. If the send operation fails, the function returns a false value (false ornil) along with an error string. The error strings are

Parameters

data

The data to send.

Usage:

local status, err = socket:send(data)

Return values:

  1. Status (true or false).
  2. Error code (if status is false).

See also:

sendto (host, port, data)

Sends data on an unconnected socket to a given destination.

Sockets that have not been connected do not have an implicit destination address, so the send function doesn't work. Instead the destination must be given with each send using this function. The protocol and address family of the socket must have been set innew_socket. On success the function returns a true value. If the send operation fails, the function returns a false value (false or nil) along with an error string. The error strings are

Parameters

host

The hostname or IP address to send to.

port

The port number to send to.

data

The data to send.

Usage:

local status, err = socket:sendto(host, port, data)

Return values:

  1. Status (true or false).
  2. Error code (if status is false).

set_port_state (host, port, state)

Sets the state of a port on a given host.

Using this function, the final port state, reflected in Nmap's results, can be changed for a target. This is useful when Nmap detects a port asopen|filtered, but the script successfully connects to that port. In this case, the script can set the port state to open. This function doesn't change the original port table passed a script's action function.

Parameters

host

Host table, containing an ip field.

port

Port table, containing number andprotocol fields.

state

Port state, like "open" or "closed".

set_port_version (host, port, probestate)

Sets version information on a port.

NSE scripts are sometimes able to determine the service name and application version listening on a port. A whole script category (version) was designed for this purpose. This function is used to record version information when it is discovered.

The host and port arguments to this function should either be the tables passed to the action method or they should have the same structure. The port argument specifies the port to operate on through its numberand protocol fields. and also contains the new version information to set. The version detection fields this function looks at arename, product, version,extrainfo, hostname, ostype,devicetype, service_tunnel, and cpe. All these keys are optional.

The probestate argument describes the state in which the script completed. It is a string, one of: "hardmatched","softmatched", "nomatch","tcpwrapped", or "incomplete"."hardmatched" is almost always used (and is the default), as it signifies a successful match. The other possible states are generally only used for standard version detection rather than the NSE enhancement.

Parameters

host

Host table, containing an ip field.

port

Port table, containing number andprotocol fields, as well as any additional version information fields.

probestate

The state of the probe: "hardmatched","softmatched", "nomatch","tcpwrapped", or "incomplete".

set_timeout (t)

Sets a timeout for socket input and output operations.

After this time, given in milliseconds, socket operations will time out and return. The default value is 30,000 (30 seconds). The lowest allowed value is 10 ms, since this is the granularity of NSE network I/O.

Parameters

t

Timeout in milliseconds.

Usage:

socket:set_timeout(10000)

See also:

timing_level ()

Returns the timing level as a non-negative integer.

Possible return values vary from 0 to 5, corresponding to the six built-in Nmap timing templates. The timing level can be set with the -T option.

Return value:

The timing level.

verbosity ()

Returns the verbosity level as a non-negative integer.

The verbosity level can be set with the -v option. When a script is given by name with the --script option, as opposed to being selected by default or by category, its verbosity level is automatically increased by one.

Usage:

if nmap.verbosity() > 0 then ... end

Return value:

The verbosity level.

version_intensity ()

Returns the version intensity as a non-negative integer.

The version intensity can be set for all version probes with the--version-intensity option. The intensity for version scripts can be overridden with the script-intensity script argument. If overridden, nmap.version_intensity() returns the overridden value automatically. If neither --version-intensity nor the script argument script-intensity are used, the version intensity defaults to 7. When a version script is given by name with the --scriptoption, as opposed to being selected automatically due to -sV, its version intensity is automatically set to maximum (9).

Usage:

portrule = function(host, port) return ... ... and nmap.version_intensity() >= 7 end

Return value:

The version intensity.