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
Usage and Examples
| Chapter 9. Nmap Scripting Engine |
## Usage and Examples While NSE has a complex implementation for efficiency, it is strikingly easy to use. Simply specify `-sC` to enable the most common scripts. Or specify the `--script` option to choose your own scripts to execute by providing categories, script file names, or the name of directories full of scripts you wish to execute. You can customize some scripts by providing arguments to them via the `--script-args` option. The two remaining options, `--script-trace` and `--script-updatedb`, are generally only used for script debugging and development. ### Script Categories NSE scripts define a list of categories they belong to. Currently defined categories are `safe`, `intrusive`, `malware`, `version`, `discovery` and `vulnerability`. By default, Nmap runs all scripts in either the `safe` or `intrusive` categories. Categories are not case sensitive. The following list describes each category. `safe` Scripts which weren't designed to crash services, use large amounts of network bandwidth or other resources, or exploit security holes. These are less likely to offend remote sysadmins. Of course (as with all other Nmap features) we cannot guarantee that they won't ever cause adverse reactions. Most of these perform general network discovery. Examples are echoTest (sends a string to the UDP echo service) and showHTMLTitle (grabs the title from a web page). `intrusive` These are not intended to crash or damage anything, but are more likely to leave suspicious logs or otherwise arouse sysadmin ire. Scripts which attempt to login to services with default passwords fall into this class. `malware` These scripts test if the target platform is infected by malware or backdoors. `version` This category cannot be selected explicitly. It is only run if `-sV` was supplied. The scripts in this category are an extension to the version detection service. Their output cannot be distinguished from version detection output and they do not produce script scanning output. `discovery` These scripts try to actively learn more about the network by querying public registries, SNMP-enabled devices, directory services, and the like. `vulnerability` These scripts check for a specific vulnerability and report results only if it is found. ### Arguments to Scripts You can pass arguments to NSE scripts via the `--script-args` option. The script-arguments generally are name-value pairs, which are provided to the script as a Lua table called `args` inside the `nmap.registry` with the names as keys for the corresponding values. The values can either be strings or tables. Subtables can be used to pass arguments to scripts with a finer granularity (e.g. pass different usernames for different scripts). A typical nmap invocation with script arguments may look like: `$ nmap -sC --script-args user=foo,pass=bar,anonFTP={pass=ftp@foobar.com}` which would result in the Lua table:
    {user="foo",pass="bar",anonFTP={pass=nobody@foobar.com}}
You could therefore access the username (`"foo"`) inside your script as `local username= nmap.registry.args.user` . As a general rule the subtables used to override options for scripts should be named as the script's `id`, since otherwise scripts can't know where to search for their arguments. ### Command-line Arguments These are the five command line arguments specific to script-scanning: `-sC` Performs a script scan using the default set of scripts. It is equivalent to `--script=safe,intrusive`. `--script <script-categories|directory|filename|all>` Runs a script scan (like `-sC`) with the scripts you have chosen rather than the defaults. Arguments can be script categories, single scripts or directories with scripts which are to be run against the target hosts instead of the default set. Nmap will try to interpret the arguments at first as categories and afterwards as files or directories. Absolute paths are used as is, relative paths are searched in the following places until found: `--datadir/`; `$(NMAPDIR)/`; `~user/nmap/` (not searched on Windows); `NMAPDATADIR/` or `./`. A `scripts/` subdirectory is also tried in each of these. Give the argument `all` to execute all scripts in the Nmap script database. If a directory is specified and found, Nmap loads all NSE scripts (any filenames ending with `.nse`) from that directory. They must have the filename extension `nse`. Nmap does not recurse into subdirectories to find scripts. When individual file names are specified, the file extension does not have to be `nse`. Nmap scripts are stored in a `scripts` subdirectory of the Nmap data directory (see the `--datadir` option) by default. Scripts are indexed in a database stored in `scripts/script.db`. The database lists all of the scripts in each category. A single script may be in several categories. `--script-args` provides arguments to the scripts. See the section called “Arguments to Scripts” for a detailed explanation. `--script-trace` This option is similar to `--packet-trace`, but works at the application level rather than packet by packet. If this option is specified, all incoming and outgoing communication performed by scripts is printed. The displayed information includes the communication protocol, source and target addresses, and the transmitted data. If more than 5% of transmitted data is unprintable, hex dumps are given instead. `--script-updatedb` This option is only useful if you have added or removed NSE scripts from the default `scripts` directory, or if you have changed any of the scripts' `categories` fields. This field contains categories such as `safe` and `discovery` which the script belongs to. Categories may be specified with the `--script` option. For efficiency reasons, NSE generates a `script.db` file which maps categories to the scripts they contain. If you changed tag directives or added/removed scripts, run nmap --script-updatedb. Some of the Nmap options have effects on script scans. The most prominent of these is `-sV`. A version scan executes the scripts in the `version` category. The scripts in this category are slightly different than other scripts. Their output blends in with the version scan and they do not produce any script scan output. Another option which has effect on the scripting engine is `-A`. The aggressive mode of Nmap implies the option `-sC`. ### Usage Examples Simple script scan. `$ nmap -sC hostname` Tracing a specific script. `$ nmap --script=./showSSHVersion.nse --script-trace hostname`
Chapter 9. Nmap Scripting Engine |  | Script Format
| [ Nmap | Sec Tools | Mailing Lists | Site News | About/Contact | Advertising | Privacy ]