Nmap Security Scanner
*Ref Guide
Security Lists
Security Tools
Site News
Advertising
About/Contact
Credits
Sponsors





Intro Reference Guide Book Install Guide
Download Changelog Zenmap GUI Docs
Bug Reports OS Detection Propaganda Related Projects
In the Movies In the News
Chapter 9. Nmap Scripting Engine
Prev   Next

Chapter 9. Nmap Scripting Engine

Table of Contents

Introduction
Usage and Examples
Script Categories
Arguments to Scripts
Command-line Arguments
Usage Examples
Script Format
id Field
description Field
author Field
license Field
runlevel Field
Port and Host Rules
Action
Script Language
Lua Base Language
Lua Extensions
Bitwise Logical Operations
Perl Compatible Regular Expressions
IP Operations
Short Portrules
Functional Programming Style List Operations
String Buffer Operations
URL Manipulation Functions
Buffered Network I/O Helper Functions
HTTP Functions
Data File Parsing Functions
Various Utility Functions
Nmap API
Information Passed to a Script
Target Information Retrieving by a Script
Various Utility Functions for Raw Packet Support
Network I/O API
Connect-style network I/O
Raw packet network I/O
Exception Handling
The Registry
Script Writing Tutorial
The Head
The Rule
The Mechanism
Version Detection using NSE
Example Scripts
Finger-Test Script
Service Owner Lookup via Identd
Implementation
Initialization Phase
Matching of Scripts to Targets
Running Scripts
Adding C Modules to Nselib
NSE Script License and Community Contributions

Introduction

The Nmap Scripting Engine (NSE) is one of Nmap's most powerful and flexible features. It allows users to write (and share) simple scripts to automate a wide variety of networking tasks. Those scripts are then executed in parallel with the speed and efficiency you expect from Nmap. Users can rely on the growing and diverse set of scripts distributed with Nmap, or write their own to meet custom needs.

The Nmap project would like to thank Diman Todorov for his excellent work building the initial NSE implementation and writing much of this documentation. Stoiko Ivanov also contributed greatly. The tasks we had in mind when creating the system are:

Network discovery

This is Nmap's bread and butter. Examples include looking up whois data based on the target domain, querying ARIN, RIPE, or APNIC for the target IP to determine ownership, performing identd lookups on open ports, SNMP queries, and listing available NFS/SMB/RPC shares and services.

More sophisticated version detection

The Nmap version detection system (Chapter 7, Service and Application Version Detection) is able to recognize thousands of different services through its probe and regular expression based matching system, but it cannot recognize everything. For example, identifying the Skype v2 service requires two independent probes. Nmap could also recognize more SNMP services if it tried a few hundred different community names by brute force. Neither of these tasks are well suited to traditional Nmap version detection, but both are easily accomplished with NSE. For these reasons, version detection now calls NSE by default to handle some tricky services. This is described in the section called “Version Detection using NSE”

Vulnerability detection

When a new vulnerability is discovered, you often want to scan your networks quickly to identify vulnerable systems before the bad guys do. While Nmap isn't a comprehensive vulnerability scanner, we plan to distribute scripts for some very severe or common vulnerabilities and misconfigurations.

Backdoor detection

Many attackers and some automated worms leave backdoors to enable later reentry. Some of these can be detected by Nmap's regular expression based version detection. For example, within hours of the MyDoom worm hitting the Internet, Jay Moran posted an Nmap version detection probe and signature so that others could quickly scan their networks. For more complex worms and backdoors, NSE is needed instead.

Vulnerability exploitation

As a general scripting language, NSE could even be used to exploit vulnerabilities rather than just find them. The capability to add custom exploit scripts may be valuable for some people (particularly penetration testers), though we aren't planning to turn Nmap into an exploitation framework like Metasploit

The listed items are just the initial script classes. It is likely that Nmap users will come up with even more inventive uses for NSE.

Scripts are written in the embedded Lua programming language The language itself is well documented in the books Programming in Lua, Second Edition and Lua 5.1 Reference Manual. The reference manual is also freely available online, as is the first edition of Programming in Lua Given the availability of these excellent general Lua programming references, this document only covers aspects and extensions specific to the Nmap implementation.

NSE is activated with the -sC option (or --script if you wish to specify a custom set of scripts) and results are integrated into Nmap normal and XML output. Two types of scripts are supported: service and host scripts. Service scripts relate to a certain open port (service) on the target host, and any results they produce are included next to that port in the Nmap output port table. Host scripts, on the other hand, run no more than once against each target IP and produce results below the port table. Example 9.1, “Typical NSE Output” shows a typical script scan. Examples of service scripts producing output are Stealth SSH Version, which tricks some SSH servers into divulging version information without logging the attempt as they normally would, Service Owner, which connects to open ports, then performs a reverse-identd query to determine what username it is running under, and HTML Title, which simply grabs the title of the root path of any web servers found. A sample host script is RIPE Query, which looks up and reports target IP ownership information.

Example 9.1. Typical NSE Output

$ ./nmap -sC localhost -p 22,23,80,113

Starting Nmap 4.20ALPHA9-NSE ( http://insecure.org )
Interesting ports on localhost (127.0.0.1):
PORT    STATE  SERVICE
22/tcp  open   ssh
|_ Stealth SSH version: SSH-1.99-OpenSSH_4.2
|_ SSH protocol version 1: Server supports SSHv1
23/tcp  closed telnet
80/tcp  open   http
|_ HTML title:Test Page for Apache Installation
113/tcp closed auth

Host script results:
|_ RIPE Query: IP belongs to:          Internet Assigned Numbers Authority

Nmap finished: 1 IP address (1 host up) scanned in 0.907 seconds


Prev   Next
Dealing with Misidentified and Unidentified Hosts Home Usage and Examples
[ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]