[GSoC] Ev2 - Easier actions interaction system for modules implemented

[mariabelenTC]

I have implemented a system to make modules actions interaction easier and smoother for users.
These are the steps needed to make sure this thing works:

• Start msfconsole
• We select a module with ACTIONS available, for example: msf5 > use auxiliary/admin/dns/dyn_dns_update
• We can check the actions available: show actions
• Now, instead of: set action UPDATE or set action DELETE and the run, we can make UPDATE or DELETE, which will automatically execute the module with the action set.

*Note that if you write UPD and press tab it will autocomplete UPDATE.

[smcintyre-r7]

Just two comments on normalizing the actions to lowercase verbs and then looking them up in a case insensitive way

[smcintyre-r7]

@msjenkins-r7 test this please.

[smcintyre-r7]

The unit tests appear to have been fixed by rerunning them, so that's good news. The code looks good, I'd just like to update the exception but I can handle that while landing.

auxiliary/admin/tftp/tftp_transfer_util looks like a good module for testing this. It offers both an "Download" and "Upload" action. Both of which are tab completing and appearing in the help output correctly.

In the following output you can tell that the action is being set correctly and then the module is running with it before within the module, it fails due to a missing setting and acknowledging the action in the error message.

msf5 auxiliary(admin/tftp/tftp_transfer_util) > show options 

Module options (auxiliary/admin/tftp/tftp_transfer_util):

   Name             Current Setting  Required  Description
   ----             ---------------  --------  -----------
   FILEDATA                          no        Data to upload in lieu of a real local file.
   FILENAME                          no        The local filename
   LHOST                             no        The local address the TFTP client should bind to
   LPORT                             no        The local port the TFTP client should listen on (default is random)
   MODE             octet            no        The TFTP mode; usual choices are netascii and octet.
   REMOTE_FILENAME                   no        The remote filename
   RHOST                             yes       The remote TFTP server
   RPORT            69               yes       The target port


Auxiliary action:

   Name    Description
   ----    -----------
   Upload  Upload FILENAME as REMOTE_FILENAME to the server.


msf5 auxiliary(admin/tftp/tftp_transfer_util) > upload 
[-] Auxiliary failed: Msf::OptionValidateError One or more options failed to validate: RHOST.
msf5 auxiliary(admin/tftp/tftp_transfer_util) > set RHOSTS 192.168.250.5
RHOSTS => 192.168.250.5
msf5 auxiliary(admin/tftp/tftp_transfer_util) > upload 
[*] Running module against 192.168.250.5

[-] Need at least a local file name or file data to upload.
[*] Auxiliary module execution completed
msf5 auxiliary(admin/tftp/tftp_transfer_util) > download
[*] Running module against 192.168.250.5

[-] Need at least a remote file name to download.
[*] Auxiliary module execution completed
msf5 auxiliary(admin/tftp/tftp_transfer_util) >

[acammack-r7]

I like the case insensitivity! The changes introduced a couple things that need to be addressed, though.

[smcintyre-r7]

The action specification to avoid datastore usage is just slightly off. I left some suggestions on how to use the keyword argument instead of modifying the datastore.

[smcintyre-r7]

The code looks great now, thanks for addressing all of our comments!

I just tested this and its working, I can tab complete and run the actions specified by admin/dns/dyn_dns_update module as commands after using it. The actions also show up as commands towards the bottom of the help output under the "Auxiliary Commands" section.

I'll get this merged in shortly, thanks for all of your work on this.

Test output

msf5 auxiliary(admin/dns/dyn_dns_update) > show options 

Module options (auxiliary/admin/dns/dyn_dns_update):

   Name      Current Setting  Required  Description
   ----      ---------------  --------  -----------
   CHOST                      no        The source address to use for queries and updates
   DOMAIN    test.lan         yes       The domain name
   HOSTNAME                   yes       The name record you want to add
   IP                         no        The IP you want to assign to the record
   RHOST     192.168.250.4    yes       The vulnerable DNS server IP address
   TYPE      A                yes       The record type you want to add. (Accepted: A, AAAA, CNAME, TXT)
   VALUE                      no        The string to be added with TXT or CNAME record


Auxiliary action:

   Name    Description
   ----    -----------
   UPDATE  Add or update a record. (default)


msf5 auxiliary(admin/dns/dyn_dns_update) > set HOSTNAME r2d2
HOSTNAME => r2d2
msf5 auxiliary(admin/dns/dyn_dns_update) > set IP 172.26.1.3
IP => 172.26.1.3
msf5 auxiliary(admin/dns/dyn_dns_update) > add

[+] Did not find an existing A record for r2d2.test.lan
[*] Sending dynamic DNS add message...
[+] The record 'r2d2.test.lan => 172.26.1.3' has been added!
[*] Auxiliary module execution completed
msf5 auxiliary(admin/dns/dyn_dns_update) > set IP 172.16.1.3
IP => 172.16.1.3
msf5 auxiliary(admin/dns/dyn_dns_update) > update

[+] Found existing A record for r2d2.test.lan
[*] Sending dynamic DNS delete message...
[+] The record 'r2d2.test.lan => 172.16.1.3' has been deleted!
[*] Sending dynamic DNS add message...
[+] The record 'r2d2.test.lan => 172.16.1.3' has been added!
[*] Auxiliary module execution completed
msf5 auxiliary(admin/dns/dyn_dns_update) > delete 

[+] Found existing A record for r2d2.test.lan
[*] Sending dynamic DNS delete message...
[+] The record 'r2d2.test.lan => 172.16.1.3' has been deleted!
[*] Auxiliary module execution completed
msf5 auxiliary(admin/dns/dyn_dns_update) > help 

Request Commands
================

    Command       Description
    -------       -----------
    request       Make a request of the specified type (https, http)


