NSE Libraries

In addition to the significant built-in capabilities of Lua, we have written or integrated many extension libraries which make script writing more powerful and convenient. These libraries (sometimes called modules) are compiled if necessary and installed along with Nmap. They have their own directory, nselib, which is installed in the configured Nmap data directory. Scripts need only require the default libraries in order to use them.

List of All Libraries

This list is just an overview to give an idea of what libraries are available. Developers will want to consult the complete documentation at https://nmap.org/nsedoc/.


This library was written by Patrik Karlsson <patrik@cqure.net> to facilitate communication with the Apple AFP Service. It is not feature complete and still missing several functions.


A basic AJP 1.3 implementation based on documentation available from Apache mod_proxy_ajp; http://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html


The AMQP library provides some basic functionality for retrieving information about an AMQP server's properties.


ASN.1 functions.


Base32 encoding and decoding. Follows RFC 4648.


Base64 encoding and decoding. Follows RFC 4648.


Pack and unpack binary data.


Bitwise operations on integers.


This library implements a minimal subset of the BitCoin protocol It currently supports the version handshake and processing Addr responses.


Bittorrent and DHT protocol library which enables users to read information from a torrent file, decode bencoded (bittorrent encoded) buffers, find peers associated with a certain torrent and retrieve nodes discovered during the search for peers.


An implementation of the Canon BJNP protocol used to discover and query Canon network printers and scanner devices.


The brute library is an attempt to create a common framework for performing password guessing against remote services.


Library methods for handling Cassandra Thrift communication as client


This module was written by Patrik Karlsson and facilitates communication with the Citrix XML Service. It is not feature complete and is missing several functions and parameters.


Common communication functions for network discovery tasks like banner grabbing and data exchange.


The credential class stores found credentials in the Nmap registry


A minimal CVS (Concurrent Versions System) pserver protocol implementation which currently only supports authentication.


Read and parse some of Nmap's data files: nmap-protocols, nmap-rpc, nmap-services, and nmap-mac-prefixes.


Implement a Dynamic Host Configuration Protocol (DHCP) client.


Minimalistic DHCP6 (Dynamic Host Configuration Protocol for IPv6) implementation supporting basic DHCP6 Solicit requests The library is structured around the following classes:

(for responses)


Simple DNS library supporting packet creation, encoding, decoding, and querying.


A minimalistic DNS BlackList library implemented to facilitate querying various DNSBL services. The current list of services has been implemented based on the following compilations of services:


Library for supporting DNS Service Discovery


DRDA Library supporting a very limited subset of operations.


EAP (Extensible Authentication Protocol) library supporting a limited subset of features.


A library supporting parsing and generating a limited subset of the Cisco' EIGRP packets.


FTP functions.


GIOP Library supporting a very limited subset of operations


A smallish gps parsing module. Currently does GPRMC NMEA decoding


Implements the HTTP client protocol in a standard form that Nmap scripts can take advantage of.


A smallish httpspider library providing basic spidering capabilities It consists of the following classes:


A minimalistic Asterisk IAX2 (Inter-Asterisk eXchange v2) VoIP protocol implementation. The library implements the minimum needed to perform brute force password guessing.


A library implementing a minor subset of the IMAP protocol, currently the CAPABILITY, LOGIN and AUTHENTICATE functions. The library was initially written by Brandon Enright and later extended and converted to OO-form by Patrik Karlsson <patrik@cqure.net>


Informix Library supporting a very limited subset of Informix operations


Utility functions for manipulating and comparing IP addresses.


A small CUPS ipp (Internet Printing Protocol) library implementation


An iSCSI library implementing written by Patrik Karlsson <patrik@cqure.net> The library currently supports target discovery and login.


A minimal Internet Storage Name Service (iSNS) implementation


JDWP (Java Debug Wire Protocol) library implementing a set of commands needed to use remote debugging port and inject java bytecode.


Library methods for handling JSON data. It handles JSON encoding and decoding according to RFC 4627.


Library methods for handling LDAP.


Returns a directory iterator listing the contents of the given path Each time the iterator is called with dir_obj it returns a directory entry's name as a string, or nil if there are no more entries.


Functional-style list operations.


Buffered network I/O helper functions.


