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.

Functions

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 and returns a string containing its path if it is found and readable (to the process).
get_info ()	Gets information about a socket.
get_interface_link (interface_name)	Gets the link-level hardware type of an interface.
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:
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)	Sends a raw IPv4 packet.
is_privileged ()	Returns whether a script should be able to perform privileged operations
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 ()	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, test_function, bpf)	Opens a socket for raw packet capture.
pcap_receive ()	Receives a captured packet.
pcap_register (packet_hash)	Starts listening for incoming packets.
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.
send (data)	Sends data on an open socket.
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.

Functions

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

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

Parameters

interface_name: The name of the interface.

Usage:

iface_type = nmap.get_interface_link("eth0")

Return value:

"ethernet", "loopback", "p2p", or nil.

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 = "...", ... },
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..."

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, typicaly 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.

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.

Usage:

dnet:ip_send(packet)

Return value:

True if Nmap is running privileged, false otherwise.

log_write (file, string)

Writes to a log file.

Writes string to file ("stdout" or "stderr"). Use stdnse.print_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 ()

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.

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: Set to 1 if the interface should activate promiscuous mode, and 0 otherwise.
test_function: Callback function used to compute the packet hash.
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, 0, callback, "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

Parameters

packet_hash: A binary string that is compared against packet hashes.

Usage:

socket:pcap_register("")

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

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:

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

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, and service_tunnel. 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.

NSEDoc

Categories

Scripts (show 134)(134)Scripts (134)

Libraries (show 47)(47)Libraries (47)

Library nmap

Functions

Functions

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:

Parameters

Usage:

Return value:

Parameters

Usage:

Return value:

Parameters

Usage:

Return value:

Usage:

Return value:

Return value:

Usage:

See also:

Usage:

See also:

Parameters

Usage:

See also:

Return value:

Parameters

See also:

Parameters

Usage:

Return value:

Usage:

Usage:

Return value:

See also:

Parameters

Usage:

Usage:

See also:

Parameters

Usage:

See also:

Usage:

Return values:

See also:

Library `nmap`