Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Nmap Scripting Engine

Introduction to the Nmap Scripting Engine

Learn what the Nmap Scripting Engine is, how scripts are written in Lua, how portrule and action work, and how to run your first safe scripts.

Port scanning, version detection and OS detection all answer fixed questions. But real work needs more flexible questions: "Which of these web servers shows a default page?", "Which hosts offer anonymous FTP?", "Is this TLS certificate about to expire?" The Nmap Scripting Engine (NSE) lets Nmap run small programs, called scripts, against the hosts and ports it has found. NSE is built into every Nmap installation and ships with hundreds of ready-made scripts.

Scripts are written in Lua, a small and fast scripting language. You do not need to know Lua to use scripts, and the next lessons show how to choose and run them. At the end of this chapter you will read and even write a simple script. As elsewhere, only use scripts on systems you are authorised to test.

Nmap and Lua cannot run on this website. Commands and Lua code are shown read-only. The runnable blocks are small Python stand-ins that model how NSE decides which scripts run and what they report.

Where scripts live

NSE scripts are files with the extension .nse. They sit in the scripts folder of the Nmap data directory, for example /usr/share/nmap/scripts on Linux or C:\Program Files (x86)\Nmap\scripts on Windows. A file named script.db indexes them by category. Libraries (for HTTP, SSH, TLS and so on) live in a nselib folder next to it.

You can list what exists with a shell command (read-only):

Terminal
ls /usr/share/nmap/scripts | head
nmap --script-help http-title    # print the documentation of one script

Running scripts

Three options choose scripts:

Option Meaning
-sC Run the default category (safe, useful, not intrusive)
--script <name|category|file|expression> Run chosen scripts
--script-help <name> Show help without running anything
Terminal
# Example commands (read-only)
nmap -sC -p 80 192.0.2.10                       # default scripts
nmap --script http-title -p 80,8080 192.0.2.10  # one named script
nmap --script "http-*" -p 80 192.0.2.10         # wildcard on names

Example output (illustrative):

TEXT
PORT   STATE SERVICE
80/tcp open  http
|_http-title: Lab status page

The |_ prefix marks the last (or only) line of a script's output. A script with several lines uses | for each line and |_ for the final one.

Anatomy of a script

Every script has a description block with metadata, then rules that decide when it runs and an action that does the work. Here is a complete, tiny script in Lua (read-only; it shows structure, not an attack):

LUA
description = [[
Reports the HTTP Server header of a web port.
]]

author = "Lab author"
license = "Same as Nmap--See https://nmap.org/book/man-legal.html"
categories = {"default", "safe"}

local shortport = require "shortport"
local http = require "http"

portrule = shortport.http

action = function(host, port)
  local response = http.get(host, port, "/")
  if response and response.header and response.header["server"] then
    return "Server: " .. response.header["server"]
  end
end

The parts:

  • categories lists the groups the script belongs to, such as safe, default, discovery, intrusive.
  • portrule is a function (here a ready-made one, shortport.http) that returns true for ports where the script makes sense. Other kinds exist: hostrule runs once per host, prerule before scanning and postrule after.
  • action runs when the rule is true. Its return value becomes the output you see after the |_.
  • require imports a library from nselib. Most of the work is done by libraries.
flowchart TD
    A["Nmap finds hosts and open ports"] --> B["For each selected script"]
    B --> C{"Rule true for this host or port?"}
    C -->|no| D["Skip"]
    C -->|yes| E["Run action(host, port)"]
    E --> F["Return value printed as script output"]

NSE evaluates rules first and runs the action only where the rule matches.

A rule/action engine in Python

The stand-in below mimics this design with plain Python functions. Scripts are objects with a rule and an action; the engine applies them to a pretend scan result.

Python Stand-in: a tiny NSE-like engine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Choosing a category changed which scripts ran, and the rules limited each script to the ports where it makes sense. That is exactly the NSE model.

Script phases

Scripts run at different moments during a scan:

  1. Pre-scan (prerule): before any host is scanned, for example to resolve targets from a database.
  2. Per-host (hostrule): once for each host after discovery.
  3. Per-port (portrule): for each open port after service detection. These are the most common.
  4. Post-scan (postrule): after everything, for example to summarise results.

Because per-port scripts use the results of version detection, --script automatically turns on -sV information where needed. A script can also be written to run only on ports whose service name matches, which is why detection quality affects which scripts fire.

Safety first

Scripts are programs. Some are harmless (http-title), some send heavy traffic (brute scripts guess passwords) and a few can disrupt a service (dos category). The next lesson covers categories in detail. Two rules help:

  • Read the description with --script-help before you run an unfamiliar script.
  • Prefer categories safe and default for routine checks, and keep intrusive scripts for lab systems or written authorisation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In which language are NSE scripts written?

    NSE embeds a Lua interpreter. Scripts are .nse files written in Lua and use libraries from nselib.
  2. 2. What does a portrule decide?

    A portrule returns true or false for a host/port pair. The action only runs where it is true.
  3. 3. What does the '|_' prefix in output mean?

    Script output lines start with '|', and the final line starts with '|_'.
  4. 4. Which option shows the documentation of a script without running it?

    --script-help prints the description, categories and arguments of the named scripts.

Summary

  • NSE runs Lua scripts from .nse files against hosts and ports found by the scan.
  • A script has metadata, a rule (portrule, hostrule, prerule, postrule) and an action.
  • -sC runs the default category; --script selects scripts by name, category, wildcard or expression.
  • Read a script's help before running it, and prefer safe categories.

Next: Script Categories and Arguments