A smallish implementation of the Couchbase Membase TAP protocol Based on the scarce documentation from the Couchbase Wiki: x http://www.couchbase.org/wiki/display/membase/SASL+Authentication+Example


A MobileMe web service client that allows discovering Apple devices using the "find my iPhone" functionality.


Library methods for handling MongoDB, creating and parsing packets.


By making heavy use of the smb library, this library will call various MSRPC functions. The functions used here can be accessed over TCP ports 445 and 139, with an established session. A NULL session (the default) will work for some functions and operating systems (or configurations), but not for others.


This module is designed to parse the PERF_DATA_BLOCK structure, which is stored in the registry under HKEY_PERFORMANCE_DATA. By querying this structure, you can get a whole lot of information about what's going on.


This module was written to marshall parameters for Microsoft RPC (MSRPC) calls. The values passed in and out are based on structs defined by the protocol, and documented by Samba developers. For detailed breakdowns of the types, take a look at Samba 4.0's .idl files.


MSSQL Library supporting a very limited subset of operations.


Simple MySQL Library supporting a very limited subset of operations.


This library implements the basics of NAT-PMP as described in the NAT Port Mapping Protocol (NAT-PMP) draft: o http://tools.ietf.org/html/draft-cheshire-nat-pmp-03


A tiny implementation of the Netware Core Protocol (NCP). While NCP was originally a Netware only protocol it's now present on both Linux and Windows platforms running Novell eDirectory.


A minimalistic NDMP (Network Data Management Protocol) library


Creates and parses NetBIOS traffic. The primary use for this is to send NetBIOS name requests.


Interface with Nmap internals.


A minimalistic library to support Domino RPC


Debugging functions for Nmap scripts.


This library was written to ease interaction with OpenVAS Manager servers using OMP (OpenVAS Management Protocol) version 2.


OpenSSL bindings.


A minimalistic OSPF (Open Shortest Path First routing protocol) library, currently supporting IPv4 and the following OSPF message types: HELLO


Facilities for manipulating raw packets.


Perl Compatible Regular Expressions.


PostgreSQL library supporting both version 2 and version 3 of the protocol. The library currently contains the bare minimum to perform authentication. Authentication is supported with or without SSL enabled and using the plain-text or MD5 authentication mechanisms.


POP3 functions.


A minimalistic PPPoE (Point-to-point protocol over Ethernet) library, implementing basic support for PPPoE Discovery and Configuration requests. The PPPoE protocol is ethernet based and hence does not use any IPs or port numbers.


Functions for proxy testing.


A minimal RDP (Remote Desktop Protocol) library. Currently has functionality to determine encryption and cipher support.


A minimalistic Redis (in-memory key-value data store) library.


Library method for communicating over RMI (JRMP + java serialization)


RPC Library supporting a very limited subset of operations.


This library implements the fundamentals needed to communicate with the WinPcap Remote Capture Daemon. It currently supports authenticating to the service using either NULL-, or Password-based authentication. In addition it has the capabilities to list the interfaces that may be used for sniffing.


A minimalist RSYNC (remote file sync) library


This Real Time Streaming Protocol (RTSP) library implements only a minimal subset of the protocol needed by the current scripts.


Simple Authentication and Security Layer (SASL).


Functions for building short portrules.


A SIP library supporting a limited subset of SIP commands and methods


Implements functionality related to Server Message Block (SMB, an extension of CIFS) traffic, which is a Windows protocol.


This module takes care of the authentication used in SMB (LM, NTLM, LMv2, NTLMv2).


Simple Mail Transfer Protocol (SMTP) operations.


SNMP functions.


A smallish SOCKS version 5 proxy protocol implementation


A relatively small implementation of the Service Location Protocol. It was initially designed to support requests for discovering Novell NCP servers, but should work for any other service as well.


Functions for the SSH-1 protocol. This module also contains functions for formatting key fingerprints.


Functions for the SSH-2 protocol.


A library providing functions for collecting SSL certificates and storing them in the host-based registry.


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


String buffer facilities.


Strict declared global library. Checks for undeclared global variables during runtime execution.


