diff --git a/docs/scripting.xml b/docs/scripting.xml index 29974ca2b..b2e415904 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -132,15 +132,54 @@ The reference manual is also scripts) and results are integrated into Nmap normalnormal output and XML output.XML output - Two types of scripts are supported: service and host - scripts. Service scripts relate to a certain open port - (service) on the target host, and any results they produce are included - next to that port in the Nmap output port table. Host scripts, - on the other hand, run no more than once against each target IP - and produce results below the port table. shows a - typical script scan. Service scripts producing - output in this example are + + + Three phases of NSE scans are supported: + + + + Script Pre-scanning phase + + This phase will run before all other Nmap scan phases, + and can be used by scripts for host discovery or to + perform any network operation which do not depends on Nmap + targets. Scripts that run in this phase are not related to + Nmap targets, and they run only once per Nmap scan and when + the necessary script arguments are present. + + + + + Script Scanning phase + + This phase is related to Nmap host group targets, and + scripts on this phase depend and run against these targets, + and can be invoked multiple times, they are called service + and host scripts. Service scripts relate to a certain open + port (service) on the target host, and any results they + produce are included next to that port in the Nmap output + port table. Host scripts, on the other hand, run no more + than once against each target IP and produce results below + the port table. + + + + + Script Post-scanning phase + + This phase will run at the end of an Nmap scan, and can + be used to report script results and to perform statistics + gathering. Scripts in this phase run only once per Nmap + scan and when the necessary script arguments are present. + + + + + + + NSE 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 portmapper to enumerate available services. The only host script producing output in this example @@ -195,7 +234,7 @@ Nmap done: 1 IP address (1 host up) scanned in 0.33 seconds - Script scanning is normally done in combination with a port scan, + Script scanning phase is normally done in combination with a port scan, because scripts may be run or not run depending on the port states found by the scan. With the option it is possible to run a script scan without a port scan, only host @@ -886,7 +925,7 @@ local username = nmap.registry.args.user Script Format - NSE scripts consist of a handful of descriptive fields, either a portrule or a hostrule defining when the script should be executed, and an action function containing the actual script instructions. Values can be assigned to the descriptive fields just as you would assign any other Lua variables. Their names must be lowercase as shown in this section. + NSE scripts consist of a handful of descriptive fields, a rule defining when the script should be executed, and an action function containing the actual script instructions. Values can be assigned to the descriptive fields just as you would assign any other Lua variables. Their names must be lowercase as shown in this section. <literal>description</literal> Field @@ -991,35 +1030,48 @@ NSE: Script Scanning completed. - Port and Host Rules + Rules + “prerule” script variable “portrule” script variable “hostrule” script variable - rules in NSE“portrule” and “hostrule” + “postrule” script variable + rules in NSE“prerule”, “portrule”, “hostrule” and “postrule” Nmap uses the script rules to determine whether a script should be run -against a target. A script contains either a portrule -function, which governs which ports of a target the scripts may -run against, or a hostrule function, which specifies that -the script should be run only once against a target IP and only if -the given conditions are met. A rule is a Lua function that returns -either true or false. The -script action function is only performed if the rule -evaluates to true. Hostrules accept a host -table as their argument and may test, for example, the IP address or -hostname of the target. Portrules accept both host and port tables -as arguments for any TCP or UDP port in the +against a target. A script contains either a prerule +function, which lets the script to be run during the Script Pre-scanning +phase, or a portrule function, which governs which +ports of a target the scripts may run against, or a +hostrule function, which specifies that the script +should be run only once against a target IP and only if +the given conditions are met, or a postrule function, +which lets the script to be run during the Script Post-scanning phase. +A rule is a Lua function that returns either true +or false. A script can have multiple rules functions in +order to run at different script scan phases, and to share the same code. +The script action function is only performed if the rule +evaluates to true. Prerules and postrules do not accept +arguments. Hostrules accept a host table as their argument and may +test, for example, the IP address or hostname of the target. Portrules +accept both host and port tables as arguments for any TCP or UDP port in the openopen port state, open|filteredopen|filtered port state, -or unfilteredunfiltered port state port states. Port rules generally test factors such as the port number, port state, or listening service name in deciding whether to run against a port. Example rules are shown in . - +or unfilteredunfiltered port state port states. Port rules generally test factors such as the port number, port state, or listening service name in deciding whether to run against a port. Example rules are shown in . +The current standard to choose between a prerule +or a postrule is: if the script is doing host discovery +or any other network operation then the prerule +should be used. The postrule is reserved for data +reporting and statistics gathering that were generated during the scan. + + Action “action” script variable The action is the heart of an NSE script. It contains all of the -instructions to be executed when the script's portrule or hostrule +instructions to be executed when the script's prerule, portrule, hostrule or postrule triggers. It is a Lua function which accepts the same arguments as the rule and can return either nil or a string. If a string is returned by a service script, the string and script's filename are printed in the Nmap port table output. A string returned by a host script is printed below the port table. No output is produced if the script returns nil. For an example of an NSE @@ -1027,6 +1079,58 @@ action refer to . + Environment Variables + “environment” script variable + + Each script has its own set of environment variables: + + + SCRIPT_PATH + + + The script path. + + + + + + SCRIPT_NAME + + + The script name. This variable can be used in debug output. + + + + + + SCRIPT_TYPE + + + Since a script can have multiple rule functions, this + environment variable will show which rule has activated + the script, this would be useful if the script wants to + share some code between different Script Scan phases. + It will take one of these four string values: + "prerule", "hostrule", + "portrule" or + "postrule". + + + + + + This is an example of a debug code that uses the previous + environment variables, followed by the output message, from dns-zone-transfer: + + stdnse.print_debug(3, "Skipping '%s' %s, 'dnszonetransfer.server' argument is missing.", SCRIPT_NAME, SCRIPT_TYPE) + + + Initiating NSE at 15:31 + NSE: Skipping 'dns-zone-transfer' prerule, 'dnszonetransfer.server' argument is missing. + + + + Script Language @@ -1944,12 +2048,13 @@ categories = {"default", "safe"} The Rule The rule section is a Lua method which decides whether to skip - or execute the script's action method against a particular service or host. - This decision is usually based on the host and port - information passed to the rule function. In the case of the - identification script, it is slightly more complicated than - that. To decide whether to run the identification script against a - given port we need to know if there is an auth + or execute the script's action. This decision is usually based on + the type of the rule and the host and port information passed to + it. A prerule or a + postrule will always evaluate to true. In the + case of the identification script, it is slightly more complicated + than that. To decide whether to run the identification script + against a given port we need to know if there is an auth server running on the target machine. In other words, the script should be run only if the currently scanned TCP port is open and TCP port 113 is also open. For now we will rely on the fact that @@ -3226,20 +3331,26 @@ end - Scanning a Host Group + Script Scanning When NSE runs a script scan, script_scan is called - in nse_main.cc with a list of targets to scan. + in nse_main.cc. Since there are three script scan + phases, script_scan accepts two arguments, a + script scan type which can be one of these values: + SCRIPT_PRE_SCAN (Script Pre-scanning phase) or + SCRIPT_SCAN (Script scanning phase) or + SCRIPT_POST_SCAN (Script Post-scanning phase), + and a second argument which is a list of targets to scan if + the script scan phase is SCRIPT_SCAN. These targets will be passed to the nse_main.lua main function for scanning. The main function for a script scan generates a number of script - threads based on whether the hostrule or - portrule returns true for a given host and port. - The generated threads are stored in a list of runlevel lists. Each - runlevel list of threads is passed separately to the + threads based on whether the rule function + returns true. The generated threads are stored in a list of runlevel + lists. Each runlevel list of threads is passed separately to the run function. The run function is the main worker function for NSE where all the magic happens.