Re: [NSE] New class of scripts -- New Rule proposal

[Daniel Miller <bonsaiviking () gmail com>]

A way to get around the decision of whether/when to use the netscript's 
discoveries to automatically add targets, a new -iC option could be 
added (in the spirit of -iL, -iR), meaning "get targets from 
netscripts". This avoids surprising someone who was not expecting to 
scan those new targets, and also allows one to use the same script to 
simply discover a list of hosts without scanning them.

A contrived example: I want to perform a dns zone transfer, 
smb-enum-sessions, and a "showmount -a"-type script to generate a list 
of targets from just a couple known targets. I know that the UNIX hosts 
are in one subnet, and the Windows hosts in another. If I don't care 
about running a full scan against all hosts, I use the -iC option with 
--script="names-of-scripts". If I want to limit my exposure to detection 
by an IDS or a host firewall, I can use the same command line, but 
without -iC to get the list of targets. Then I can sort them by subnet, 
and then just scan -p135,139,445,3389 for Windows and -p21,22,23,111 for 
UNIX.

Dan

On 06/24/2010 03:02 PM, Djalal Harouni wrote:
> NSE proposal: New rule "netrule"
>
> Introduction:
> -------------
> In this proposal we will try to introduce a new rule "netrule" which can
> be used by a new class of NSE scripts.
>
> The current NSE rules are:
> o hostrule: specifies that the script should only run once against the
> host IP.
> o portrule: specifies that the script should only run against the ports
> list of the current target.
>
> The limitation of these rules is that the scripts will run only against
> a single host IP (hostrule or portrule), and this host is provided by
> Nmap which has already done a bunch of operations to get this information,
> so as an example, we can't run scripts against other targets which can be
> networks or domain names that do not depend on Nmap previous operations.
> * Network targets can be useful for host discovery and broadcast operations.
> * Domain name targets can be useful to do DNS brute force operations.
> Another limitation is that since NSE scripts depend on host and port
> tables information they must run after Nmap scan phases.
>
> A simple example:
> * Script: dns-zone-transfer.nse
> * Portrule: portrule = shortport.portnumber(53, 'tcp')
> Modify the dns-zone-transfer.nse script and add another rule to let the
> script run against the domain name to discover new targets. The current
> script will only run when Nmap finds a DNS server, so with a new added
> rule that script will run directly and does not depend on open ports and
> can find new subdomain targets for Nmap, in other words specify a domain
> name as a target and with the use of the results of this script, Nmap
> will scan all the newly discovered subdomains and hostnames.
>
>
> Please note that this is a first proposal about a new rule. There will
> be other proposals to complete the New scripts class definition.
>
>
> More NSE Rules Background:
> --------------------------
> At present there are only two types of scripts, host and port classes
> scripts. Each script has its own rule and action.
>
> o The action function is the heart of an NSE script [1].
> o The rule is the Lua function which will be evaluated by NSE to true or
>    false.
>
> The script's action will only be executed if its rule evalutes to true.
>
> NSE Rules:
> o Host rule:
> "Specifies that the script should be run only once against a target
> IP and only if the given conditions are met." [1]
> The Host rule accepts a host table which contains the IP or Hostname of
> the target as an argument.
>
> o Port rule:
> "Governs which ports of a target the scripts may run against" [1].
> The Port rule accepts both host and port tables as arguments or any TCP
> or UDP port in the open, open|filtered, or unfiltered port states [1].
>
>
> Motivation:
> -----------
> 1. Network operations:
> We can need scripts that perform different network operations in order
> to discover more hosts. In general these scripts will run once per scan
> and can feed Nmap with new targets, but we can have other use cases.
>
>   o Use broadcast and multicast protocols as suggested in this thread
>     http://seclists.org/nmap-dev/2010/q1/883
>
>   o We can also use AS entries to get IPs as suggested in this thread
>     http://seclists.org/nmap-dev/2010/q2/101
>
>   o Perform DNS discovery: brute force, zone transfert etc.
>
>   o Perform Whois requests.
>
>   o Any other operation which can take a network or a simple input that
>   can be used to produce a list of Nmap targets.
>
>
> New NSE Net scripts details:
> ----------------------------
> In order to introduce the new class of scripts we need to define a new
> rule and its use.
>
> o The new rule of the scripts will be named: "netrule"
>
> o The new scripts will be identified by the presence of the netrule.
>
> o The scripts will run when the new --script-netscan Nmap option is
> specified and when the netrule function evaluates to true, like the
> version scan scripts which depend on the -sV option.
>
> o Each script can have its own arguments like any other script.
>    e.g: netscript.arg1=x, netscript.arg2=x ...
>
>
> We can also have different new scripts which can run multiple times:
> o Before any scanning.
> o Before hostgroup NSE scan.
> o After hostgroup NSE scan.
> o After scanning all hostgroups.
>
>
> Net table:
> ----------
> Information passed to the new net scripts is in the net lua table.
>
> o net -- This table is passed as a parameter to the rule and action
> functions.
>
> o net.command_line_targets -- The targets specified on the command line
> (including -iR and -iL).
>
> o net.excluded_targets -- The targets specified to be excluded via
> --exclude and --excludefile.
>
> o net.targets -- The "effective" targets. This should be the
> net.command_line_targets - net.excluded_targets.
>
> o net.interface -- like the host.interface.
>
> o net.mac_addr_src -- like the host.mac_addr_src.
>
> o net.bin_ip_src -- like the host.bin_ip_src.
>
>
> Additions:
> The net.targets field can be ignored by these scripts, of course there
> are other net scripts that depend on Nmap targets to work.
> e.g: script which does broadcast stuff on a network target needs this
> field which is the specified net. After that the script can parse the
> netblock etc.
> another e.g: use AS entries to get IPs, in this case the script can
> ignore the cmdline target in other words ignore this field, and use the
> --script-args for its input.
>
>
> Netrule:
> --------
> o The netrule will run when the new --script-netscan Nmap option is
> specified.
>
> o The netrule will facilitate the addition of the new host discovery and
> scanning scripts.
>
>
> Since we can have different scripts which can run at different times or
> multiple times as stated in the [New NSE Net scripts details] section,
> the imprortant question will be: When should the scripts run ?
> For this we can propose:
>
> o A new string argument like "before_scan" and "after_scan" to be passed
> and evaluated in the netrule function of each script.
>
> o Another solution will be to propose different netrule funtions:
>   * netrule_before_scan() -- run the script before any Nmap scan.
>
>   * netrule_before_nse_hostgroup() -- run the script before NSE hostgroup
>   scan phase.
>
>   * netrule_after_nse_hostgroup() -- run the script after NSE hostgroup
>   scan phase.
>
>   * netrule_after_scan() -- run the script after scanning all groups.
>
>
> Simple implementation example:
> ------------------------------
>
> -- run the script before Nmap scans
> netrule = shortport.netrule_check("before_scan")
>
> action = function(net)
>
>         -- command line targets
>         for _,v in ipairs(net.command_line_targets) do
>                 stdnse.print_debug("%s", v)
>         end
>
>         -- excluded targets
>         for _,v in ipairs(net.excluded_targets) do
>                 stdnse.print_debug("%s", v)
>         end
>
>         -- effective targets
>         for _,v in ipairs(net.targets) do
>                 stdnse.print_debug("%s", v)
>         end
>
>         stdnse.print_debug("IP Source: %s", packet.toip(host.bin_ip_src))
>
>         return
> end
>
>
> Conclusion:
> -----------
> The addition of these new netrules will let the scripts take
> different targets not only Nmap IP hosts or port lists, and will offer
> them a way to run before or after Nmap scan phases.
>
> This idea about a new class of scripts was first brought by Ron [2].
> Thx Patrick for your feedbacks.
>
>
> [1] http://nmap.org/book/nse-script-format.html
> [2] http://seclists.org/nmap-dev/2010/q1/883
>
>    

_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://seclists.org/nmap-dev/