[framework] Auxiliary Module Questions

[mmiller at hick.org]

On Tue, Apr 17, 2007 at 05:48:50PM +0000, Kashif Iftikhar wrote:
> Hello,
> 
>  I am trying to put together an HTTP PUT/GET auxiliary module. I have
> a few questions regarding the working of auxiliary modules.
> 
> 1. What is the difference between auxiliary actions (of class
> AuxiliaryAction) and auxiliary commands? Looking at the source code,
> the auxiliary_commands accessor function returns an empty dictionary (
> { } ). Does this mean that auxiliary commands have not yet been
> implemented?

Auxiliary commands allow you to add custom commands to the console
interface.  For example, there are builtin commands like 'exploit' and
'check' for exploit modules.  Auxiliary modules by default all have the
'run' command.  You can add additional commands through the
auxiliary_commands method.  Take a look at admin/backupexec/registry.rb
for an example.  These additional commands are only applicable to the
one specific auxiliary module that defines them.

> 2. Regarding auxiliary actions, I was able to add auxiliary actions by
> passing either
> 
>  'Actions'        => [AuxiliaryAction.new('PUT_FILE', {}),
>                                 AuxiliaryAction.new('DELETE_FILE', {})],
> 
>    OR
> 
>  'Actions'     =>
> 				[ ['My Aux action'] ],
> 
>  Looking at the constructor of AuxiliaryAction class, there is also
> an options dictionary/hash named opts that can be passed. For the time
> being I am passing it empty. What keys/values can come into opts? How
> do I add description for an action.

This hash is to let you have dynamic variables associated with your
actions.  These only have meaning within your auxiliary module, and
aren't displayed to end-users.  For example, if you look at exploit
modules, the Targets information hash element has a name and a hash of
options.  The concept is the same with auxiliary modules.

>  doing 'show actions' in msfconsole just displays the action name
> without any description. I tried adding a 'Description' key to the
> opts passed to AuxiliaryAction class but it had no effect.

There isn't a way at the moment to provide a description with actions.
We could look into doing this by standardizing on some hash element keys
such as 'Description'.

> 3. How does an action become passive? Do I just include it in the
> PassiveActions list/array and it automatically gets to run as passive
> or are there other requirements?

Yep, I believe this is all you need to do.

> 4. Is there a way to monitor the status/progress of auxiliary scanner
> modules? Can this progress be monitored from the database without
> calling msfcli or msfconsole etc?

You should be able to select from various tables, but I don't think
there is a way to figure out "percentage" complete, for example.

> 5. The auxiliary scanner modules provide three ways (scan host, scan
> range and scan batch) to do a scan. Exploring the source code, I was
> able to figure out these:
> 
>  * To scan a host the module should implement the run_host() method.
>  * To scan a range, the run_range method should be implemented.
>  * To scan a batch, the run_batch() method and also a batch_size
> accessor function should be implemented.
> 
>  My question is from where does the run_host(ip) method gets the IP,
> the run_range(range) method gets the range and the run_batch(batch)
> method gets the batch? How can a user specify a range or a batch using
> msfconsole?

If I recall correctly, ranges are specified by setting RHOSTS to
something like 10.0.0.0/8 or some other network address form.

>  I am planning to write a tutorial on auxiliary modules developments
> and on some useful mixins like HttpClient, any other tips suggestions
> will also be greatly appreciated.

Great!  We look forward to seeing it.  Feel free to send more questions
to the list as you have them.