The Nmap Scripting Engine and its use cases

What NSE is

The Nmap Scripting Engine is a Lua interpreter embedded in Nmap. It lets you write small scripts that run during a scan and reuse everything Nmap already provides: fast parallel I/O, target and port lists, service detection results, timing controls and output formats.

Nmap ships with hundreds of scripts and a large library of reusable Lua modules (the nselib). You can use them as they are, copy and adapt them, or write your own.

Use cases

That last row is the reason to learn to write scripts. Off-the-shelf scripts cover public software. Your organisation’s own protocols, appliances and policies are only covered if you cover them.

Script categories

Every script declares one or more categories. They’re how you select scripts by intent and how you keep a scan safe.

Choosing categories honestly matters. Anyone running --script safe is trusting yours.

Running scripts

nmap -sC 10.0.0.5                              # default category
nmap --script vuln 10.0.0.5                    # a whole category
nmap --script http-title,ssl-cert 10.0.0.5     # by name
nmap --script "http-*" -p 80,443 10.0.0.5      # wildcard
nmap --script "default and safe" 10.0.0.5      # boolean expression
nmap --script "not intrusive" 10.0.0.5
nmap --script ./my-script.nse 10.0.0.5         # a file path
nmap --script-args 'http.useragent=MyScanner' --script http-title 10.0.0.5

Useful companions:

The four script types

A script’s rule decides when it runs. There are four types:

Most scripts you’ll write use a portrule: “if this port looks like a web server, run my code.”

How NSE executes scripts

Two properties shape how you write scripts:

• Scripts run in parallel, cooperatively. Each script instance (one per host or port) runs in its own Lua coroutine. When a script waits on the network, NSE switches to another one. That’s why scanning thousands of ports with scripts is fast.
• There is no pre-emption. A script that spins in a long CPU-bound loop blocks every other script. Keep loops small and let network calls do the waiting. (More in lesson 10.)

Where scripts live

The libraries sit beside it in nselib/. Reading them is the fastest way to learn what’s available.

To use your own script by name, put it in a scripts/ directory Nmap searches (for example ~/.nmap/scripts/, or anywhere via --datadir) and run nmap --script-updatedb so it lands in script.db. Passing an explicit path (--script ./my-script.nse) always works and is what we’ll use in the labs.

Lab: read a real script

1. The description, author, license and categories fields at the top.
2. The @usage, @args and @output documentation comments.
3. The portrule line. Which shortport predicate does it use?
4. The action function. What does it return when there’s no title?

Then run it against the lab server from lesson 1:

nmap -p 8000 --script http-title 127.0.0.1
nmap -p 8000 --script-help http-title
nmap -p 8000 --script http-title -d 127.0.0.1 2>&1 | grep -i "NSE"

Checkpoint