Lead Image © Raman Maisei, 123RF.com

Lead Image © Raman Maisei, 123RF.com

Develop your own scripts for Nmap

The Scribe

Article from ADMIN 30/2015
Nmap does a great job with standard penetration testing tasks, but for specific security analyses, you will want to develop your own test scripts. The Nmap Scripting Engine makes this possible.

For years, Nmap [1] has been essential to system administrators. There are virtually no alternatives to the classic tool for penetration testing. Out of the box, this tool already gives you more than 100 standard scripts. However, Nmap offers more than just the ability to run predefined scripts.

The Nmap Scripting Engine (NSE) gives you what is potentially the most powerful and flexible feature of all: the ability to run your own scripts and thus automate various scanning and analysis tasks. The scripts are based on the Lua programming language [2], which is easy to learn and perfect for developing test scripts. Nmap executes these scripts in parallel at a high speed and with great efficiency.

Nmap's core functions are network, version, and vulnerability analysis. NSE takes scanning with Nmap to the next level. For example, you can use the scan engine to identify SQL injection vulnerabilities and potential brute force attack vectors. With the help of NSE, you can create your own test scripts and modify existing ones. To help you keep track, the developers have divided the scripts into various categories. You need to be familiar with these to be able to assign your scripts correctly via the header configuration. Based on the category name, you can see the field of application. Table 1 summarizes the various types.

Table 1

Script Categories

Category Description
auth These scripts handle authentication data and attempt to work around the authentication on the target system. Examples include x11-access, ftp-anon, and oracle-enum-users. The exceptions are scripts for brute force attacks.
broadcast Scripts in this category output broadcasts to identify any previously unidentified hosts on the local network. The newtargets argument automatically adds any newly discovered hosts to the scanning queue.
brute Scripts of this type execute brute force attacks to retrieve the target system's access credentials. Nmap has dozens of such scripts for various protocols, for example, http-brute, oracle-brute, and snmp-brute.
default These are standard scripts that are used if you run Nmap with the -sC or -A options.
discovery These scripts actively attempt to discover more about the network by, for example, querying public registers, SNMP-capable devices, directory services, etc. Examples include html-title, which captures the title of a website, or smb-enum-shares, which reads Windows shares.
dos Scripts from this category can cause denial of service attacks. The reason for this is typically testing for vulnerabilities. The service crashing is more of an undesirable side effect than the objective.
exploit These scripts target vulnerabilities.
external The scripts in this group send data to external databases and network services. For example, Nmap can query a whois server for more details about the target system.
fuzzer These scripts send unexpected or random fields in each packet transmitted to the target system. This technique can be used to identify unexpected or unknown vulnerabilities of the targets. An example of this is dns-fuzz, which confronts a DNS server with unknown requests until the server either crashes or blocks the connection.
intrusive These scripts cannot be assigned to the safe category because the risk of the target system crashing is fairly high. The reasons include the use of considerable resources or exploiting existing vulnerabilities. If you cannot assign your own scripts to a specific category, you should at least classify them as safe or intrusive .
malware These scripts are used to discover whether the target system is already infected with malware or backdoors. Examples include smtp-strangeport, which checks SMTP servers for intruders, and auth-spoof, which identifies identd spoofing daemons.
safe These scripts are considered to be safe and will not cause damage to the targets. However, they can use considerable network bandwidth or other resources. Examples include ssh-hostkey, which queries the SSH key, and html-title, which parses the title of a website.
version These script types are extensions of the version detection types, however, they cannot be selected explicitly. They only run if you enable version detection with the -sV option. Examples include skypev2-version, pptp-version, and iax2-version.
vuln The last script type tests for specific known vulnerabilities. However, reports are only output if vulnerabilities are actually found.

Variable Applications

Nmap's core functionality is and will always be scanning network components. The version identification system can distinguish between thousands of different services. To do this, the scanner relies on tests and a match system that also supports the use of regular expressions. Nmap reliably identifies SNMP services and discovers brute force vulnerabilities. Both options can be easily exploited with NSE and matching test scripts.

For administrators, identifying existing and new vulnerabilities in the IT infrastructure is an essential task. It is a matter of getting there before others do. Although Nmap is not a security scanner like Nessus or OpenVAS, thanks to the scripting engine, you can perform simple vulnerability tests. Currently, Nmap has several scripts for this, and the developers are planning to add more.

Nmap and NSE are also useful for detecting backdoors. Hackers and worms typically leave a backdoor after an attack to ensure easy access to the system on next contact. Nmap scripts can identify these – not all, but a large number. NSE can also be used to identify complex worms and backdoors.

With NSE as a general scripting environment, you can of course also exploit any vulnerabilities you identify. The ability to run exploit scripts is particularly useful for pen testing. However, the developers are not planning to convert Nmap into a full-fledged exploitation framework like Metasploit. That said, it is good to know that you could also use Nmap in combination with NSE for this job. To get started developing your own Nmap scripts, you first need to enable the engine. If you have Nmap in place, this is easily done: Just use the -sC option. The results of the script execution are integrated into Nmap.

