Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Nmap Scripting Engine

Script Categories and Arguments

Understand NSE categories such as safe, default, discovery, intrusive and vuln, select scripts with boolean expressions, and pass arguments with --script-args.

Nmap ships with several hundred scripts, so you need a way to choose among them. Every script belongs to one or more categories, and you can pick whole categories, single names, wildcards or a boolean expression that combines them. In this lesson you learn what each category means for safety, how to build selection expressions, and how to give scripts options with --script-args.

This is also where the main safety idea of NSE appears: the categories tell you in advance how much risk a script carries. Reading them is part of responsible scanning.

Example commands are read-only, since Nmap cannot run in the browser. The Python stand-ins reproduce the selection logic so you can experiment with expressions.

The main categories

Category What it is for Risk
default The set run by -sC: fast, useful, low impact Low
safe Does not crash services, use big bandwidth or exploit things Low
discovery Learns more about the network: DNS names, shares, directories Low to medium
version Extends version detection Low
auth Checks authentication, for example anonymous logins Medium
vuln Checks for known vulnerabilities Medium
brute Guesses credentials High: lockouts and noisy logs
intrusive May use lots of resources or crash a service High
exploit Actively exploits a weakness High
dos Tests for denial-of-service weakness; can crash services High
malware Looks for backdoors and malware signs Medium
broadcast Sends broadcasts to find hosts on the local network Medium
external Sends data to third parties (such as WHOIS servers) Privacy risk
fuzzer Sends unexpected input to find bugs High

A script can be in several categories, for instance http-title is in default, discovery and safe. A script in intrusive or dos should never run against a system you have not agreed on. Note the external category: the script might send your target's address to a third-party server.

Selecting scripts

The --script option takes a comma-separated list. Each item can be:

  • a script name: http-title
  • a category: safe
  • a file or directory path: ./my-scripts/
  • a wildcard: "ssh-*" (quote it so your shell does not expand it)
  • a boolean expression with and, or, not and parentheses
Terminal
# Example commands (read-only)
nmap --script safe 192.0.2.10
nmap --script "default or safe" 192.0.2.10
nmap --script "default and safe" 192.0.2.10          # both categories
nmap --script "not intrusive" 192.0.2.10             # everything except intrusive
nmap --script "(default or discovery) and not intrusive" 192.0.2.10
nmap --script "http-*" -p 80,443 192.0.2.10

Expressions are the safest way to say "run useful things but never the risky ones".

An expression evaluator

The stand-in below gives each script a set of categories and evaluates the same kind of expression. Python's eval is used only on text we control after replacing names with True/False, and the example is pure teaching code.

Python Stand-in: evaluate --script expressions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Compare "default" with "not intrusive": the second also includes scripts like http-headers that are not in default. And "intrusive or dos" lists exactly the scripts you need to keep away from production systems.

Passing arguments

Many scripts accept options. You pass them with --script-args as comma-separated name=value pairs. Script-specific names are usually prefixed with the script name (http-title.url) or a library name (http.useragent), so different scripts do not collide.

Terminal
# Example commands (read-only)
nmap --script http-title --script-args http-title.url=/status 192.0.2.10
nmap --script http-headers --script-args http.useragent="Lab-Audit/1.0" 192.0.2.10
nmap --script-args-file args.txt --script default 192.0.2.10

Values containing commas or quotes can be grouped with braces: --script-args 'user=admin,paths={/a,/b}'. Use --script-help to see a script's argument names.

A script may also have an option you should always set when testing your own scanning: a clear user agent string, so your server's log owner can see who connected.

Python Stand-in: parse --script-args

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Updating and tracing

  • nmap --script-updatedb rebuilds script.db after you add or remove a script file.
  • --script-trace shows the data each script sends and receives. It is helpful for learning and debugging, and shows what a monitoring system will see.
  • --script-timeout 30s limits how long one script may run.
  • -sC is shorthand for --script=default.

Choosing sensibly

A good routine for a new target that you are allowed to test:

  1. Start with -sV and -sC.
  2. Add --script "safe and discovery" or specific scripts for what you saw.
  3. Use vuln scripts only when authorised and with the owners informed.
  4. Avoid brute, dos, fuzzer and exploit unless you have explicit written permission and a plan for outages.

For common scripts and sample output see Common NSE Scripts.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which category should you be most careful with on a production server?

    dos scripts test denial-of-service weaknesses and can crash services. intrusive, brute, exploit and fuzzer need the same caution.
  2. 2. What does --script "(default or discovery) and not intrusive" do?

    The expression combines categories with and/or/not, so scripts in intrusive are removed from the union of default and discovery.
  3. 3. How do you pass an option to a script?

    --script-args takes comma-separated name=value pairs, usually prefixed with the script or library name.
  4. 4. Why is the 'external' category a privacy concern?

    External scripts contact other services, such as WHOIS or geolocation servers, so details of your scan leave your network.
  5. 5. What command rebuilds the script index after adding a file?

    --script-updatedb regenerates script.db so categories and names include the new file.

Summary

  • Categories describe what a script does and how risky it is; safe and default are the low-risk starting points.
  • --script accepts names, categories, wildcards, paths and boolean expressions.
  • --script-args passes name=value options; --script-help lists them.
  • Keep brute, dos, exploit, fuzzer and intrusive for authorised lab or test work.

Next: Common NSE Scripts