diff --git a/docs/scripting.xml b/docs/scripting.xml index a4fa37e90..c94972cbb 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -194,6 +194,13 @@ Nmap done: 1 IP address (1 host up) scanned in 0.33 seconds are generally only used for script debugging and development. Script scanning is also included as part of the (aggressive scan) option. + + Scripts are not run in a sandbox and thus could accidentally or + maliciously damage your system or invade your privacy. Never run + scripts from third parties unless you trust the authors or have + carefully audited the scripts yourself. + + Script Categories script categories @@ -402,7 +409,6 @@ and vuln. Category names are not case sensitive. The follow - @@ -427,104 +433,51 @@ and vuln. Category names are not case sensitive. The follow - + -Turns on the use of NSE for script scanning and specifies the scripts to be -loaded and possibly run. The argument to --script is a comma seperated list of -predicates, files or directories of scripts. A predicate is used to load a -script based on categories or filename. Any one of these comma delimited -strings is first interpretted as a predicate and then as a file or directory -if the predicate was not used to load a script. +Runs a script scan using the comma-separated list of filenames, script +categories, and directories. Each element in the list may also be a +Boolean expression describing a more complex set of scripts. Each +element is interpreted first as an expression, then as a category, and +finally as a file or directory name. The special argument +all makes every script in Nmap's script database +eligible to run. -A --script predicate is a case-insensitive boolean equation made up of -categories, filenames or a filename pattern conforming to a basic pattern. The -boolean operators are the same as in Lua: and, -or and not. Using these boolean operators, -you may form equations that give you tight control over which scripts may be -run in a flexible and easy manner. Typically, these predicates must be quoted -in the shell as they often contain spaces or other special shell characters. +File and directory names may be relative or absolute. Absolute names are +used directly. Relative paths are looked for in the following places +until found: +data filesdirectory search orderscripts, location of + + +$NMAPDIRNMAPDIR environment variable +~/.nmap (not searched on Windows).nmap directory +NMAPDATADIRNMAPDATADIR +the current directory + +A scripts subdirectory is also tried in each of +these. -When NSE first attempts to intepret a string as a predicate, each category, -filename or filename pattern is considered a boolean variable, true or -false. When this predicate is tested for a script in the script database: -(1) a category is only true if the script entry -is of that category; (2) a filename is only true if the -script entry has the same filename (optionally ignoring the extension); -or (3) a filename pattern is only true if the script entry in the -database has a filename that matches the pattern. The category "all" matches -all script entires. A filename pattern may be expressed using an appropriately -placed * character which expands to 0 or more characters in -the filename. A couple predicate examples at this point may prove illustrative: - ---script "intrusive" - -Matches scripts that are under the intrusive category. - ---script "all and not intrusive" - -Matches scripts all scripts that not under the intrusive category. - ---script "safe or http-brute" - -Matches scripts that are under the safe category or have the filename -"http-brute". - ---script "discovery or http-*" - -Matches scripts that are under the discovery category or have a filename -beginning with "http-". - ---script "(all and not intrusive) or ( - -You may use parenthesis to force operator associations. A script predicate -conforms to a very strict syntax which is included here in ABNF notation: - - -predicate = exp / ("(" exp ")") -exp = name / predicate binop predicate / unop predicate -binop = "and" / "or" -unop = "not" -name = %x21-%x27 / - %x2A-%x2B / - %x2D-%x3A / - %x3C-%x7E ; All visible characteres except ',', '(', ')', and ';' - +When a directory name is given, Nmap loads every file in the directory +whose name ends with .nse. All other files are +ignored and directories are not searched recursively. When a filename is +given, it does not have to have the .nse extension; +it will be added automatically if necessary. -If using the string as a predicate did not result in any files being loaded, -then NSE finally attempts to interpret the string as a script filename or -directory. You may specify a script or directory of scripts as an absolute -or relative path. Absolute paths are used as supplied. Relative paths are -searched for in the following places until found:data -filesdirectory search -orderscripts, location -of --datadir/; -$NMAPDIR/;NMAPDIR -environment variable ~/.nmap/ (not - searched on Windows);.nmap directory -NMAPDATADIR/ -orNMAPDATADIR -./. A scripts/ subdirectory is also -tried in each of these. - - -If a directory is specified and found, Nmap loads all NSE -scripts (any filenames ending with .nse) from that -directory. Filenames without the nse extension are -ignored. Nmap does not search recursively into subdirectories to find -scripts. If individual file names are specified, the file extension -does not have to be nse. +See for examples and a full +explanation of the option. +script databasescript.db +scripts, location of Nmap scripts are stored in a scripts subdirectory of the Nmap data directory by default (see ). For efficiency, scripts are indexed in @@ -533,13 +486,6 @@ in scripts/script.db,script.d which lists the category or categories in which each script belongs. Give the argument all to execute all scripts in the Nmap script database. - -Scripts are not run in a sandbox and thus could accidentally or -maliciously damage your system or invade your privacy. Never run scripts from -third parties unless you trust the authors or have carefully audited the -scripts yourself. - - @@ -549,7 +495,7 @@ scripts yourself. - provides arguments to the scripts. See Provides arguments to the scripts. See for a detailed explanation. @@ -620,6 +566,133 @@ scripts yourself. + + Script Selection + + + + The option takes a comma-separated list + of categories, filenames, and directory names. Some simple + examples of its use: + + + + + nmap --script default,safe + + Loads all scripts in the default and + safe categories. + + + + nmap --script smb-os-discovery + + Loads only the smb-os-discovery.nse + script. Note that the .nse extension is + optional. + + + + nmap --script default,banner,/home/user/customscripts + + Loads the script in the default + category, the banner.nse script, and all + .nse files in the directory + /home/user/customscripts. + + + + nmap --script all + + Loads every script in + script.db.script.db + + + + + + When referring to scripts from script.db by + name, you can use a shell-style ‘*’ + wildcard. + + + + + nmap --script "http-*" + + Loads all scripts whose name starts with + http-, such as + http-auth.nse and + http-open-proxy.nse. The argument to + had to be in quotes to protect the + wildcard from the shell. + + + + + + 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. + + + + + nmap --script "not intrusive" + + Loads every script except for those in the + intrusive category. + + + + nmap --script "default or safe" + + This is functionally equivalent to + nmap --script "default,safe". It loads all + scripts that are in the default category or + the safe category or both. + + + + nmap --script "default and safe" + + Loads those scripts that are in + both the default and + safe categories. + + + + nmap --script "(default or safe or intrusive) and not http-*" + + Loads scripts in the default, + safe, or intrusive + categories, except for those whose names start with + http-. + + + + + + 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 to Scripts script arguments @@ -636,9 +709,7 @@ scripts yourself. example of - -$ nmap -sC --script-args user=foo,pass=bar,whois={whodb=nofollow+ripe} - +nmap -sC --script-args user=foo,pass=bar,whois={whodb=nofollow+ripe} The aforementioned command results in this Lua table: @@ -665,9 +736,7 @@ $ nmap -sC --script-args user=foo,pass=bar,whois={whodb=nofollow+ripe} example of - - $ nmap -sC example.com - + nmap -sC example.com Executing a specific script with tracing enabled: @@ -675,18 +744,14 @@ $ nmap -sC --script-args user=foo,pass=bar,whois={whodb=nofollow+ripe} example of example of - - $ nmap --script=./showSSHVersion.nse --script-trace example.com - + nmap --script=./showSSHVersion.nse --script-trace example.com Execute all scripts in the mycustomscripts directory as well as all default scripts in the safe category: - - $ nmap --script=mycustomscripts,safe example.com - + nmap --script=mycustomscripts,safe example.com