How to Master the Power of the Nmap Scripting Engine

nmap scripting engine featured image

You have heard of the powerful open-source network scanning tool Nmap, but have you heard of the even more powerful Nmap Scripting Engine?

The Nmap Scripting Engine (NSE) is a game-changing feature of Nmap that allows you to automate your network scanning and exploitation tasks. It can save you from tedious manual scans and sifting through vulnerability reports. It can elevate your hacking skills to the next level through scripting, allow you to extend the capabilities of Nmap, and fully customize this already powerful tool.

The NSE is trusted by thousands of penetration testers and red teamers who create scripts daily. These experts rely on this game-changing feature during real-world engagements; now you can too.

Let’s learn everything we need to become masters of the Nmap Scripting Engine today!

What Is the Nmap Scripting Engine?

The Nmap Scripting Engine (NSE) is a powerful feature of Nmap that allows you to automate network scanning tasks using scripts. These scripts allow you to extend and customize the basic features offered by the Nmap network scanning tool to leverage the tool’s powerful scanning capabilities to your needs.

If you are unfamiliar with Nmap, look at How to Scan Vulnerabilities With Nmap: A Comprehensive Guide. It covers everything you need to know about this powerful network scanning tool.

The NSE uses the Lua programming language to interact with Nmap. This is a lightweight yet powerful language that is commonly used for scripting. It is used by applications like the Wireshark network protocol analyzer, the Neovim text editor, and the Nginx web server to provide customization and extended functionality.

Nmap comes with various scripts you can use without creating your own. These scripts are organized into four distinct types based on the kind of targets they take and the scanning phase in which they are run.

Prerule scripts

These scripts run before any of Nmap's scan phases have been completed. At this stage, Nmap has yet to collect any information about its targets. As such, these scripts are useful for tasks that don't depend on specific scan targets, such as performing network broadcast requests to query DHCP and DNS servers. This can generate new targets for Nmap to scan.

Host scripts

Scripts in this phase run during Nmap's normal scanning process after Nmap has performed host discovery, port scanning, version detection, and OS detection against the target machine. This type of script is invoked once against each target machine that matches the script’s predefined targeting requirements.

Service scripts

This type includes scripts that run against specific services listening on a target system. It is the most common Nmap script type. These scripts may run more than once. For instance, if Nmap discovers web servers running on multiple ports on a machine, these scripts may run multiple times (once for each port).

Postrule scripts

These scripts run after Nmap has scanned all of its targets and are commonly used to format and present Nmap’s output. They contain postrule functions that ensure Nmap’s output is consistent and appropriate. For example, the ssh-hostkey script is a postrule script that’s postrule function checks for duplicate keys amongst all of the hosts scanned and then prints any that are found.

Many Nmap scripts can be run as either a prerule or postrule script. If a script you create can be used as either, the Nmap team recommends using a prerule for consistency.

Nmap Command Generator

Say goodbye to the hassle of trying to remember the exact syntax for your Nmap commands! With our Nmap Command Generator, you can simply say what you need Nmap to do, and we will generate the command for you.

How Are Nmap Scripts Categorized?

Aside from separating scripts based on their type, the NSE also organizes scripts into categories based on their functionality. Each category contains dozens of scripts, and Nmap allows you to execute all the scripts in one or more categories simultaneously. This is very useful when you must comprehensively test your target system.

