Re: NSE console script help

[Martin Holst Swende <martin () swende se>]

On 01/19/2011 03:24 AM, Fyodor wrote:
> On Tue, Jan 18, 2011 at 08:27:10PM +0100, Martin Holst Swende wrote:
> > If I use: "nmap foobar.com --script=all --script-args=help", lets
> > say nmap discovers the for me totally unknown service
> > "gazonk". Perhaps there is a very uncommon script which is a bit
> > intrusive, and not default, written specifically for the gazonk
> > service.  The chances of me finding that script are small, normally,
> > but since the command above will print only[1] the help about that
> > particular script, I will have a higher chance of finding the right
> > script for the task.
> Well, the way I see it, there are four main script help selection
> possibilities:
>
> 1) Print the script help info for all scripts known by Nmap
> 2) Print the info for all scripts selected (by a specifier, like
>    "default" or "safe" or "broadcast" or "asn-query" or whatever).  In
>    this case, you can get behavior #1 by specifying "all".
> 3) Print just the scripts which pass their rule (portrule, hostrule,
>    prerule, or postrule) and thus would be (or are) actually run by Nmap.
I think this is valueable, since this can be a way for users to learn about
new scripts when they are relevant.

> 4) Print just the help for the scripts which actually produced output.
>    That way users don't end up with output from scripts they don't
>    really understand.
>
> Speaking of #4, maybe our nmap.xsl converter should link link the
> script name in script output directly to
> http://nmap.org/nsedoc/scripts/[script_name].html.
>
> Now which of these four selection possibilities are most important,
> and what sort of API we should use to provide them, is a tougher
> question.
>
> One question is how much work you want Nmap to do when you ask for
> help.  With #1 and #2, you could either print the information
> immediately and then stop, or you could let the scan continue.  The
> advantage of stopping is that it lets people see their script options
> before committing to running them.  I suppose the advantages of
> continuing are that it puts the information there in the Nmap report
> along with the results (avoids running Nmap twice), and (more
> importantly) might be more consistent if we also offer #3 and #4.
>
> For #3, Nmap needs to do its port scanning, OS detection, version
> detection, and run at least the script portrules.  For #4, Nmap needs
> to completely execute.  So if we want to support these, it pretty much
> dictates an interface which runs the scan AND produces help.
>
> There is also the issue of interface ease of use.  To support only #1,
> we just need a new Nmap option without requiring any options.  "nmap
> --script-help" would do the trick.  We'd probably just print the help
> and not do a scan.
>
> To support only #2, we would either have to take a script specifier
> like "default" for --script-help, or we'd have to require that the
> user also pass an existing scripting option like --script, -A, or -sC.
> We would have the option of doing an actual script scan, or just
> printing the help.
>
> To support only #3 or #4, we'd need a new option like --script-help
> and it would have to pair with existing scripting options like
> --script, -A, or -sC.  And we would have to do the actual scanning too
> (possibly just to the point of rule evaluation for #3).
It is conceivable that this could also be 'shortcutted', so that  the
user specifies service/port from the
command line. Something like:
nmap -p80,8080 --script=all --script-help service='http'
==> nmap 'pretends' to have found open port 80,8080 and 'http'

Anyway, I think that a help system should encompass #1, #2 and #3. I
don't personally
see any real point in #4 (I seldom run a script I don't know anything
about, and if I do, and it produces output,
that output usually speaks for itself)

> We could support multiple stages #1 through #4, but that also
> increases complexity.
As you pointed out, #2 gives #1 pretty easily, and I think #3 could give
#2 pretty easily also. But that depends on how it is implemented.
#4 really implies two things:
1) Help-output will wait until all scripts are finished
2) No help will be available unless you actually execute scripts (which
is a bit backwards in case I want help about a potentially disruptive
script)

> It is worth noting that each one is a superset of the higher-numbered
> options.  So #2 contains all the scripts (and possibly more) in #3,
> and so on.
>
> Cheers,
> Fyodor
> _______________________________________________
> Sent through the nmap-dev mailing list
> http://cgi.insecure.org/mailman/listinfo/nmap-dev
> Archived at http://seclists.org/nmap-dev/

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