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:

Status (true or false).
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:

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

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.

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:

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

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

Parameters

interface_name: The dnet-style name of the interface to open.

Usage:

dnet:ethernet_open("eth0")

Parameters

packet: An ethernet frame to send.

Usage:

dnet:ethernet_send(packet)

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:

Status (true or false).
Local IP address (if status is true) or error string (if status is false).
Local port number (if status is true).
Remote IP address (if status is true).
Remote port number (if status is true).

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

Usage:

dnet:ip_open()

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)

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

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.

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

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

Usage:

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

Return values:

Status (true or false).
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).
Data from the second OSI layer (e.g. ethernet headers).
Data from the third OSI layer (e.g. IPv4 headers).
Packet capture time, as floating point seconds since the epoch

Usage:

local status, data = socket:receive()

Return values:

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

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:

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

Parameters

n: Minimum number of bytes to read.

Usage:

local status, bytes = socket:receive_bytes(1)

Return values:

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

Parameters

n: Minimum number of lines to read.

Usage:

local status, lines = socket:receive_lines(1)

Return values:

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

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:

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

Parameters

data: The data to send.

Usage:

local status, err = socket:send(data)

Return values:

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

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:

Status (true or false).
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)

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.

Library nmap

Functions

Functions

Usage:

Return value:

Parameters

Usage:

Return values:

Usage:

Return value:

Usage:

Return value:

Usage:

Return values:

See also:

Parameters

Usage:

Return value:

See also:

Parameters

Usage:

Return values:

See also:

Usage:

Return value:

Usage:

See also:

Parameters

Usage:

See also:

Parameters

Usage:

See also:

Parameters

Usage:

Return value:

Usage:

Return values:

See also:

Usage:

Return value:

Parameters

Usage:

Return value:

Usage:

Return value:

Parameters

Usage:

Return value:

Parameters

Usage:

Return value:

Usage:

Return value:

Usage:

Return value:

Return value:

Usage:

See also:

Usage:

See also:

Parameters

Usage:

See also:

Return value:

Usage:

Return value:

Parameters

See also:

Parameters

Usage:

Return value:

Usage:

Parameters

Usage:

Return value:

See also:

Parameters

Usage:

Usage:

Library `nmap`