There are currently 14 categories which an NSE script can fall under, as defined by the official Nmap documentation:

  • Auth - These scripts deal with providing or bypassing authentication credentials on the target system.
  • Broadcast - Scripts in this category discover hosts not listed on the command line by broadcasting on the local network. You can use the newtargets script argument to allow these scripts to automatically add newly discovered hosts to the Nmap scanning queue.
  • Brute - These scripts use brute force attacks to guess the authentication credentials of a remote server.
  • Default - This is the default set of scripts run when you use the -sC or -A Nmap options on the command line. The Nmap team categorizes these scripts based on speed, usefulness, verbosity, reliability, intrusiveness, and privacy.
  • Discovery - These scripts try to actively discover more about the network by querying public registries, SNMP-enabled devices, directory services, and similar sources.
  • DoS - Scripts in this category may cause a Denial of Service (DoS) and can crash vulnerable services. This is usually an undesired side effect of testing for a traditional vulnerability.
  • Exploit - These scripts aim to actively exploit a known vulnerability.
  • External - Scripts in this category may send data to a third-party database or network resource. These third-party databases may record anything you send them (e.g., IP addresses). Most Nmap scripts only involve network traffic between your computer and the target computer. If this is not the case, they are placed in this category.
  • Fuzzer - This category contains scripts designed to send server software unexpected or randomized fields in each packet to discover unknown bugs and vulnerabilities in software. This can be a slow process and bandwidth-intensive.
  • Intrusive - These scripts have a high risk of crashing the target system, using up significant resources on the target machine (e.g., bandwidth or CPU time), or otherwise being perceived malicious by the target's system administrators.
  • Malware - These scripts test whether the target platform is infected by malware or backdoors.
  • Safe - These scripts weren't designed to crash services, use large amounts of network bandwidth or other resources, or exploit security holes. Most of these scripts perform general network discovery and are unlikely to cause adverse side effects.
  • Version - The scripts in this special category are an extension to the Nmap’s version detection feature and cannot be selected explicitly. They are selected to run only if version detection (-sV) is specified on the command line.
  • Vuln - These scripts check for specific known vulnerabilities and generally only report results if they are found.

How Do I Use Nmap Scripts?

Now that you have a basic understanding of what the NSE is and the types of scripts you can run let’s look at how to actually run an Nmap script.

Nmap scripts can be executed using the --script command line option followed by the name of the script you want to execute or the name of the entire category of scripts you want to execute. Nmap will then load the script and execute it (or them) against the target you define. Let’s see this in action.

Before executing any scripts in Nmap, it is good practice to update the script database with the command nmap --script-updatedb. This will load any updates Nmap has made to its scripts and any new ones you have added.

Executing a Specific Nmap Script

To execute a specific Nmap script against a target machine, you can run the following command:

nmap --script <script_name> <target>

If you wanted to run the http-title script against a machine whose IP address is 10.0.200.10, you would run the command:

nmap --script http-title.nse 10.0.200.10

Executing a Single Nmap Script

Here the script returned the title of the default web page running on machine 10.0.200.10. It appears to be an Elastic web GUI.

The NSE extension .nse is optional. You could run nmap --script http-title 10.0.200.10. However, when executing single Nmap scripts, it is best practice to include this extension to explicitly define that you are running a single script, not an entire category of scripts. This is particularly useful when running custom Nmap scripts (e.g., nmap --script /home/user/custom-script.nse 10.0.200.10).

Executing Nmap Scripts With Arguments  

Some scripts require you to specify arguments so they can execute correctly. This can be done with the argument --script-args followed by a list of arguments you want to pass to the script or with --scripts-args-file followed by a file containing the arguments you want to pass.

To specify script arguments for the ssh-brute Nmap script and run it against 10.0.200.10, you can execute the following command nmap --script ssh-brute --script-args userdb=users.txt,passdb=passwords.txt 10.0.200.10

Executing an Nmap Script with Arguments

Here the argument userdb contains a list of usernames (specified in the users.txt file), and passdb contains a list of passwords (specified in the passwords.txt file). From the output, you can see that the script was able to successfully brute force SSH login with the credentials elastic:elastic.

To specify these arguments in a file and pass this on the command line, run the command:

nmap --script ssh-brute --script-args-file /home/attacker/script-args.txt

Executing an Nmap Script with Arguments Passed as a File

If you are unsure if a Nmap script requires command line arguments, you can run nmap --script-help=<script_name> to show help about the script. This will include a brief description, the script’s categories, and the arguments you can pass.

You can also use this command line option to search for scripts when you combine it with a wildcard. To search for all scripts that start with http run the command nmap --script-help=http*. If you run the command nmap --script-help=*, you will see information about every script you can run with Nmap.

Executing a Nmap Script Category

Instead of executing a single script, the NSE also allows you to execute an entire category of scripts against a target machine. To do this, run the following command:

nmap --script <category_name> <target>

If you wanted to run all the scripts that fall under the vuln category against a machine whose IP address is 10.0.200.3, you would run the command:

nmap --script vuln 10.0.200.3

Executing a Category of Nmap Scripts

Here the script returned several results for common vulnerabilities it scanned for. Unfortunately, the target machine was not vulnerable to these vulnerabilities.

