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

Libraries often accidentally make use of globals variables when local scope was intended. Two or more scripts that make use of library functions which unintentionally use the same global variable will find that variable constantly rewritten. This is a serious bug that can cause NSE to stall or a correct script to spectacularly fail, and, because Lua uses global-by-default scope assignment when it encounters a variable, this is also a common bug.

Consider a global variable being used by two different scripts, within the library, to hold sockets or data. When one script is yielded after storing data in the variable, another script awakens only to replace that data. In contrast, a local variable would store the information on the stack of the running script separate from others.

To help correct this problem, NSE now uses an adapted library 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.

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_register 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 smallest compiled module that comes with NSE is bit, and one of the most straightforward is openssl. These modules serve as good examples for a beginning module writer. The source code for bit is found in nse_bit.cc and nse_bit.h, while the 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_register 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_register(L, OPENSSLLIBNAME, 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_init.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”).