skip to content

In Nmap, how do you preview which scripts a --script expression such as "safe and not http-*" would select, and how do arguments reach them?

level: middleimportance: should knowfreq 24%

answer

  1. a dry run before the scan
  2. the help option reuses the same syntax
  3. not first, then and, then or
  4. quote what has spaces or stars
  5. command line beats the file

basics

~10 s

--script-help takes the same specification as --script and prints each matching script's name, categories and description, without scanning. Arguments go in through --script-args name=value,... or --script-args-file, and a command-line value supersedes the file.

solid answer

~40 s

`--script` takes a comma-separated list of script names, categories, directories ending in `/` and Boolean expressions using `and`, `or`, `not`, parentheses and `*` wildcards. Precedence follows Lua: `not` binds first, then `and`, then `or`. Quote any expression that has spaces or a wildcard so the shell leaves it alone. `nmap --script-help "<same expression>"` prints the name, categories and description of each match and exits before any scan, so the change record can list exactly what will run. Arguments are `name=value` pairs in `--script-args`, often qualified with the script's name, or one per line in `--script-args-file`; a value on the command line supersedes the file. A `+` prefix forces a script to run even when its rule would not match, which an audit plan should list as an exception.

code

bash · 5 lines
bash
# Preview the selection and keep the help as XML for the change record
nmap --script-help "safe and not http-*" -oX selection.xml

# Run it on one documented host, with arguments read from a file
nmap -sV -p 22,443 --script "safe and not http-*" --script-args-file args.txt 192.0.2.10

go deeper

for a junior

Recall that --script-help previews what a --script selection would run, and that script arguments go in with --script-args.

for a middle

Explain the selection syntax: names, categories, directories, wildcards, and/or/not with Lua precedence, quoting, and that a command-line argument supersedes the argument file.

for a senior

Show the audit habit: put the resolved name list and Nmap release in the change record, use --script-trace to give owners an application-level record, and flag every + as an exception.

for a principal

Decide how selections are governed: a reviewed list per environment rather than free-form expressions, with the preview attached to every change.

## How a selection is resolved The argument to `--script` is a comma-separated list. Nmap interprets each element **first as an expression, then as a category, and finally as a file or directory name**. A name needs no `.nse` extension. A directory name ending in `/` loads every `.nse` file in that directory, without descending into subdirectories. Relative names are looked for in the `scripts` subdirectory of the places Nmap searches in order: `--datadir`, `$NMAPDIR`, `~/.nmap`, the directory holding the `nmap` executable, and a few more, ending with the current directory. Names in the index (`scripts/script.db`) also accept a shell-style `*` wildcard. | Expression | Loads | |---|---| | `"http-*"` | every script whose name starts with `http-` | | `"not intrusive"` | every script except those in `intrusive` | | `"default or safe"` | same as `"default,safe"`: either category or both | | `"default and safe"` | only scripts in both | | `"(default or safe or intrusive) and not http-*"` | those three categories, minus names starting `http-` | ## Precedence and quoting The operators bind as in Lua: `not` first, then `and`, then `or`; parentheses override. So `"default or intrusive and not http-*"` means every default script **plus** the intrusive scripts whose names do not begin `http-`. It does not remove `http-` scripts from the default part. When a change record contains an expression with more than one operator, add parentheses, and always let `--script-help` print the result. Any expression with a space or a wildcard must be quoted. Otherwise the shell splits it into several words or expands the `*` against local files, and Nmap receives something other than what was reviewed. ## Previewing a selection `--script-help` accepts the same specifications as `--script`. For each match Nmap prints the script name, its categories and its description. It then exits before scanning any target, so it is safe to run on a workstation and cheap to repeat after any edit. With `-oX`, an XML representation of the help is written to the file, which can be attached to the change record. Previewing has three uses: 1. Show the board **names**, not category words. 2. Confirm that an expression with `not` or a wildcard says what its author intended. 3. Compare the listing between two Nmap releases. ## Passing arguments - `--script-args` takes comma-separated `name=value` pairs. Names and values may not contain whitespace or the characters `{`, `}`, `=` and `,` unless quoted; a table can be written with braces, as in Lua. - Many scripts qualify argument names with the script's name, and a script checks its fully qualified name first. Some arguments belong to a library and therefore affect every script that uses it. The same argument cannot hold different values for different scripts. - `--script-args-file` loads the same arguments from a file, comma- or newline-separated, with no shell quoting. A path is looked up along Nmap's usual search path. Arguments on the command line supersede ones in the file. - The online NSE documentation lists the arguments each script accepts, and the script's own header comment does too. ## Forcing, tracing and debugging - A `+` before a name, category or expression forces those scripts to run regardless of their `portrule` or `hostrule`. The book's example is forcing a configuration review of database servers on a nonstandard port that detection did not recognise. In an audit plan it is an exception: it sends that script's probes to ports its rule judged irrelevant. - `--script-trace` prints every communication a script makes: protocol, addresses and data, as a hex dump when more than 5% is unprintable. `--packet-trace` also enables it. This is the record a system owner can ask for. - `--script-timeout` caps one script instance. An instance that exceeds it is terminated and produces no output; `-d` reports each timeout. - `--script-updatedb` rebuilds the index and is needed only after adding or removing scripts or changing categories. ## In an audit plan Write the expression, the resolved name list, the Nmap release, the argument file and any `+` exceptions into one record, and review the record rather than the command line. ## Selection pitfalls - Each element is tried first as an expression, then as a category and finally as a file or directory name, so a misspelling that matches nothing in the index falls through to a path lookup. Compare the preview with the number of scripts you expect. - A wildcard such as `http-*` matches every script whose name starts that way, including ones added in a later release, so a stored expression can quietly grow. - The special argument `all` selects every script in the database, including the categories the reference guide calls dangerous; it never belongs in a production plan. - Argument names are shared: the same argument cannot be given different values for different scripts, so two scripts that need different values for one name cannot run in one command.

  • What does a + in front of a script name change, and when might an audit plan allow it?
    It forces that script to run even where its portrule or hostrule would not match, for instance against a database service on a nonstandard port that detection did not recognise. The cost is that probes go to ports the script's rule judged irrelevant, so list the ports and the script as an explicit exception.
  • How can the owner of a system see exactly what a script sent?
    `--script-trace` prints all incoming and outgoing script communication: protocol, source, target and data, in hex when more than 5% is unprintable. `--packet-trace` turns it on too. Capturing that output with the scan gives the owner an application-level record to compare with their own logs.

  • --script-help runs the scripts against the target to show their output
  • Wildcards and Boolean expressions work the same without quotes
  • In a Boolean expression, or binds tighter than and
  • --script-args-file overrides the command line
  • A directory ending in / loads its subdirectories too