diff --git a/docs/scripting.xml b/docs/scripting.xml index 873115984..d5250a36a 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -14,7 +14,7 @@ growing and diverse set of scripts distributed with Nmap, or write their own to meet custom needs. - We designed NSE to be versatile, with the following tasks in mind: + We designed NSE to be versatile, with the following tasks in mind: @@ -56,9 +56,12 @@ When a new vulnerability is discovered, you often want to scan your networks quickly to identify vulnerable systems before the bad guys do. While Nmap isn't a - comprehensive vulnerability scanner, + comprehensive vulnerability scanner, NSE is powerful enough to handle even demanding vulnerability - checks. Many vulnerability detection scripts are already available and we plan to distribute more as they are written. + checks. When the Heartbleed bug affected hundreds of thousands of + systems worldwide, Nmap's developers responded with the + ssl-heartbleed detection script within 2 days. + Many vulnerability detection scripts are already available and we plan to distribute more as they are written. @@ -69,13 +72,10 @@ Many attackers and some automated worms leave backdoors to enable later reentry. Some of these can be detected by - Nmap's regular expression based version detection. For - example, within hours of the MyDoom worm hitting the - Internet, Jay MoranMoran, - Jay posted an Nmap version detection - probe and signature so that others could quickly scan their - networks for MyDoom infections. NSE is needed to reliably - detect more complex worms and backdoors. + Nmap's regular expression based version detection, but more complex worms + and backdoors require NSE's advanced capabilities to reliably detect. + NSE has been used to detect the Double Pulsar NSA backdoor in SMB and + backdoored versions of UnrealIRCd, vsftpd, and ProFTPd. @@ -104,24 +104,24 @@ Scripts are written in the embedded - Lua programming language, version 5.2.Lua programming languageNmap Scripting Engine - The language itself is well documented in the books + Lua programming language, version 5.3.Lua programming languageNmap Scripting Engine + The language itself is well documented in the books - Programming - in Lua, Second Edition and - Lua - 5.1 Reference Manual. + Programming + in Lua, Fourth Edition and + Lua + 5.2 Reference Manual. - Programming in Lua, Second Edition and - Lua 5.1 Reference Manual. + Programming in Lua, Fourth Edition and + Lua 5.2 Reference Manual. -The reference manual, updated for Lua 5.2, is also - freely available - online, as is the +The reference manual, updated for Lua 5.3, is also + freely available + online, as is the first edition of Programming in - Lua. Given the availability of these excellent general + Lua. Given the availability of these excellent general Lua programming references, this document only covers aspects and extensions specific to Nmap's scripting engine. @@ -135,7 +135,7 @@ The reference manual, updated for Lua 5.2, is also - A typical script scan is shown in the + A typical script scan is shown in the . Service scripts producing output in this example are ssh-hostkey, which provides the system's RSA and DSA SSH keys, and rpcinfo, which queries @@ -212,7 +212,7 @@ Black Hat Briefings in 2010. or . Every host will be assumed up and still only host scripts will be run. This technique is useful for scripts like - whoiswhois script + whois-ipwhois-ip script that only use the remote system's address and don't require it to be up. @@ -383,7 +383,7 @@ Black Hat Briefings in 2010. - These scripts aim to actively exploit some vulnerability. + These scripts aim to actively exploit some vulnerability. Examples include jdwp-exec and http-shellshock. @@ -395,7 +395,7 @@ Black Hat Briefings in 2010. Scripts in this category may send data to a third-party database or other network resource. An example - of this is whois, which makes a + of this is whois-ip, which makes a connection to whoiswhois servers to learn about the address of the target. There is always @@ -549,7 +549,7 @@ Black Hat Briefings in 2010. against each target host which matches its hostrule function. Examples are whois, + url="https://nmap.org/nsedoc/scripts/whois-ip.html">whois-ip, which looks up ownership information for a target IP, and path-mtu @@ -650,8 +650,8 @@ advanced users in special cases. For example, you might want to do a configuration review on a bunch of MS SQL servers, some of which are running on nonstandard ports. Rather than slow the Nmap scan by running extensive version detection () so that Nmap will recognize the ms-sql -service, you can force the ms-sql-config script to run against all the +--version-all) so that Nmap will recognize the ms-sql +service, you can force the ms-sql-config script to run against all the targetted hosts and ports by specifying . @@ -735,8 +735,8 @@ Nmap script database, but should be used cautiously since Nmap may contain explo specification, Nmap prints the script name, its categories, and its description. The specifications are the same as those accepted by ; so for example if you want help about - the ftp-anon script, you would run - nmap --script-help ftp-anon. A sample of script + the ssl-enum-ciphers script, you would run + nmap --script-help ssl-enum-ciphers. A sample of script help is shown in . @@ -745,10 +745,16 @@ Nmap script database, but should be used cautiously since Nmap may contain explo $ nmap --script-help "afp-* and discovery" -Starting Nmap 5.36TEST4 ( https://nmap.org ) at 2011-01-27 13:04 PST +Starting Nmap 7.40 ( https://nmap.org ) at 2017-04-21 14:15 UTC + +afp-ls +Categories: discovery safe +https://nmap.org/nsedoc/scripts/afp-ls.html + Attempts to get useful information about files from AFP volumes. + The output is intended to resemble the output of ls. afp-serverinfo -Categories: discovery safe +Categories: default discovery safe https://nmap.org/nsedoc/scripts/afp-serverinfo.html Shows AFP server information. This information includes the server's hostname, IPv4 and IPv6 addresses, and hardware type (for example @@ -823,10 +829,13 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html The scripts in this category are slightly different from other scripts because their output blends in with the version scan results and they do not produce any - script scan output. + script scan output to the screen. If the + + option is used, typical script output will still be available in the + XML output file. - Another option which affects the scripting engine is + Another option which affects the scripting engine is .features enabled by The aggressive Nmap mode implies the option. @@ -901,7 +910,7 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html and, or, and not operators to build Boolean expressions. The operators have the same - precedence + precedence as in Lua: not is the highest, followed by and and then or. You can alter precedence by using parentheses. Because expressions contain @@ -989,9 +998,6 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html 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. Script arguments are often qualified with the relevant @@ -1000,21 +1006,21 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html 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, + amount of time 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 + timeout=250ms, 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 + rlogin-brute.timeout=20s,timeout=250ms. In + that case, the timeout will be 20 seconds for the + rlogin-brute script, and 250 milliseconds 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 (separated by commas or newlines) and specify just the file name @@ -1029,7 +1035,7 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html example of -nmap -sC --script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},xmpp-info.server_name=localhost' + nmap -sC --script-args 'user=foo,pass=",{}=bar",paths={/admin,/cgi-bin},xmpp-info.server_name=localhost' Notice that the script arguments are surrounded in single quotes. For the @@ -1039,12 +1045,13 @@ https://nmap.org/nsedoc/scripts/afp-showmount.html relevant manual. The command results in this Lua table: nmap.registry.args = { - user = "foo", - pass = ",{}=bar", - whois = { - whodb = "nofollow+ripe" - }, - xmpp-info.server_name="localhost" + user = "foo", + pass = ",{}=bar", + paths = { + "/admin", + "/cgi-bin" + }, + xmpp-info.server_name="localhost" } 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: @@ -1057,9 +1064,8 @@ local server_name = stdnse.get_script_args("xmpp-info.server_name") nmap.registry.args table. For this reason, short or ambiguous names like user are not recommended. Some scripts prefix their arguments with their script name, like - smtp-open-relay.domain. Others, like - whois in the example above, take their arguments in a - table named after the script. Arguments used by libraries, which can + smtp-open-relay.domain. + Arguments used by libraries, which can affect many scripts, usually have names beginning with the name of the library, like smbuser and creds.snmp.