A library that implements the basics of the STUN protocol (Session Traversal Utilities for NAT) per RFC3489 and RFC5389. A protocol overview is available at http://en.wikipedia.org/wiki/STUN.


Arrange output into tables.


Utility functions to add new discovered targets to Nmap scan queue.


Library implementing a minimal TFTP server


TNS Library supporting a very limited subset of Oracle operations


Username/password database library.


A UPNP library based on code from upnp-info initially written by Thomas Buchanan. The code was factored out from upnp-info and partly re-written by Patrik Karlsson <patrik@cqure.net> in order to support multicast requests.


URI parsing, composition, and relative URL resolution.


A tiny library allowing some basic information enumeration from Versant object database software (see http://en.wikipedia.org/wiki/Versant_Corporation). The code is entirely based on packet dumps captured when using the Versant Management Center administration application.


The VNC library provides some basic functionality needed in order to communicate with VNC servers, and derivates such as Tight- or Ultra- VNC.


Functions for vulnerability management.


A Vuze DHT protocol implementation based on the following documentation: o http://wiki.vuze.com/w/Distributed_hash_table


A library that enables scripts to send Web Service Dynamic Discovery probes and perform some very basic decoding of responses. The library is in no way a full WSDD implementation it's rather the result of some packet captures and some creative coding.


Implementation of the XDMCP (X Display Manager Control Protocol) based on: x http://www.xfree86.org/current/xdmcp.pdf


A XMPP (Jabber) library, implementing a minimal subset of the protocol enough to do authentication brute-force.

A common mistake when editing libraries is to accidentally use a global variable instead of a local one. Different libraries using the same global variable can be the cause of mysterious bugs. Lua's scope assignment is global by default, so this mistake is easy to make.

To help correct this problem, NSE uses a library adapted from the standard Lua distribution called strict.lua. The library will raise a runtime error on any access or modification of a global variable which was undeclared in the file scope. A global variable is considered declared if the library makes an assignment to the global name (even nil) in the file scope.

Adding C Modules to Nselib

A few of the modules included in nselib are written in C or C++ rather than Lua. Two examples are bit and pcre. We recommend that modules be written in Lua if possible, but C and C++ may be more appropriate if performance is critical or (as with the pcre and openssl modules) you are linking to an existing C library. This section describes how to write your own compiled extensions to nselib.

The Lua C API is described at length in Programming in Lua, Second Edition, so this is a short summary. C modules consist of functions that follow the protocol of the lua_CFunction type. The functions are registered with Lua and assembled into a library by calling the luaL_newlib function. A special initialization function provides the interface between the module and the rest of the NSE code. By convention the initialization function is named in the form luaopen_<module>.

The most straightforward compiled module that comes with NSE is openssl. This module serves as a good example for a beginning module writer. The source code for openssl source is in nse_openssl.cc and nse_openssl.h. Most of the other compiled modules follow this nse_<module name>.cc naming convention.

Reviewing the openssl module shows that one of the functions in nse_openssl.cc is l_md5, which calculates an MD5 digest. Its function prototype is:

static int l_md5(lua_State *L);

The prototype shows that l_md5 matches the lua_CFunction type. The function is static because it does not have to be visible to other compiled code. Only an address is required to register it with Lua. Later in the file, l_md5 is entered into an array of type luaL_Reg and associated with the name md5:

static const struct luaL_Reg openssllib[] = {
  { "md5", l_md5 },
  { NULL, NULL }

This function will now be known as md5 to NSE. Next the library is registered with a call to luaL_newlib inside the initialization function luaopen_openssl, as shown next. Some lines relating to the registration of OpenSSL BIGNUM types have been omitted:

LUALIB_API int luaopen_openssl(lua_State *L) {
  luaL_newlib(L, openssllib);
  return 1;

The function luaopen_openssl is the only function in the file that is exposed in nse_openssl.h. OPENSSLLIBNAME is simply the string "openssl".

After a compiled module is written, it must be added to NSE by including it in the list of standard libraries in nse_main.cc. Then the module's source file names must be added to Makefile.in in the appropriate places. For both these tasks you can simply follow the example of the other C modules. For the Windows build, the new source files must be added to the mswin32/nmap.vcproj project file using MS Visual Studio (see the section called “Compile from Source Code”).