Core Commands
=============

    Command       Description
    -------       -----------
    ?             Help menu
    banner        Display an awesome metasploit banner
    cd            Change the current working directory
    color         Toggle color
    connect       Communicate with a host
    exit          Exit the console
    get           Gets the value of a context-specific variable
    getg          Gets the value of a global variable
    grep          Grep the output of another command
    help          Help menu
    history       Show command history
    load          Load a framework plugin
    quit          Exit the console
    repeat        Repeat a list of commands
    route         Route traffic through a session
    save          Saves the active datastores
    sessions      Dump session listings and display information about sessions
    set           Sets a context-specific variable to a value
    setg          Sets a global variable to a value
    sleep         Do nothing for the specified number of seconds
    spool         Write console output into a file as well the screen
    threads       View and manipulate background threads
    tips          Show a list of useful productivity tips
    unload        Unload a framework plugin
    unset         Unsets one or more context-specific variables
    unsetg        Unsets one or more global variables
    version       Show the framework and console library version numbers


Module Commands
===============

    Command       Description
    -------       -----------
    advanced      Displays advanced options for one or more modules
    back          Move back from the current context
    clearm        Clear the module stack
    info          Displays information about one or more modules
    listm         List the module stack
    loadpath      Searches for and loads modules from a path
    options       Displays global options or for one or more modules
    popm          Pops the latest module off the stack and makes it active
    previous      Sets the previously loaded module as the current module
    pushm         Pushes the active or list of modules onto the module stack
    reload_all    Reloads all modules from all defined module paths
    search        Searches module names and descriptions
    show          Displays modules of a given type, or all modules
    use           Interact with a module by name or search term/index


Job Commands
============

    Command       Description
    -------       -----------
    handler       Start a payload handler as job
    jobs          Displays and manages jobs
    kill          Kill a job
    rename_job    Rename a job


Resource Script Commands
========================

    Command       Description
    -------       -----------
    makerc        Save commands entered since start to a file
    resource      Run the commands stored in a file


Database Backend Commands
=========================

    Command           Description
    -------           -----------
    analyze           Analyze database information about a specific address or address range
    db_connect        Connect to an existing data service
    db_disconnect     Disconnect from the current data service
    db_export         Export a file containing the contents of the database
    db_import         Import a scan result file (filetype will be auto-detected)
    db_nmap           Executes nmap and records the output automatically
    db_rebuild_cache  Rebuilds the database-stored module cache (deprecated)
    db_remove         Remove the saved data service entry
    db_save           Save the current data service connection as the default to reconnect on startup
    db_status         Show the current data service status
    hosts             List all hosts in the database
    loot              List all loot in the database
    notes             List all notes in the database
    services          List all services in the database
    vulns             List all vulnerabilities in the database
    workspace         Switch between database workspaces


Credentials Backend Commands
============================

    Command       Description
    -------       -----------
    creds         List all credentials in the database


Developer Commands
==================

    Command       Description
    -------       -----------
    edit          Edit the current module or a file with the preferred editor
    irb           Open an interactive Ruby shell in the current context
    log           Display framework.log paged to the end if possible
    pry           Open the Pry debugger on the current module or Framework
    reload_lib    Reload Ruby library files from specified paths


Auxiliary Commands
==================

    Command       Description
    -------       -----------
    add           Add a new record. Fail if it already exists.
    check         Check to see if a target is vulnerable
    delete        Delete an existing record.
    exploit       This is an alias for the run command
    rcheck        Reloads the module and checks if the target is vulnerable
    recheck       This is an alias for the rcheck command
    reload        Reloads the auxiliary module
    rerun         Reloads and launches the auxiliary module
    rexploit      This is an alias for the rerun command
    run           Launches the auxiliary module
    update        Add or update a record. (default)


msfconsole
==========

`msfconsole` is the primary interface to Metasploit Framework. There is quite a
lot that needs go here, please be patient and keep an eye on this space!

Building ranges and lists
-------------------------

Many commands and options that take a list of things can use ranges to avoid
having to manually list each desired thing. All ranges are inclusive.

### Ranges of IDs

Commands that take a list of IDs can use ranges to help. Individual IDs must be
separated by a `,` (no space allowed) and ranges can be expressed with either
`-` or `..`.

### Ranges of IPs

There are several ways to specify ranges of IP addresses that can be mixed
together. The first way is a list of IPs separated by just a ` ` (ASCII space),
with an optional `,`. The next way is two complete IP addresses in the form of
`BEGINNING_ADDRESS-END_ADDRESS` like `127.0.1.44-127.0.2.33`. CIDR
specifications may also be used, however the whole address must be given to
Metasploit like `127.0.0.0/8` and not `127/8`, contrary to the RFC.
Additionally, a netmask can be used in conjunction with a domain name to
dynamically resolve which block to target. All these methods work for both IPv4
and IPv6 addresses. IPv4 addresses can also be specified with special octet
ranges from the [NMAP target
specification](https://nmap.org/book/man-target-specification.html)

### Examples

Terminate the first sessions:

    sessions -k 1

Stop some extra running jobs:

    jobs -k 2-6,7,8,11..15

Check a set of IP addresses:

    check 127.168.0.0/16, 127.0.0-2.1-4,15 127.0.0.255

Target a set of IPv6 hosts:

    set RHOSTS fe80::3990:0000/110, ::1-::f0f0

Target a block from a resolved domain name:

    set RHOSTS www.example.test/24
msf5 auxiliary(admin/dns/dyn_dns_update) >

[smcintyre-r7]

Release Notes

Improvement for auxiliary modules which expose actions, allowing invocation of those exposed actions by the user as commands when the user has changed context into the module through the use command within msfconsole.