27 Jun, 2024
Nmap NSE Script Development Tutorial
Cybersecurity, Nmap

Introduction to Nmap and NSE

Nmap (Network Mapper) is a powerful open-source tool used for network discovery and security auditing. Its capabilities extend beyond simple port scanning, making it a versatile tool for network administrators, security professionals, and developers. One of the most potent features of Nmap is its Scripting Engine (NSE), which allows users to write scripts to automate various network tasks.

NSE scripts can perform a wide range of tasks, from advanced network scanning and vulnerability detection to information gathering and exploitation. This article aims to provide a comprehensive guide to developing Nmap NSE scripts, including practical examples and SEO-optimized content to help you master this powerful tool.



Understanding Nmap NSE

The Nmap Scripting Engine (NSE) is an embedded Lua interpreter that enables users to write scripts for extending Nmap’s functionality. Lua is a lightweight, embeddable scripting language with a simple syntax, making it easy to learn and use.


Key Features of NSE

  1. Extensibility: NSE scripts can be used to extend Nmap’s capabilities beyond basic port scanning.
  2. Automation: Automate repetitive tasks, such as vulnerability scans and data collection.
  3. Flexibility: Perform a wide range of tasks, including vulnerability detection, information gathering, and even exploitation.
  4. Customizability: Create custom scripts tailored to specific network environments and security needs.



Getting Started with NSE Script Development


Setting Up Your Environment

Before you start writing NSE scripts, ensure you have Nmap installed on your system. You can download and install Nmap from the official website: Nmap.org.



Basic Structure of an NSE Script

An NSE script consists of three main sections:

  1. Head: Contains metadata about the script, including its name, description, author, license, categories, and dependencies.
  2. Rule: Defines when the script should be executed.
  3. Action: Contains the script’s main logic and functionality.

Here is a basic template of an NSE script:

-- Head section
description = [[
  A brief description of what the script does.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"default", "discovery"}

-- Rule section
portrule = function(host, port)
  return port.state == "open"
end

-- Action section
action = function(host, port)
  return "Hello, NSE!"
end



Writing Your First NSE Script

Let’s create a simple NSE script that checks for the presence of a specific HTTP header.

  1. Create a new file called http-header-check.nse.
  2. Add the head section with the necessary metadata:
description = [[
  Checks for the presence of a specific HTTP header.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"discovery"}
  1. Define the rule section to specify when the script should run:
portrule = function(host, port)
  return port.protocol == "tcp" and port.service == "http"
end
  1. Write the action section to implement the script’s functionality:
local http = require "http"

action = function(host, port)
  local response = http.get(host, port)
  if response.header["X-Special-Header"] then
    return "X-Special-Header is present"
  else
    return "X-Special-Header is not present"
  end
end



Running Your NSE Script

To run your newly created NSE script, use the following command:

nmap --script http-header-check -p 80 <target>

Replace <target> with the IP address or hostname of the target system. Nmap will execute the script and display the results.



Advanced NSE Script Development

Using Libraries and Modules

NSE provides several built-in libraries and modules to help you develop more complex scripts. Some commonly used libraries include:

  1. stdnse: Standard NSE library with utility functions.
  2. nmap: Provides access to Nmap-specific functions and data.
  3. http: Used for making HTTP requests and handling responses.
  4. shortport: Contains functions for matching specific ports and services.

Example: Vulnerability Scanning Script

Let’s create an NSE script that checks for a specific vulnerability in a web application.

  1. Create a new file called http-vuln-check.nse.
  2. Add the head section with the necessary metadata:
description = [[
  Checks for a specific vulnerability in a web application.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"vuln"}
  1. Define the rule section to specify when the script should run:
portrule = function(host, port)
  return port.protocol == "tcp" and port.service == "http"
end
  1. Write the action section to implement the script’s functionality:
local http = require "http"

action = function(host, port)
  local response = http.get(host, port, "/vulnerable-endpoint")
  if response.status == 200 and response.body:find("vulnerable") then
    return "Vulnerability detected: specific vulnerability description."
  else
    return "No vulnerability detected."
  end
end



Debugging and Testing NSE Scripts

Debugging and testing are crucial steps in NSE script development. Here are some tips to help you debug and test your scripts effectively:

  1. Use Print Statements: Add print() statements to your script to output debugging information.
  2. Enable Debugging Mode: Run Nmap with the -d flag to enable debugging output.
  3. Test on Multiple Targets: Test your script on various targets to ensure it works in different environments.



Best Practices for NSE Script Development

  1. Follow Lua Coding Conventions: Write clean, readable, and maintainable code by following Lua coding conventions.
  2. Handle Errors Gracefully: Use error handling to manage unexpected situations and avoid script crashes.
  3. Optimize Performance: Minimize network requests and processing time to improve script performance.
  4. Document Your Code: Provide clear and concise comments and documentation for your script.



Practical Examples of NSE Scripts

Example 1: Banner Grabbing Script

Banner grabbing is a technique used to gather information about a service running on a target system. Let’s create an NSE script to perform banner grabbing.

  1. Create a new file called banner-grab.nse.
  2. Add the head section with the necessary metadata:
description = [[
  Performs banner grabbing on a target service.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"discovery"}
  1. Define the rule section to specify when the script should run:
portrule = function(host, port)
  return port.state == "open"
end
  1. Write the action section to implement the script’s functionality:
local socket = require "nmap.socket"

action = function(host, port)
  local sock = socket:new()
  local status, err = sock:connect(host.ip, port.number)
  if not status then
    return "Failed to connect: " .. err
  end

  sock:send("HEAD / HTTP/1.0\r\n\r\n")
  local response = sock:receive_lines(1)
  sock:close()

  return response
end



Example 2: DNS Enumeration Script

DNS enumeration involves gathering information about DNS records associated with a domain. Let’s create an NSE script to perform DNS enumeration.

  1. Create a new file called dns-enum.nse.
  2. Add the head section with the necessary metadata:
description = [[
  Performs DNS enumeration on a target domain.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"discovery"}
  1. Define the rule section to specify when the script should run:
hostrule = function(host)
  return true
end
  1. Write the action section to implement the script’s functionality:
local dns = require "dns"

action = function(host)
  local domain = host.targetname
  local records = dns.query(domain, {qtype = "ANY"})
  local results = {}

  for _, record in ipairs(records) do
    table.insert(results, record.qtype .. ": " .. record.rdata)
  end

  return table.concat(results, "\n")
end



Example 3: FTP Anonymous Login Check Script

Checking for anonymous login access to FTP servers is a common security task. Let’s create an NSE script to perform this check.

  1. Create a new file called ftp-anon-check.nse.
  2. Add the head section with the necessary metadata:
description = [[
  Checks for anonymous login access to FTP servers.
]]

author = "Your Name <your.email@example.com>"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"auth"}
  1. Define the rule section to specify when the script should run:
portrule = function(host, port)
  return port.protocol == "tcp" and port.service == "ftp"
end
  1. Write the action section to implement the script’s functionality:
local ftp = require "ftp"

action = function(host, port)
  local status, err = ftp.open(host, port)
  if not status then
    return "Failed to connect: " .. err
  end

  local status, err = ftp.login("anonymous", "guest")
  if status then
    ftp.quit()
    return "Anonymous login allowed."
  else
    return "Anonymous login not allowed."
  end
end



Conclusion

Nmap’s Scripting Engine (NSE) is a powerful tool that extends Nmap’s capabilities beyond basic port scanning. By learning to write NSE scripts, you can automate various network tasks, perform advanced vulnerability scans, and gather detailed information about your network.