How to read an NSE script before you run it: --script-help, arguments, and source

Where scripts live

Scripts are plain Lua files, typically in /usr/share/nmap/scripts on Linux or the Nmap install folder on Windows. script.db indexes them by category. Listing that directory and grepping for a protocol name is the fastest way to discover what exists, for example ls /usr/share/nmap/scripts | grep -i ldap.

Because scripts are source code, you can read exactly what one does before you run it. That is a habit worth building, especially for anything outside the safe category.

--script-help and the header

nmap --script-help ssl-cert prints the description, categories, and a link to the documentation page. Each script file also begins with a description block, an @usage example, an @output sample, and @args lines for every argument it reads. Read the @args before you assume a script’s defaults suit your network.

If a script you need is missing, update the database with nmap --script-updatedb after adding a file, and only add scripts from sources you trust.

Snippet

nmap --script-help ssl-cert
sed -n 1,60p /usr/share/nmap/scripts/http-title.nse

Lab: pass arguments and trace one script

Run http-title against a lab web server on a non-root path by passing an argument, then add --script-trace to see the raw request and response. The trace makes clear that the script sent one ordinary GET request. Repeat with http-headers to compare.

Arguments can also go in a file with --script-args-file, which keeps long settings like user agents and paths out of your shell history and documents them alongside the scan.

Snippet

sudo nmap -p 8080 --script http-title --script-args http-title.url=/status 192.168.56.101
sudo nmap -p 8080 --script http-headers --script-trace 192.168.56.101 2>&1 | head -60

When a script prints nothing

Scripts only run when their rule matches, usually a port and a recognized service. If -sV did not identify HTTP on a custom port, an http script may silently skip it. Add -sV, or force it with --script +http-title, where the plus sign runs it regardless of the rule.

Use -d for debug output when a script fails. The error usually points to a missing argument, a TLS problem, or a timeout.

Diagram

Reading a script before you trust it

Find
List the scripts directory and grep for the protocol.
Command
```
ls /usr/share/nmap/scripts | grep -i smb
```
Read
Check description, categories, and @args with --script-help.
Run
Pass arguments explicitly and save output.
Trace
Use --script-trace on the lab to see exactly what was sent.

Check yourself

1. Where are NSE scripts usually stored on Linux?

2. Which option shows the raw data a script sends and receives?

3. An http script prints nothing for a web app on port 9999. Most likely cause?