Library nmap

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.

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

Functions

address_family ()

Returns the address family Nmap is using.

bind (addr, port)

Sets the local address of a socket.

clock ()

Returns the current date and time in seconds.

clock_ms ()

Returns the current date and time in milliseconds.

close ()

Closes an open connection.

condvar (object)

Create a condition variable for an object.

connect (host, port, protocol)

Establishes a connection.

debugging ()

Returns the debugging level as a non-negative integer.

ethernet_close ()

Closes an ethernet interface.

ethernet_open (interface_name)

Opens an ethernet interface for raw packet sending.

ethernet_send (packet)

Sends a raw ethernet frame.

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.

get_info ()

Gets information about a socket.

get_interface ()

Returns the interface name (dnet-style) that Nmap is using.

get_interface_info (interface_name)

Gets the interface network information.

get_payload_length ()

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

get_port_state (host, port)

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

get_ports (host, port, proto, state)

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

get_ssl_certificate ()

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

get_ttl ()

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

have_ssl ()

Determines whether Nmap was compiled with SSL support.

ip_close ()

Closes a raw IPv4 socket.

ip_open ()

Opens a socket for raw IPv4 packet sending.

ip_send (packet, dst)

Sends a raw IPv4 or IPv6 packet.

is_privileged ()

Returns whether a script should be able to perform privileged operations

list_interfaces ()

Lists network interfaces

log_write (file, string)

Writes to a log file.

mutex (object)

Create a mutex on an object.

new_dnet ()

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

new_socket (protocol, af)

Returns a new NSE socket object.

new_try (handler)

Creates a new exception handler.

pcap_close ()

Closes a pcap device.

pcap_open (device, snaplen, promisc, bpf)

Opens a socket for raw packet capture.

pcap_receive ()

Receives a captured packet.

receive ()

Receives data from an open socket.

receive_buf (delimiter, keeppattern)

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

receive_bytes (n)

Receives bytes from an open connection.

receive_lines (n)

Receives lines from an open connection.

reconnect_ssl ()

Reconnect the open (connected) socket with SSL.

resolve (host, family)

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

send (data)

Sends data on an open socket.

sendto (host, port, data)

Sends data on an unconnected socket to a given destination.

set_port_state (host, port, state)

Sets the state of a port on a given host.

set_port_version (host, port, probestate)

Sets version information on a port.

set_timeout (t)

Sets a timeout for socket input and output operations.

timing_level ()

Returns the timing level as a non-negative integer.

verbosity ()

Returns the verbosity level as a non-negative integer.

version_intensity ()

Returns the version intensity as a non-negative integer.

Functions

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 bind overrides 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 except nil, 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

  • "wait": Wait on the condition variable until another thread wakes us.
  • "signal": Wake up a single thread from the waiting set of threads for this condition variable.
  • "broadcast": Wake up all threads in the waiting set of threads for this condition variable.

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 is port.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 name is given, it is used to request the correct certificate in SSL connections. Passing a string instead of a host table acts like host.ip and host.name were set to the same value. If port is 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):

  • "Address family for hostname not supported" (EAI_ADDRFAMILY)
  • "Temporary failure in name resolution" (EAI_AGAIN)
  • "Bad value for ai_flags" (EAI_BADFLAGS)
  • "Non-recoverable failure in name resolution" (EAI_FAIL)
  • "ai_family not supported" (EAI_FAMILY)
  • "Memory allocation failure" (EAI_MEMORY)
  • "No address associated with hostname" (EAI_NODATA)
  • "Name or service not known" (EAI_NONAME)
  • "Servname not supported for ai_socktype" (EAI_SERVICE)
  • "ai_socktype not supported" (EAI_SOCKTYPE)
  • "System error" (EAI_SYSTEM)
In addition to these standard system error messages there are two NSE-specific errors:
  • "Sorry, you don't have OpenSSL": The protocol is "ssl" but Nmap was compiled without OpenSSL support.
  • "invalid connection method": The second parameter is not one of "tcp", "udp", and "ssl".