Typically, Nmap scripts only return results if a target machine is potentially vulnerable or an error occurs. For instance, if you execute the same set of scripts against the web server from our previous example (10.0.200.10), a different set of results are returned.

Executing a Category of Nmap Scripts Against a Linux Machine

Instead of using script categories to run multiple scripts simultaneously against a target machine, you can use wildcards. For instance, running the command nmap --script http* 10.0.200.10 will run every Nmap script that begins with http against the machine 10.0.200.10.

Executing All Nmap Scripts

There is a third way to execute scripts. If you specify the command line option -sC, Nmap will run all its default scripts against a target machine. This is the same as running the command nmap --script default <target>, only shorter.

The default Nmap scripts are the ones the team considers the most optimal to run based on multiple factors. If you wanted to run all of Nmap’s scripts against machine 10.0.200.3, you would execute the command:

nmap –sC 10.0.200.3

Executing a Nmap's Default Scripts

Here you can see significantly more output for machine 10.0.200.3 than when you ran the scripts in the vuln category.

If you want to see all the scripts that Nmap runs against a target machine, use the -v command line option. This tells Nmap to provide verbose output, including the number of scripts loaded to run, the time it took to run, and why certain scripts failed.

How Do I Add Nmap Scripts?

As shown above, you can run a custom Nmap script with the command nmap --script </path/to/custom-script.nse> <target>. However, if you want to make a Nmap script part of your hacking toolkit, you will want to add it to the NSE database so that you don’t have to specify the path to your script every time.

To do this, you need to find the Nmap installation directory on your machine:

  • For Linux systems, this is usually /usr/share/nmap/scripts/. This is where you can find it on Kali Linux.
  • For Windows systems, this is usually C:\Program Files (x86)\Nmap\scripts\.

Then you can download or create your custom Nmap script and copy it to this directory.

Copying a Custom Nmap Script to the Default Nmap Directory

To run your custom Nmap script, you must update the NSE database with the command nmap --script-updatedb. Then you can run the script like any other Nmap script.

Updating the NSE Database and Executing a Custom Nmap Script

To execute most of these commands Kali Linux, you must become a Sudo user.

Where Can I Get Additional Nmap Scripts?

You can create your own or import community-contributed scripts to add more Nmap scripts to the default ones that come pre-installed with Nmap. A large selection of community-contributed scripts is available on GitHub, which are freely available and ready for use.

These scripts range from full network reconnaissance frameworks to scripts that can exploit the latest vulnerabilities. It is the ideal place to learn what Nmap scripts can do and how other script authors have achieved this functionality.

To use a community script, you need to perform the following:

  1. Find a community-contributed Nmap script online.
  2. Download the script to your local machine.
  3. Either run the script from the command line with nmap --script </path/to/your/script.nse> or add it to the NSE database.

StationX has no connection to these community-contributed scripts, our team has not tested them, and we do not officially endorse them. We recommend you take care when using these scripts and understand what they do before using them. Always thoroughly testing any script you run before using it in a penetration test or red team exercise.

Conclusion

The Nmap Scripting Engine (NSE) is a game-changing feature of the powerful network scanning tool Nmap. It allows hackers to create and execute scripts that automate everything from scanning for vulnerabilities to exploitation.

The NSE is used by professional, ethical hackers and penetration testers worldwide to automate their hacking workflows. Now you have the skills to join them and create your own NSE scripts using the Lua programming language. You can also find community-contributed scripts online to add to your hacking toolkit.

Enjoy using this newfound knowledge and use it wisely!

If you struggle to remember any of the commands showcased in this article, use this Nmap Cheat Sheet 2023: All the Commands, Flags & Switches to quickly find the command you want to run.

Interested in learning other skills required to become a hacker or penetration tester? Take a look at these training courses:

Frequently Asked Questions

Level Up in Cyber Security: Join Our Membership Today!

vip cta image
vip cta details
  • Adam Goss

    Adam is a seasoned cyber security professional with extensive experience in cyber threat intelligence and threat hunting. He enjoys learning new tools and technologies, and holds numerous industry qualifications on both the red and blue sides. Adam aims to share the unique insights he has gained from his experiences through his blog articles. You can find Adam on LinkedIn or check out his other projects on LinkTree.

>