diff --git a/docs/refguide.xml b/docs/refguide.xml index cad53ac5b..0637de47e 100644 --- a/docs/refguide.xml +++ b/docs/refguide.xml @@ -2174,26 +2174,29 @@ which lists the category or categories in which each script belongs. - + script arguments -Lets you provide arguments to NSE scripts. Arguments are a comma separated list -of name=value pairs or array values within a table. Array -values are simply values with implicit ordered numeric keys. Array Values as -well as Keys and Values in key-value pairs may be strings of characters not -including "{", "}", "=", "," or whitespace. You may quote -these strings to allow all characters. The quote delimiter must be escaped by -a backslash if used inside the quoted string. A backslash is only used as an -escape mechanism for quote delimiters in quoted strings; in all other contexts -it is interpreted literally. Array Values and Values in key-value pairs are -allowed to be nested tables delimited by { and -}. An example of script arguments: --script-args -auth={user=foo,pass=',{}=bar'},userdb=C:\Path\To\File. See NSE's -online script documentation at http://nmap.org/nsedoc for each script's -accepted arguments. +Lets you provide arguments to NSE scripts. 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 or more name-value pairs, including nested +tables. An example of script arguments: +. +The online NSE Documentation Portal at +lists the arguments that each script accepts. diff --git a/docs/scripting.xml b/docs/scripting.xml index cf3e12141..3febac7eb 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -492,11 +492,11 @@ Nmap script database. - + - Provides arguments to the scripts. See for a detailed explanation. + Provides arguments to the scripts. See + for a detailed explanation. @@ -702,55 +702,57 @@ Nmap script database. Arguments may be passed to NSE scripts using the option. The arguments describe a table of - key-value pairs and possibly array values. Array values in this case have - omitted numerical keys. The arguments are provided to scripts as a Lua - table named args inside nmap.registry. + key-value pairs and possibly array values. The arguments are provided to + scripts as a table in the registry called + nmap.registry.args. - Similar to Lua table constructor syntax, we delimit key-value pairs and - array values by commas. A key-value pair is separated by an equal sign. - Each successive array value is accessed by implicit integer keys, - starting from 1. Array values do not necessarily need to appear after - all key-value pairs or in succession. They are typically used to - enumerate a list of items, such as proxy hosts or usernames. - - - A point of divergence is the acceptance of (possibly unquoted) strings - containing many illegal characters. A key, value, or an array value may - be a sequence of characters not including '{', '}', ',', - '=' or whitespace. You may overcome this restriction by using - quotes (single or double) to allow all characters within the quotation - marks. Naturally, the quote delimiter cannot appear within your quoted - string unless you escape the quote using a backslash. A backslash is only + 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. A value in a key-value pair or an - array value may also be a nested table delimited by, as in Lua, - '{' and '}'. Note that nested subtables are commonly - used to pass arguments to scripts with finer granularity, such as passing - different usernames for different scripts. + backslash is interpreted literally. - Here is a typical Nmap invocation with script arguments: - + + 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. + Nested subtables are commonly used to pass arguments specific to one + script, in a table named after the script. That is what is happening with + the whois table in the example below. + + + Here is a typical Nmap invocation with script arguments: + example of + nmap -sC --script-args user=foo,pass=',{}=bar',whois={whodb=nofollow+ripe},userdb=C:\Some\Path\To\File - - - The aforementioned command results in this Lua table: - + + + That command results in this Lua table: {user="foo",pass=",{}=bar",whois={whodb="nofollow+ripe"},userdb="C:\\Some\\Path\\To\\File"} - - You could therefore access the username (foo) - inside your script with this statement: - - local username = nmap.registry.args.user - - Subtables used to override - options for scripts are usually named after the script to ease retrieval. - - + You could then access the username "foo" inside + your script with this statement: + +local username = nmap.registry.args.user + + + + The online NSE Documentation Portal at lists the arguments that each script + accepts. + +