diff --git a/docs/scripting.xml b/docs/scripting.xml index 11b10be92..108d9f0dc 100644 --- a/docs/scripting.xml +++ b/docs/scripting.xml @@ -234,7 +234,7 @@ Nmap done: 1 IP address (1 host up) scanned in 0.33 seconds - Script scanning phase is normally done in combination with a port scan, + Script scanning 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 @@ -925,7 +925,7 @@ local username = nmap.registry.args.user Script Format - 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. + 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 @@ -1037,32 +1037,53 @@ NSE: Script Scanning completed. “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 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 . -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. + Nmap uses the script rules to determine whether a script should be + run against a target. 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. + + + A script must contain one or more of the following functions that + determine when the script will be run: + + prerule() + hostrule(host) + portrule(host, port) + postrule() + + prerule scripts run once, before any hosts are + scanned, during the script pre-scanning + phase.script + pre-scanning hostrule and + portrule scripts run after each batch of hosts + is scanned. postrule scripts run once after all + hosts have been scanned, in the script post-scanning + phase.script post-scanning + phase A script may run in more than one + phase if it has several rules. + + + prerule and postrule do not + accept arguments. hostrule accepts a host table + and may test, for example, the IP address or hostname of the + target. portrule accepts both a host table and + a port table for any 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 . + + + The current standard to choose between a + prerule or a postrule is + this: if the script is doing host discovery or any other network + operation then the prerule should be used. + postrule is reserved for reporting of data and + statistics that were gathered during the scan.