There are times when you will realize that the code you are writing could be put into a library to be re-used by other NSE scripts. The process of writing an NSE library is straightforward, and there are only certain things that we need to consider, such as not accessing global variables used by other scripts. Although Lua modules are preferred, the Nmap Scripting Engine also supports C modules via the Lua C API, for those looking for that extra performance.
This recipe will teach you how to create your own Lua NSE library.
Creating a library has a similar process to writing scripts. Just keep in mind the scope of the variables that you are working with. Let's create a simple library:
- Create a new file
mylibrary.lua, and start by typing the required libraries you may need:local math = require "math"
- Now, simply add the functions to your library. We will create a function that returns the classic
"Hello World!"message:function hello_word() return "Hello World!" end
- Place your library file inside the directory
/nselib/. Create a new NSE script and add therequire()call inside of it:local mylibrary = require "mylibrary"
- Execute your method from inside your script. If the method can't be accessed, you probably set an incorrect scope assignment for the function:
mylibrary.hello_world()
The LUA NSE libraries are stored inside the directory /nselib/ in your configured data directory. To create our own libraries we just need to create the .lua file and place it in that directory:
--hello.lua
local stdnse = require "stdnse"
function hello(msg, name)
return stdnse.format("%s %s", msg, name)
endNSE scripts can now import your NSE library and call the available functions:
local hello = require "hello" ... hello.foo()
It is important to document your library well before submitting it to <[email protected]> in order to help other developers quickly understand the purpose and functionality of your new library.
To avoid overriding global variables used in other scripts by mistake, include the module strict.lua. This module will alert you every time you access or modify undeclared global variables at runtime.
If something unexpected happens, turn on debugging to get additional information. Nmap uses the flag -d for debugging and you can set any integer between 0 and 9:
$ nmap -p80 --script http-google-email -d4 <target>
The library nmap provides an exception handling mechanism for NSE scripts, which is designed to help with networking I/O tasks.
The exception handling mechanism from the nmap library works as expected. We wrap the code that we want to monitor for exceptions inside a nmap.try() call. The first value returned by the function indicates the completion status. If it returns false or nil, the second returned value must be an error string. The rest of the return values in a successful execution can be set and used as you wish. The catch function defined by nmap.new_try() will execute when an exception is raised.
The following example is a code snippet of the script mysql-vuln-cve2012-2122.nse (http://nmap.org/nsedoc/scripts/mysql-vuln-cve2012-2122.html). In this script a catch function performs some simple garbage collection if a socket is left open:
local catch = function() socket:close() end local try = nmap.new_try(catch) … try( socket:connect(host, port) ) response = try( mysql.receiveGreeting(socket) )
The official documentation of the NSE library nmap can be found at http://nmap.org/nsedoc/lib/nmap.html.
Some modules included with the Nmap Scripting Engine are written in C++ or C. These languages provide enhanced performance and are recommended when that is a critical aspect of the required task.
We can use compiled C modules with the Lua C API in our scripts by following the protocols described extensively at:
- The Making HTTP requests to identify vulnerable Trendnet webcams recipe
- The Sending UDP payloads by using NSE sockets recipe
- The Exploiting a path traversal vulnerability with NSE recipe
- The Writing a brute force script recipe
- The Working with the web crawling library recipe
- The Reporting vulnerabilities correctly in NSE scripts recipe