Parameters

host
Host table, hostname or IP address.
port
Port table or number.
protocol
"tcp", "udp", or "ssl" (default "tcp", or whatever was set in new_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, nil is 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 or nil 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 by new_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 (dnet-style) that Nmap is using.

For example in the pre-scanning ("prerule" scripts) phase if Nmap is run with the -e eth0, then "eth0" can be returned, however Nmap can return an other interface name since it can determine the best interface suited for the job. 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 on failures.
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:

  • device The interface name, can be an interface alias.
  • shortname A simple short name of the device.
  • netmask The netmask bits (CIDR) of the interface.
  • address The string representing the IP address assigned to the interface.
  • link The string representing the hardware type of the interface. Possible values are: "ethernet", "loopback", "p2p" or "other".
  • mac MAC address (six-byte-long binary string) of the interface if the type of the interface is "ethernet", otherwise it is nil.
  • broadcast The string representing the broadcast address assigned to the interface if the interface type is "ethernet" and if the used address is IPv4, otherwise it is nil.
  • up The state of the interface, possible values are "up" or "down".
  • mtu The MTU size of the interface.

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, and action 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 and protocol 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 nil for 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 an exponent member, containing the public exponent as a bignum. If the type is "ec", it will have an ecdhparams.curve_params member, containing a table with ec_curve_type and curve keys as strings.

It also has the following member functions:

  • digest(algorithm) returns the digest of the certificate using the given digest algorithm, which is any of the strings returned by openssl.supported_digests, typically something like "md5" or "sha1".

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 by os.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 be nil.

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:

  • device The interface name, can be an interface alias.
  • shortname A simple short name of the device.
  • netmask The netmask bits (CIDR) of the interface.
  • address The string representing the IP address assigned to the interface.
  • link The string representing the hardware type of the interface. Possible values are: "ethernet", "loopback", "p2p" or "other".
  • mac MAC address (six-byte-long binary string) of the interface if the type of the interface is "ethernet", otherwise it is nil.
  • broadcast The string representing the broadcast address assigned to the interface if the interface type is "ethernet" and if the used address is IPv4, otherwise it is nil.
  • up The state of the interface, possible values are "up" or "down".
  • mtu The MTU size of the interface.

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

  • "lock": makes a blocking lock on the mutex. If the mutex is busy then the thread will yield and wait. The function returns with the mutex locked.
  • "trylock": makes a non-blocking lock on the mutex. If the mutex is busy then it immediately returns a false value. Otherwise, the mutex locks the mutex and returns true.
  • "done": releases the mutex and allows another thread to lock it. If the thread does not have a lock on the mutex, an error will be raised.
  • "running": returns the thread locked on the mutex or nil if no thread is locked. This should only be used for debugging as it interferes with finished threads from being collected.

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 support connect-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 "inet").

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 to new_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 are false 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 or nil) along with an error string. A failure occurs for example if receive 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. Using match.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 of string.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 or nil) along with an error string. The error strings are

  • "Trying to send through a closed socket": There was no call to socket:connect before the send operation.
  • "TIMEOUT": The operation took longer than the specified timeout for the socket.
  • "ERROR": An error occurred inside the underlying Nsock library.
  • "CANCELLED": The operation was cancelled.
  • "KILL": For example the script scan is aborted due to a faulty script.
  • "EOF": An EOF was read (probably will not occur for a send operation).

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 in new_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

  • "TIMEOUT": The operation took longer than the specified timeout for the socket.
  • "ERROR": An error occurred inside the underlying Nsock library.
  • "CANCELLED": The operation was cancelled.
  • "KILL": For example the script scan is aborted due to a faulty script.
  • "EOF": An EOF was read (probably will not occur for a send operation).

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 as open|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 and protocol 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 number and protocol fields. and also contains the new version information to set. The version detection fields this function looks at are name, 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 and protocol 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 --script option, 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.