Re: Script selection - Gsoc

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

I thought a bit more about argument handling, and instead of just
throwing ideas around, I implemented something a bit more concrete to
show what I mean. I picked a script which uses arguments, it happened to
be dns-zonetransfer.nse.

To that script, I added the function :

script_args = function()
    return     {name="dnszonetransfer.domain", desc="Domain to transfer"},
            {name="domain", desc="Fallback domain to transfer if
dnszonetransfer.domain is not set"}
end

And modified the action function by basically just removing a call to
nmap.registry as thus :

action_ = function(host, port, args)
    local soc, status, data
    local catch = function() soc:close() end
    local try = nmap.new_try(catch)
   
    local domain = nil
   
    if args.dnszonetransfer and args.dnszonetransfer.domain then
        domain = args.dnszonetransfer.domain
    elseif args['dnszonetransfer.domain'] then
        domain = args['dnszonetransfer.domain']
...

As you can see, the action is now called action_ . This is because I did
not want to dive into nse_main.lua, but instead simulated the framework
by wrapping the original action in another function (which is called
action). So, something like this could be used by the framework to both
determine what arguments are used and provide help to the end-user about
them:


-- Displays information about what arguments a script is using
show_args = function()
    local my_args= {script_args()}
    local used_args,_ = {}
    print ("Script arguments:")
    for _,arg in ipairs(my_args) do
        local optional = arg.optional
        local defaultValue = arg.default or "None"
        local desc = arg.desc
        local name = arg.name
        output = ("    '%s' - %s"):format(name, desc)
        if defaultValue ~= nil then
            output = output ..  (" (default:%s)"):format(defaultValue)
        end
        if optional == false then
            output = output ..  (" required"):format(defaultValue)
        end
        print(output)
    end
   
end

action = function(host, port)
    -- Get scripts arguments
    local my_args= {script_args()}
    local used_args,_ = {}
    for _,arg in ipairs(my_args) do
        local v = nmap.registry.args[arg.name]
        if v == nil then
            v = arg.default
        end
        used_args[arg.name] = v
        -- Is required parameter missing ?
        if v == nil and arg.optional ~= true then
            stdnse.print_debug(("Required parameter %s not
set"):format(arg.name))
            show_args()
            return false
        end
    end
    -- Parameters set, call action
    action_(host, port, used_args)
end

 
When I run this, this is what I get :
martin@linovox:~/workspace/nsescripts$ nmap --script
dns-zonetransfer2.nse --script-args help=true -p 53 ns3.zoneedit.com -PN

Starting Nmap 5.21 ( http://nmap.org ) at 2010-04-01 20:54 CEST
Script arguments:
    'dnszonetransfer.domain' - Domain to transfer (default:None)
    'domain' - Fallback domain to transfer if dnszonetransfer.domain is
not set (default:None)
NSE: Script Scanning completed.
Nmap scan report for ns3.zoneedit.com (76.74.236.21)
Host is up (0.18s latency).
PORT   STATE SERVICE
53/tcp open  domain

Nmap done: 1 IP address (1 host up) scanned in 0.29 seconds

If I modify so that e.g dnszonetransfer.domain is mandatory
(optional=false), this is what I get trying to run it without the
argument :

Initiating NSE at 20:56
NSE: NSE Script Threads (1) running:
NSE: Starting dns-zonetransfer2 against 76.74.236.21:53.
NSE: Required parameter dnszonetransfer.domain not set
Script arguments:
    'dnszonetransfer.domain' - Domain to transfer (default:None) required
    'domain' - Fallback domain to transfer if dnszonetransfer.domain is
not set (default:None)
NSE: Finished dns-zonetransfer2 against 76.74.236.21:53.
Completed NSE at 20:56, 0.00s elapsed
NSE: Script Scanning completed.
Nmap scan report for ns3.zoneedit.com (76.74.236.21)
Host is up, received user-set (0.18s latency).
Scanned at 2010-04-01 20:56:23 CEST for 0s
PORT   STATE SERVICE REASON
53/tcp open  domain  syn-ack
Final times for host: srtt: 182578 rttvar: 182578  to: 912890

Read from /usr/local/share/nmap: nmap-services.
Nmap done: 1 IP address (1 host up) scanned in 0.30 seconds
martin@linovox:~/workspace/nsescripts$


> From my view, it seems like a great benefit to have info about arguments
as lua-code instead of relying on parsing tags from a bunch of files.
The only drawback as I see it is that all scripts with comments need to
be modified - but probably only very minor, but please correct me if I
am wrong. Comments?
Regards,
/Martin







Martin Holst Swende wrote:
> Just a minor suggestion, if there is going to be work done on script
> arguments, wouldn't it be better to try and fix a generic
> argument-handling mechanism, so that arguments could be accessed by way
> of introspection?
> Something like :
>
> args=[foo:"Optional foozing parameter",bar:"If you want  a bar-scan"]
>
> function action(host , port, args)
>     foo, bar = unpack(args)
>     ...
>
> That way, the engine (or any other library) could read what parameters
> are used. It seems to me that some solution like this would be better in
> the long run, not least since documentation which is tied that hard to
> the actual code will by definition always be up to date.  But perhaps I
> am missing something ?
>
> Just my 2 cents...
> /Martin
>
>
> Ron wrote:
>   
> > Hey,
> >
> > I don't think you have to worry too much about arguments that the developer didn't document in the @args fields. At 
> > the very most, I'd print a warning of some sort but nothing else. Typically, if there are undocumented arguments, 
> > you might not want to advertise them -- they may be pure debugging or something similar. That is, of course, only my 
> > opinion. 
> >
> > One thing to watch out for, though, is requirements. smb-brute.nse, for example, includes unpwdb.lua, which has its 
> > own set of (very important!) arguments. So following the tree of requirements is important. 
> >
> > Ron
> >
> >
> > On Wed, 31 Mar 2010 23:34:46 +0530 kirubakaran S
> > <kirubakaran1989 () gmail com> wrote:
> >   
> >     
> > > Hi dev,
> > >     I am working great on thinking about script selection
> > > interface for Gsoc.  I deduced every script have two type
> > > of arguments. One is direct argument which is accessed through
> > > the nmap.registry.** - lua table.Another argument is variables in
> > > library functions which have default values and it can be changed.
> > > To design interface I should know what are all the arguments for a
> > > particular script, In this case I can parse @args field in script to
> > > know which are all essential arguments. But when script developers
> > > forget @args field or if the script uses argument of library
> > > variables we cannot enumerate
> > >  what are all library variable arguments for this script. Because
> > > script developers do not include @args field for arguments of library
> > > variables.
> > >
> > > Example : In pgsqlbrute.nse arguments are
> > > 1. pgsql.version
> > > 2. pgsql.nossl     ----> type one
> > > 3. passdb, unpwdb.passlimit, unpwdb.timelimit, unpwdb.userlimit,
> > > userdb
> > >      --> type 2 library variables.
> > > But script only provides these lines
> > > --@args pgsql.nossl If set to 1 or true disables SSL.
> > > --@args pgsql.version Force protocol version 2 or 3
> > >    while designing interface if I conclude arguments by parsing @
> > > args I miss the type2 arguments and user cannot change it!!
> > >
> > >
> > >   To solve this problem , like script.db which stores categories of
> > > script. store the names of arguments in script_arguments.db file.
> > > And conclude the arguments by searching this file.will this solution
> > > for finding out arguments for particular script work out? or can
> > > anyone suggest me what is the best way to find out all arguments
> > > for script. correct me If I am wrong..
> > >
> > > Thanks.
> > >
> > >
> > > -- 
> > > Kirubakaran.S
> > > _______________________________________________
> > > 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/
>   

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