NSE scripts define a list of categories they belong to. Currently defined categories are auth, broadcast, brute, default. discovery, dos, exploit, external, fuzzer, intrusive, malware, safe, version, and vuln. Category names are not case sensitive. The following list describes each category.

NSE supports four types of scripts, which are distinguished by the kind of targets they take and the scanning phase in which they are run. Individual scripts may support multiple types of operation.

These are the five command-line arguments specific to script scanning:

Some other Nmap options have effects on script scans. The most prominent of these is -sV. A version scan automatically executes the scripts in the version category. The scripts in this category are slightly different from other scripts because their output blends in with the version scan results and they do not produce any script scan output to the screen. If the -oX option is used, typical script output will still be available in the XML output file.

Another option which affects the scripting engine is -A. The aggressive Nmap mode implies the -sC option.

The --script option takes a comma-separated list of categories, filenames, and directory names. Some simple examples of its use:

When referring to scripts from script.db by name, you can use a shell-style ‘*’ wildcard.

More complicated script selection can be done using the and, or, and not operators to build Boolean expressions. The operators have the same precedence as in Lua: not is the highest, followed by and and then or. You can alter precedence by using parentheses. Because expressions contain space characters it is necessary to quote them.

Names in a Boolean expression may be a category, a filename from script.db, or all. A name is any sequence of characters not containing ‘ ’, ‘,’, ‘(’, ‘)’, or ‘;’, except for the sequences and, or, and not, which are operators.

Arguments may be passed to NSE scripts using the --script-args option. The arguments describe a table of key-value pairs and possibly array values. The arguments are provided to scripts as a table in the registry called nmap.registry.args, though they are normally accessed through the stdnse.get_script_args function.

The syntax for script arguments is similar to Lua's table constructor syntax. Arguments are a comma-separated list of name=value pairs. Names and values may be strings not containing whitespace or the characters ‘{’, ‘}’, ‘=’, or ‘,’. To include one of these characters in a string, enclose the string in single or double quotes. Within a quoted string, ‘\’ escapes a quote. A backslash is only used to escape quotation marks in this special case; in all other cases a backslash is interpreted literally.

Values may also be tables enclosed in {}, just as in Lua. A table may contain simple string values, for example a list of proxy hosts; or more name-value pairs, including nested tables.

Script arguments are often qualified with the relevant script name so that a user doesn't unintentionally affect multiple scripts with a single generic name. For example, you can set the timeout for responses to the broadcast-ping script (and only that script) by setting broadcast-ping.timeout to the amount of time you're willing to wait. Sometimes, however, you want a script argument applied more widely. If you remove the qualification and specify just timeout=250ms, you will be setting the value for more than a dozen scripts in addition to broadcast-ping. You can even combine qualified and unqualified arguments, and the most specific match takes precedence. For example, you could specify rlogin-brute.timeout=20s,timeout=250ms. In that case, the timeout will be 20 seconds for the rlogin-brute script, and 250 milliseconds for all other scripts which support this variable (broadcast-ping, lltd-discovery, etc.)

Rather than pass the arguments on the command line with --script-args, you may store them in a file (separated by commas or newlines) and specify just the file name with --script-args-file. Options specified with --script-args on the command-line take precedence over those given in a file. The filename may be given as an absolute path or relative to Nmap's usual search path (NMAPDIR, etc.)

Here is a typical Nmap invocation with script arguments:

Notice that the script arguments are surrounded in single quotes. For the Bash shell, this prevents the shell from interpreting the double quotes and doing automatic string concatenation. Naturally, different shells may require you to escape quotes or to use different quotes. See your relevant manual. The command results in this Lua table:

nmap.registry.args = {
  user = "foo",
  pass = ",{}=bar",
  paths = {
    "/admin",
    "/cgi-bin"
  },
  xmpp-info.server_name="localhost"
}

While you could access the values directly from nmap.registry.args, it is normally better to use the stdnse.get_script_args function like this:

local server_name = stdnse.get_script_args("xmpp-info.server_name")

All script arguments share a global namespace, the nmap.registry.args table. For this reason, short or ambiguous names like user are not recommended. Some scripts prefix their arguments with their script name, like smtp-open-relay.domain. Arguments used by libraries, which can affect many scripts, usually have names beginning with the name of the library, like smbuser and creds.snmp.

The online NSE Documentation Portal at https://nmap.org/nsedoc/ lists the arguments that each script accepts, including any library arguments that may influence the script.