From 1623bcfa665625743d3f98db01ec62f100b69593 Mon Sep 17 00:00:00 2001 From: fyodor Date: Thu, 1 Mar 2012 08:56:45 +0000 Subject: [PATCH] Update --script-args to note that many scripts qualify their arguments with the script name, and that you can pass unqualified arguments to affect every script using that name. Also updated scripting.xml to emphasize that instead of using nmap.registry.args directly, scripts should get their arguments with stdnse.get_script_args. Regenerated the nroff too after making these changes to the source XML --- docs/nmap-update.1 | 4 ++-- docs/nmap.1 | 11 ++++++----- docs/refguide.xml | 10 ++-------- docs/scripting.xml | 33 +++++++++++++++++++++++++++------ docs/zenmap.1 | 4 ++-- 5 files changed, 39 insertions(+), 23 deletions(-) diff --git a/docs/nmap-update.1 b/docs/nmap-update.1 index 3550ffbd4..a63e27f9a 100644 --- a/docs/nmap-update.1 +++ b/docs/nmap-update.1 @@ -2,12 +2,12 @@ .\" Title: nmap-update .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 02/25/2012 +.\" Date: 03/01/2012 .\" Manual: nmap-update Reference Guide .\" Source: nmap-update .\" Language: English .\" -.TH "NMAP\-UPDATE" "1" "02/25/2012" "nmap\-update" "nmap\-update Reference Guide" +.TH "NMAP\-UPDATE" "1" "03/01/2012" "nmap\-update" "nmap\-update Reference Guide" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/docs/nmap.1 b/docs/nmap.1 index d5f2e73f3..9cfb22980 100644 --- a/docs/nmap.1 +++ b/docs/nmap.1 @@ -2,12 +2,12 @@ .\" Title: nmap .\" Author: [see the "Author" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 02/25/2012 +.\" Date: 03/01/2012 .\" Manual: Nmap Reference Guide .\" Source: Nmap .\" Language: English .\" -.TH "NMAP" "1" "02/25/2012" "Nmap" "Nmap Reference Guide" +.TH "NMAP" "1" "03/01/2012" "Nmap" "Nmap Reference Guide" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -1354,9 +1354,10 @@ http\-\&. 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 \(oq{\(cq, \(oq}\(cq, \(oq=\(cq, or \(oq,\(cq\&. To include one of these characters in a string, enclose the string in single or double quotes\&. Within a quoted string, \(oq\e\(cq 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\&. A complex example of script arguments is -.\" --script-args: example of .sp .if n \{\ .RS 4 .\} .nf \fB\-\-script\-args \*(Aquser=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},userdb=custom\*(Aq\fR .fi .if n \{\ .RE .\} -The online NSE Documentation Portal at +{}, just as in Lua\&. A table may contain simple string values or more name\-value pairs, including nested tables\&. Many scripts qualify their arguments with the script name, as in +xmpp\-info\&.server_name\&. You may use that full qualified version to affect just the specified script, or you may pass the unqualified version (server_name +in this case) to affect all scripts using that argument name\&. A script will first check for its fully qualified argument name (the name specified in its documentation) before it accepts an unqualified argument name\&. A complex example of script arguments is +\fB\-\-script\-args \*(Aquser=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},xmpp\-info\&.server_name=localhost\*(Aq\fR\&. The online NSE Documentation Portal at \m[blue]\fB\%http://nmap.org/nsedoc/\fR\m[] lists the arguments that each script accepts\&. .RE diff --git a/docs/refguide.xml b/docs/refguide.xml index a2c7930cf..bcf38e31a 100644 --- a/docs/refguide.xml +++ b/docs/refguide.xml @@ -2398,14 +2398,8 @@ 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. A complex example of script arguments is - -example of - ---script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},userdb=custom' - - -The online NSE Documentation Portal at +tables. Many scripts qualify their arguments with the script name, as in xmpp-info.server_name. You may use that full qualified version to affect just the specified script, or you may pass the unqualified version (server_name in this case) to affect all scripts using that argument name. A script will first check for its fully qualified argument name (the name specified in its documentation) before it accepts an unqualified argument name. A complex example of script arguments is +. The online NSE Documentation Portal at lists the arguments that each script accepts. diff --git a/docs/scripting.xml b/docs/scripting.xml index a7c45a3c1..1d45dd592 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -959,8 +959,9 @@ http://nmap.org/nsedoc/scripts/afp-showmount.html option. The arguments describe a table of key-value pairs and possibly array values. The arguments are provided to scripts as a table in the registry called - nmap.registry.args. + nmap.registry.args, though they are normally accessed through the stdnse.get_script_args function. + The syntax for script arguments is similar to Lua's table constructor syntax. Arguments are a comma-separated list of @@ -984,6 +985,27 @@ http://nmap.org/nsedoc/scripts/afp-showmount.html script, in a table named after the script. That is what is happening with the whois table in the example below. + + Script arguments are often qualified with the relevant + script name so that a user doesn't unintentially affect multiple + scripts with a single generic name. For example, you can set + the timeout for responses to the + broadcast-ping script (and only that script) + by setting broadcast-ping.timeout to the + number of milliseconds you're willing to wait. Sometimes, + however, you want a script argument applied more widely. If you + remove the qualification and specify just + timeout=250, you will be setting the value + for more than a dozen scripts in addition to + broadcast-ping. You can even combine + qualified and unqualified arguments, and the most specific match + takes precedence. For example, you could specify + rlogin-brute.timeout=20000,timeout=250. In + that case, the timeout will be 20,000 for the + rlogin-brute scripts, and 250 for all other + scripts which support this variable + (broadcast-ping, + lltd-discovery, etc.) Rather than pass the arguments on the command line with , you may store them in a file @@ -999,7 +1021,7 @@ http://nmap.org/nsedoc/scripts/afp-showmount.html example of -nmap -sC --script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},userdb=custom' +nmap -sC --script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},xmpp-info.server_name=localhost' Notice that the script arguments are surrounded in single quotes. For the @@ -1014,13 +1036,12 @@ nmap.registry.args = { whois = { whodb = "nofollow+ripe" }, - userdb="custom" + xmpp-info.server_name="localhost" } - You could then access the username "foo" inside - your script with this statement: + While you could access the values directly from nmap.registry.args, it is normally better to use the stdnse.get_script_args function like this: -local username = nmap.registry.args.user +local server_name = stdnse.get_script_args("xmpp-info.server_name") diff --git a/docs/zenmap.1 b/docs/zenmap.1 index 1315e5ea7..1a13da411 100644 --- a/docs/zenmap.1 +++ b/docs/zenmap.1 @@ -2,12 +2,12 @@ .\" Title: zenmap .\" Author: [see the "Authors" section] .\" Generator: DocBook XSL Stylesheets v1.76.1 -.\" Date: 02/25/2012 +.\" Date: 03/01/2012 .\" Manual: Zenmap Reference Guide .\" Source: Zenmap .\" Language: English .\" -.TH "ZENMAP" "1" "02/25/2012" "Zenmap" "Zenmap Reference Guide" +.TH "ZENMAP" "1" "03/01/2012" "Zenmap" "Zenmap Reference Guide" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" -----------------------------------------------------------------