Getting Started with NSE

NSE scripts use the file suffix NSE and reside in a default Nmap installation below the /usr/share/nmap/scripts/ directory. To execute a specific NSE script, use the following syntax:

nmap --script scriptname.nse targethost

If you want to run a script and state the path, use the following command to do so:

nmap --script /path/to/scriptScriptname.nse targethost

After creating your first scripts, you will probably not want to launch them publicly, but first test whether they actually perform the desired actions. Nmap provides a dedicated test server in the scanme.nmap.org domain for this purpose. Use the following command for your first evaluations:

nmap --script /path/userdefined NSE-script.nse scanme.nmap.org

When taking your first steps, it also makes sense to enable debugging. Use the -d, supplemented with a value between 1 and 9, to do so. The higher the debug value, the more verbose the output. For example:

nmap -sV --script exploit -d3 targethost

NSE scripts have a clear-cut structure. This becomes most clear when you take a look at an existing script. The scripts not only define the tests to perform but also the output. Nmap and NSE define four different script types, which are characterized by different execution rules:

  • prerule
  • postrule
  • portrule
  • hostrule

Prerule scripts are executed before the scan. They can be used, for example, to collect service information. Some of these script types also define new targets, which are then analyzed by follow-up scripts.

The targets-sniffer.nse script, for example, uses prerule to check whether Nmap is running in privileged mode and the scanner can correctly identify the network interface:

prerule = function()
return nmap.is_privileged() and
(stdnse.get_script_args("targets-sniffer.iface") or

Postrule scripts are executed after Nmap has scanned all the targets. It makes sense to use this for formatting and presenting Nmap output. One of the most popular Postrule scripts is ssh-hostkey. It opens a connection to an SSH server, then reads and outputs the public key. The rule is defined as follows:

postrule = function() return (nmap.registry.sshhostkey ~= nil) end

Service scripts contain the portrule function, which attempts to find out which services are running on the target host and with which ports. Nmap has more than 15 scripts for testing HTTP services on web servers. If a web server with various ports is running on a target, the script runs multiple times – once per port.

The fourth script type is the host script. This type is typically used after Nmap has run discovery, port, version, or operating system scans. The hostrule function is applied here. An example is whois, which identifies the owner of a target system, or path-mtu, which discovers the maximum IP packet size accepted by a host.

Scan Phases

The scanning actions that Nmap performs are broken down into various phases. You need to be familiar with these so you will know the order in which the scanner typically performs which actions and which steps you can omit if needed:

  • Phase one is pre-scanning. It only runs if you use the -sC or --script options. This is an attempt to use NSE scripts to discover more information about the target (Figure 1).
Figure 1: Initial Nmap run with the Nmap Scripting Engine enabled, targeting localhost.
  • In phase two, Nmap resolves the target's hostnames, to be able to continue working with the IP addresses.
  • In phase three, Nmap then discovers whether the target(s) are accessible. It uses various discovery techniques to do this. You can omit this phase using the -Pn option.
  • Phase four involves reverse DNS resolution. Nmap performs a reverse lookup here to discover the hostnames of the targets. You can enforce this phase with the -R option and skip it with -n.
  • Phase five is port scanning – the classic task. In this phase, Nmap discovers the status of the ports to analyze. You can also omit this phase by stipulating the -sn option.
  • Phase six is advanced version detection for the open ports found. This phase is only performed if you stipulate the -sV argument when running Nmap.
  • In phase seven, Nmap attempts to identify the operating system run on the target hosts. This test only occurs if you use the -O option.
  • Nmap scans can cycle through three more phases, with phase eight being the traceroute phase in which the port scanner determines the route to the hosts. This phase is enabled by the --traceroute option.
  • NSE scripts are finally used in phase nine. The output is generated here on the basis of the output configuration defined in the script. Nmap formats the acquired information and outputs it.
  • The tenth or final phase is known as post-scanning. Here the post-scans defined in the NSE script are executed. If no more tests are defined, this phase is omitted.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Protect Your Servers with Nmap

    If you've ever had to test the security of your servers, you've almost certainly come across the ever-flexible Nmap (Network Mapper) – used by sys admins to help protect their servers and diagnose problems.

  • Nmap 6.0 Released
  • BackTrack Linux: The Ultimate Hacker's Arsenal

    Penetration Testing and security auditing are now part of every system administrator's "other duties as assigned." BackTrack Linux is a custom distribution designed for security testing for all skill levels from novice to expert.

  • Managing Port Scan Results with Dr. Portscan

    Regularly scanning the ports on your own network prevents intruders from sneaking in, but if you have dozens or hundreds of servers, you’ll need professional help: Dr. Portscan to the rescue.

  • Security as Code
    Gauntlt is a sophisticated DevOps tool that can test the security of your continuous integration/continuous delivery pipeline.
comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=