From cfc16fb6de6c3d844238525c64d870d00c439fbf Mon Sep 17 00:00:00 2001 From: batrick Date: Fri, 29 May 2009 07:14:48 +0000 Subject: [PATCH] Updated refguide and scripting chapter of book to the new syntax of the --script-args as well as a more full account of some details. The previous text was very vague about some features, especially array values. --- docs/refguide.xml | 32 +++++++++++++++++--------------- docs/scripting.xml | 43 ++++++++++++++++++++++++++++++++----------- 2 files changed, 49 insertions(+), 26 deletions(-) diff --git a/docs/refguide.xml b/docs/refguide.xml index 491e2c4d3..cad53ac5b 100644 --- a/docs/refguide.xml +++ b/docs/refguide.xml @@ -2174,25 +2174,27 @@ which lists the category or categories in which each script belongs. - + script arguments -Lets you provide arguments to NSE scripts. Arguments are passed -as name=value pairs. The provided argument is -processed and stored inside a Lua table, to which all scripts have -access. The names are taken as strings (which must be alphanumeric -values) and used as keys inside the -argument-table. Values are either strings or tables -themselves (surrounded by ‘{’ and -‘}’). -For example, you could pass the comma-separated arguments: -user=bar,pass=foo,whois={whodb=nofollow+ripe}. -String arguments are potentially used by several scripts; subtables are -normally used by only one script. In scripts that take a subtable, the -subtable is usually named after the script (like -whois in this example). + +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. + diff --git a/docs/scripting.xml b/docs/scripting.xml index 739d95d9a..cf3e12141 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -701,24 +701,45 @@ Nmap script database. script arguments Arguments may be passed to NSE scripts using the - option. The script arguments are generally - name-value pairs. They are provided to scripts as a Lua table named - args inside nmap.registry. - The argument names are keys for the corresponding values. The values can be - either strings or tables. Subtables can be used to pass arguments to - scripts with finer granularity, such as passing different usernames for - different scripts. Here is a typical Nmap invocation with script arguments: - + 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. + + + 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 + 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. + + Here is a typical Nmap invocation with script arguments: 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},userdb=C:\Some\Path\To\File The aforementioned command results in this Lua table: -{user="foo",pass="bar",whois={whodb="nofollow+ripe"}} +{user="foo",pass=",{}=bar",whois={whodb="nofollow+ripe"},userdb="C:\\Some\\Path\\To\\File"} You could therefore access the username (foo)