Develop your own scripts for Nmap

The Scribe

Discovering Open Ports

What precisely can you do with NSE scripts and how can the tasks be implemented in concrete terms? The first part of this question is easy to answer; the second part is more difficult. You can use your Nmap scripts to collect information about target systems, discover extended data and hidden data, perform brute force to gain access to systems, and check targets for potential vulnerabilities.

Basic Lua skills are required for developing NSE scripts. Additionally, Nmap relies on the NSE API and the powerful NSE library. However, because Lua is easy to read and understand, I'll look at the basic framework of a simple NSE script, which I will call http-vuln-check.nse and which outputs Hello World! when it finds an open port (Listing 1). The script will test a web application for vulnerabilities. Lines starting with two dashes (--) are comments.

Listing 1

Hello World!

-- Header --
-- Rule --
portrule = function(host, port)
return port.protocol == "tcp"
and port.number == 80
and port.state == "open"
-- Action --
action = function(host, port)
return "Hello World!"

The previous script consists of three sections. In the Header, you store a variety of metadata on the script function, the objective, the author, and the category. The Rule section is where you define the conditions required to run the script. This script must contain at least one of the functions described above: portrule, hostrule, prerule, or postrule.

Most scripts use at least the portrule function. In the example here, the portrule function relies on the Nmap API to test TCP port 80.

The Action section defines the script's logic, which is very simple in this case: If the script finds an open TCP port 80, it outputs the message Hello World! .

To test the script on a local web server, run the following command:

# nmap --script /path/http-vuln-check local targetlhost -p 22,80,443

The output should look something like Listing 2.

Listing 2

Sample Output

Starting Nmap 6.47 ( at 2015-03-12:00:00 CET
Nmap scan report for targethost (
Host is up (0.023s latency).
rDNS record for localhost
22/tcp filtered ssh
80/tcp open http
|_http-vuln-check: Hello World!
443/tcp open https
Nmap done: 1 IP address (1 host up) scanned in 0.23 seconds

If you use Zenmap, the Nmap GUI for scanning (see the box called "Kali Linux Toolbox"), the scan results will be displayed in the Nmap Output tab (Figure 2). If you run Nmap at the command line, you will see typical console output.

Figure 2: You can run your own script with Zenmap if you prefer not to work at the command line.

Kali Linux Toolbox

Nmap has an excellent reputation as a port scanner, but a port scanner alone is not a complete toolbox for comprehensive analysis of your critical network components. Once you have seen the need to perform different security checks, your next question is likely to be what is the best environment for the job. The Debian-based Kali Linux distribution, which includes Nmap and the Nmap GUI Zenmap is perfect.

If you want to use Nmap with your own scripts, this will be easy to do with Kali Linux for a couple of reasons: For one, an Nmap installation in Kali Linux is immediately ready for action; for another, Zenmap is a top-class GUI for managing Nmap and running NSE scripts. Thanks to the GUI, running Nmap is child's play; you can conveniently define the target system to scan and the scan variants, which start with ping scans and include everything up to comprehensive port analyses.

Zenmap is also suitable for less experienced users; the program shows you the Nmap command that actually runs below the target and scan variants along with all the command's options. The GUI also has a visualization of the network structure. The computer viewer delivers technical details of the analyzed system depending on the scan variant (Figure 3).

Figure 3: Zenmap in action. With the GUI, managing the scanner and evaluating the results from the acquired data are far easier.

What makes NSE so powerful and versatile is the use of libraries, which you can easily integrate into your scripts. One of the most commonly used libraries is shortport.http , which executes short portrule functions. The modified script configuration looks like Listing 3.

Listing 3

Modified Script Configuration

-- Header --
local shortport = require "shortport"
-- Rule --
portrule = shortport.http
-- Action --
action = function(host, port)
      return "Hello World!"

The direct comparison between the two script configurations shows that the NSE code can be vastly simplified thanks to the shortport library. Because the shortport.http library checks all the typical HTTP ports (80, 443, 631, 7080, 8080, 8088, 5800, 3872, 8180, 8000) and the various services (http, https, ipp, http-proxy, etc.), you see far more information about the target system.

Final Polishing

Often, the objective of a script is to discover more about services and vulnerabilities of a target. To do this, you need to extend the basic script slightly. To check the vulnerability of a web application, I will attempt to download a web page and evaluate the web server's response (Listing 4).

Listing 4

Checking for Vulnerabilities

-- Header --
local shortport = require "shortport"
local http = require "http"
-- Rule --
portrule = shortport.http
-- Action --
action = function(host, port)
      local uri = "/index.html"
      local response = http.get(host, port, uri)
      return response.status

The previous example relies on the http [3] library. You could continue refining the script and only generate output if HTTP code 200 is returned.

The next step is usually to identify specific vulnerabilities. Again, this is typically easier than you might think; all you need to do in most cases is identify the service version. In this example, you can turn to the string library and modify the script header as follows:

local string = require "string"

To allow third parties to use your script, you need to do some polishing of the header. It can contain a variety of details. In combination with the @ sign, you can include details of usage (@usage) and output (@output) in the header. Listing 5 shows an example of a simple header.

Listing 5

Header Example

-- Header --
description = [[Example to introduce developing your own Nmap scripts]]
-- @usage
-- nmap --script http-vuln-check target_host
-- @output
-- 80/tcp open http
-- |_http-vuln-check: Vulnerable
author = "holger reibold"
license = "like nmap"
categories = {"default", "safe"}
local shortport = require "shortport"

After reaching this point, you will probably be interested in how to delve more deeply into the development of NSE scripts. The best approach is to study the NSE library, where you will find a huge amount of input for analyzing services other than HTTP. Nmap has more interesting opportunities to offer – for example, parallel scanning of various hosts.


Nmap is a top-ranked port scanner that is well equipped to analyze typical network components in the standard configuration. In combination with NSE and the comprehensive libraries, the scanner can easily be tuned for handling your required tasks, which means Nmap is still unrivaled.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Protect Your Servers with Nmap

    If you've ever had to test the security of your servers, you've almost certainly come across the ever-flexible Nmap (Network Mapper) – used by sys admins to help protect their servers and diagnose problems.

  • Nmap 6.0 Released
  • BackTrack Linux: The Ultimate Hacker's Arsenal

    Penetration Testing and security auditing are now part of every system administrator's "other duties as assigned." BackTrack Linux is a custom distribution designed for security testing for all skill levels from novice to expert.

  • Managing Port Scan Results with Dr. Portscan

    Regularly scanning the ports on your own network prevents intruders from sneaking in, but if you have dozens or hundreds of servers, you’ll need professional help: Dr. Portscan to the rescue.

  • Security as Code
    Gauntlt is a sophisticated DevOps tool that can test the security of your continuous integration/continuous delivery pipeline.
comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=