Disclaimer

Scripts are not run in a sandbox and thus could accidentally or maliciously damage your system or invade your privacy. Never run scripts from third parties unless you trust the authors or have carefully audited the scripts yourself.

Only scan networks and hosts you have permission for. Many hosting providers do not allow the scanning of other networks, and doing it anyways could cause you trouble. Please be aware of it.

This blog post will cover the general usage of nmap scripts, not the scripting itself. Check out the getting started with nmap post if you are new to nmap.

Basics usage #

The Nmap Scripting Engine (NSE) allows you to run and share pre-made and custom scripts. Scripts are written in Lua and use the file extension .nse. NSE will enable you to scan and analyze any host and network in-depth and according to your needs. Automation, vulnerability scans, and many other functions are possible with the NSE.

A list of all, by default, included scripts can be found in their official docs.

I mainly use scripts to find, enumerate and check SMB shares and SSH servers, finding potential rogue DHCP servers (consumer routers ftw), and some specific vuln scans for like log4j and other recent attacks.

Run a nmap with a script:: nmap --script=SCRIPTNAME TARGETNETWORK/HOST; multiple syntaxes are allowed, as I’ll show in the next example
Example with different syntaxes:: nmap --script http-title scanme.nmap.org; nmap --script=http-title scanme.nmap.org; nmap --script 'http-title' scanme.nmap.org; nmap --script "http-title" scanme.nmap.org; nmap --script="http-title" scanme.nmap.org; and I bet there are more, and you even can see the file extension .nse right after

Output:

[...]
80/tcp    open     http
|_http-title: Go ahead and ScanMe!
[...]

Side note: Scanning the domain scanme.nmap.org is permitted in low volumes as stated on their page, but please do not abuse it!

Using multiple scripts #

There are various ways to use multiple scripts at once. The easiest way would be to separate them with a comma.

nmap -p 80 --script=http-title,http-headers scanme.nmap.org

Another way would be to use a whole directory with with --datadir argument, in which all scripts within the chosen directory would be running.

The last way is to pick a whole category of scripts. I’ll write about categories further down in this post.

Script help page

You can use --script-help to get additional information of a script.

nmap --script-help http-title.nse

Starting Nmap 7.80 ( https://nmap.org ) at 2023-04-07 16:23 CEST

http-title
Categories: default discovery safe
https://nmap.org/nsedoc/scripts/http-title.html
  Shows the title of the default page of a web server.

  The script will follow up to 5 HTTP redirects using the default rules in the
  http library.

Script arguments

Some scripts require arguments. You can find them with --script-help or on the official page of the script.

The official syntax is:: --script-args <n1>=<v1>,<n2>={<n3>=<v3>},<n4>={<v4>,<v5>}; and it often enough takes me 1-2 tries to get everything right, depending on the script.

If you have many arguments to run, you can call them from a file with --script-args-file FILENAME.

Script directory #

You usually can find the default scripts in the following directories.

Linux:: /usr/local/share/nmap/scripts or /usr/share/nmap/scripts or somewhere else, depending on the installing method.; or look for them via locate *.nse
Windows:: C:\Program Files\Nmap\scripts

You can choose a different directory with the --datadir argument.

nmap --datadir /some/random/path/to/scripts/ -sC -sV TARGETNETWORK

NSE will look for the script in the following places until found:: --datadir; $NMAPDIR; ~/.nmap (Linux); APPDATA>\nmap (Windows); directory containing the nmap executable + ../share/nmap in Linux; NMAPDATADIR; and the current directory

NSE data directory

More complex scripts require separate data sets, databases, and other things. Those must be placed in the NSE data directory. It works similarly to the script directory but is out of this post’s scope. Most scripts that require this function will let you know. I just thought it would be beneficial to mention.

Custom scripts #

It is straightforward to use and add custom scripts, that are either created by yourself or downloaded from the internet.

I want to point to the disclaimer at the top of the post: only run scripts that you trust!

Run a custom script in nmap:: nmap --script /path/to/script.nse TARGET

Using the absolute path of a script would be the easiest way to do so. If the script works and you plan to use it more often, you can add it you the script.db, which contains all scripts and let you call the script with the name only. This file is generally in the same directory as the already included scripts.

Add the .nse file to the script directory and run the following command to add the script to script.db:

sudo nmap --script-updatedb

You should now be able to run the script with the name only.

Script categories #

NSE categorizes its scripts, so you can run a bunch of them at once. The following categories are currently there:

auth, broadcast, default, discovery, dos, exploit, external, fuzzer, intrusive, malware, safe, version, and vuln

Most names are self-explanatory, and for more information, I’d like to refer you to the official docs.

You can run nmap with all default scripts with the following command:: nmap --script=default TARGET; nmap -sC TARGET # -sC is the short form and no other category has one to my knowledge

Like the scripts, you could run multiple categories. Simply separate them with a comma.

Scripts in a category

I bet there are easier ways to check what scripts are in a category, but I’d just check the script.db for the specific category:

grep -i 'default' script.db

Output

Entry { filename = "address-info.nse", categories = { "default", "safe", } }                                                     
Entry { filename = "afp-serverinfo.nse", categories = { "default", "discovery", "safe", } }                                      
Entry { filename = "ajp-auth.nse", categories = { "auth", "default", "safe", } }                                                 
Entry { filename = "ajp-methods.nse", categories = { "default", "safe", } }
Entry { filename = "amqp-info.nse", categories = { "default", "discovery", "safe", "version", } }
[...]