Writing a Simple NSE Script in Nmap

Introduction to NSE (Nmap Scripting Engine)

Nmap, or Network Mapper, is a powerful open-source tool used for network discovery and security auditing. One of its most versatile features is the Nmap Scripting Engine (NSE), which allows users to write custom scripts to automate tasks, enhance scanning capabilities, and extend Nmap’s functionality.

NSE scripts are written in Lua, a lightweight scripting language, and can perform various tasks, such as:

• Detecting vulnerabilities
• Gathering information about network hosts
• Performing brute-force attacks
• Automating reconnaissance tasks

In this article, we will guide you through writing a simple NSE script from scratch, explaining its structure, key components, and how to run it.

Understanding NSE Script Structure

An NSE script typically follows this structure:

1. Head (Metadata Section) - Provides essential details about the script, such as its name, categories, dependencies, and author.
2. Rule Section - Defines conditions under which the script should execute.
3. Action Section - Contains the main logic of the script.

Here is a simple breakdown of an NSE script:

-- Head Section
local stdnse = require "stdnse" -- Import Nmap standard NSE library
local shortport = require "shortport" -- Import port scanning utilities

-- Description and metadata
description = [[
This is a simple NSE script that checks for a specific open port and responds accordingly.
]]

author = "Your Name"
license = "Same as Nmap"
categories = {"default", "discovery"}

-- Rule Section: Define when this script should run
portrule = shortport.port_or_service(80, "http")

-- Action Section: Define what this script does
function action(host, port)
    return "Port 80 is open on " .. host.ip
end

Step-by-Step Guide to Writing a Simple NSE Script

Step 1: Setting Up Your Environment

Before writing an NSE script, ensure you have Nmap installed. You can verify this by running:

nmap --version

Also, ensure Lua is installed if you want to test your script outside Nmap.

Step 2: Writing a Basic NSE Script

Let’s create a simple NSE script named custom-simple.nse that checks if a specific port (e.g., port 80) is open.

1. Create a New NSE Script File

Open a terminal and navigate to the directory where you want to save the script. Use a text editor like vim, nano, or gedit to create a new file:

nano custom-simple.nse

2. Add the Metadata Section

The metadata section includes details like the author, description, and category.

-- Metadata
local shortport = require "shortport"

description = [[
A basic NSE script that checks for an open HTTP port (80).
]]

author = "Your Name"
categories = {"discovery"}

3. Define the Rule Section

This section determines when the script will execute. We’ll check if port 80 is open.

portrule = shortport.port_or_service(80, "http")

4. Implement the Action Section

This is where we define what happens when the script executes.

function action(host, port)
    return "Port 80 is open on " .. host.ip
end

Step 3: Running the NSE Script

After saving the script, move it to Nmap’s scripts directory. On Linux or macOS, you can use:

sudo mv custom-simple.nse /usr/share/nmap/scripts/

Then, update the Nmap script database:

sudo nmap --script-updatedb

Now, run Nmap with the script:

sudo nmap -p 80 --script=custom-simple.nse <target-IP>

Replace <target-IP> with the actual target’s IP address.

Step 4: Enhancing the Script

To make the script more interactive, let’s modify it to check for additional details like the HTTP server banner.

-- Import additional libraries
local http = require "http"

function action(host, port)
    local response = http.get(host, port)
    if response then
        return "Port 80 is open on " .. host.ip .. " | HTTP Server: " .. (response.header.server or "Unknown")
    else
        return "Port 80 is open, but no HTTP response received"
    end
end

This enhancement fetches the HTTP server’s banner if available.

Debugging and Testing Your Script

To test the script without running a full scan, use Nmap’s debugging mode:

sudo nmap -p 80 --script=custom-simple.nse <target-IP> -d

• -d enables debug mode to provide more details about script execution.
• If you encounter errors, ensure the script is correctly formatted and located in the right directory.

Conclusion

Writing NSE scripts in Nmap allows security professionals and network administrators to customize their scans and automate tasks efficiently. In this guide, we:

• Introduced the basics of NSE scripting
• Explained the script structure
• Created a simple script to check for an open HTTP port
• Enhanced it to retrieve HTTP server details

NSE scripting is a powerful skill that can greatly enhance network reconnaissance and vulnerability assessment. As you become more familiar with Lua and Nmap’s built-in functions, you can create advanced scripts for specific security needs.