RFC: Improved module category definition

[jmartin-tech]

Problem:

Since modules are the primary entrypoint to expanding Metasploit Framework contributors are starting to offer utilities as modules. Some of these utilities to do not fit the standard categories of exploit/post/auxiliary/payload/evasion.

Many of these modules end up defined as auxiliary/scanner or exploit when in fact they do not necessarily scan or exploit a vulnerability. Moreover these module tend to simply exercise intended function in services that provide access to execute code. In many cases the reasoning to decide where these modules will be placed is based on what is to be executed, or to be more precise, built in handler support.

Some known modules that meet this utility:

auxiliary/scanner/ssh/ssh_login
auxiliary/scanner/ssh/ssh_login_pubkey
exploit/linux/local/su_login
exploit/windows/smb/psexec
exploit/windows/smb/webexec
exploit/windows/local/current_user_psexec
exploit/windows/local/wmi
post/multi/manage/sudo

One concerning issue with the current location for these module is the misnomer that many are preforming an exploit. While many longer term users may consider this a detail they can simply gloss over when generating a report based on actions taken with Metasploit Framework, a less savvy stakeholder sent only a report that did includes details of these actions may be confused or even mislead by a finding and focus resources inefficiently.

Potential solutions:

Define module classification more clearly

• Reserve the exploit path for modules to things that take advantage of an exploit
• Make handler inclusion simpler
  refactoring handler support to be a single library import
• Add a new top level category such as utility modules or second level category such as auxiliary/utility & post/utility

[smcintyre-r7]

I'd be in favor of moving "exploit" modules such as those in your example list into auxiliary/utility for a few reasons. As I understand it, "auxiliary" modules have always been the everything else category. The line between scanner and exploit is a bit blurry now as it is since exploits have first-class support for RHOSTS. Using auxiliary/utility would also eliminate the need to add a new module type, which would be ideal unless there's a strong distinction between auxiliary and utility like "utilities get a shell without exploiting a vulnerability".

In 2020 we saw some modules that exploited vulnerabilities that didn't necessarily yield a shell (see SAP's RECON and Zerologon). From a technical perspective, if we go this path we should ensure that all module types have easy access to the same session handler capabilities that the current exploit modules have.

In regards to the login modules that are under the auxiliary/scanner tree, I typically hear people refer to the process as "scanning" when they're checking networks for where credentials are valid that they've obtained through some means. Since those modules also take multiple target systems, I think it makes sense to continue classifying them as scanners even though they're not scanning for a vulnerability per se.

[bwatters-r7]

I like this in theory, but in practice, I find the definition of an exploit vulnerability is far stickier than it appears at first. One person's definition of exploit is likely not another's when we dig deeply enough. I think one of the thorniest would be something like a DLL injection attack: DLL injection could be due to a coding mistake, an inherent file/registry permissions mistake, an installation mistake, a devops mistake, or even a common user error (picture a well-used how-to that contains an errant step for setting permissions). In that case, I can see something like a DLL injection landing pretty much anywhere in this spectrum, with the vendor's behavior being the deciding factor. Does a DLL injection need a CVE to be an exploit? Some have CVEs, some don't. Does it need to be patched? Some are, some are not. I may be assigning outsized power to Metasploit, but I'm curious if this would result in vendors being less likely to attach CVEs to exploits if doing so was a determining factor for how we categorized them.
Scanners that rely on timing attacks are utilizing a vulnerability, but are very much still scanners. Loading a dll is standard, but being able to write to the location may be a vulnerability, generally depending on the whim of the vendor; the same thing for service path overwrites.
I absolutely understand the logic in wanting to give a cleaner definition for exploit but I'm worried the replacement will be less transparent and far more arbitrary; in many cases this strikes me as a "I know an exploit when I see it" methodology that will result in a spectacular thread of bikeshedding in our PRs.
Admittedly, I'm no fan of the sort of odd definition we've established, but from a clear-cut categorization, where things should land is super clear and can be done with a super easy (and frankly, programmatic definition)- If it needs a handler, it is an exploit, if it does not need a handler, but does need a session, it is a post module. If it needs neither a handler or a session, it goes in aux. The exception I can think of immediately is the one you brought up- login scanners. I've always assumed that login scanners were dumped in aux back in the day because we did not support RHOSTS in exploits and the Metasploit legends of old wanted the RHOSTS feature for login scanner modules. It is funny, but unlike @smcintyre-r7, I'd be OK migrating the login scanners to the exploit side, as it feels like they should have always been there.
A second consideration is when someone has local access to a [type] computer, I can imagine them wanting to type use exploit/[type]/local and then tab to view the possible ways to elevate a session, or use post/[type] tab to see what tools are available when they have a session. I absolutely get some of the modules do not fall neatly into these categories, but pulling exploits and post modules that are 'different' and dumping them into aux so that customers have to explore a third option and manually parse behavior seems suboptimal.
In many cases, I'm seeing this as a dichotomy for favoring clarity to users vs clarity to consumers, and both are super important, so I absolutely appreciate where this desire comes from, but to be blunt, I feel like the difference between module types should be so straightforward we could write a Rubocop rule for it.

[jmartin-tech]

I agree that the examples for DLL injection meet the exploit idea, and in the end I am not sure it conflicts with the original problem statement.

something like a DLL injection attack: DLL injection could be due to a coding mistake, an inherent file/registry permissions mistake, an installation mistake, a devops mistake, or even a common user error (picture a well-used how-to that contains an errant step for setting permissions).

The example modules in exploit or even post however are not mistakes or even mis-configuration they are intended utility.

[cdelafuente-r7]

This is a complex problem and I think this discussion will come back over and over. I'm in favor of these proposed changes, but I'm sure there will be new modules that won't fit in any category, again. Maybe it is time to rethink the whole category concept to be more flexible.

I was thinking of a flat model, based on tags for category, with capabilities added to each module according to its needs. This should be more granular than just Exploit or Scanner and allow any kind of combinations. Think of a module that needs a Session using Ssh but creates another session and also needs a Handler. And let's say this module has the capability to Scan a network through the new created session. Maybe we should take advantage of the mixin mechanism and bring default tags into the module metadata, along with the needed helpers/utilities. For example:

• auxiliary/scanner/ssh/ssh_login: this module could add both a Scanner and a Ssh mixins, which automatically add the scanner and ssh tags, along with the corresponding helpers.
• exploit/windows/smb/psexec: with the Handler and Remote mixins, that would bring the corresponding tags to the module, along with the helpers needed.

Additional custom tags could still be specified in the module metadata (info hash), and used for search purposes.

This might not be the best way to do it, but I think a more flexible model that won't require moving modules around in modules/ directory would be preferred.

[jmartin-tech]

A novel approach, I like the idea of functionality needs defining tags. From a strictly search perspective this sounds flexible.

Given that primary module interaction is with the CLI how would tab completions be supported?
Should every tag be a possible tab completion that performs a search result for that tag and offers modules or other combinable tags? For example:

• scanner/ssh/ssh_login or ssh/scanner/ssh_login would both be valid completions

From a user interaction perspective the completions sound reasonable. Leading to a few more questions.

• Does it lend to a canonical way of naming modules?
• What would the base tags be for a module that uses no mixins? Would the author need to define some tags?
• Can completions be implemented in a performant way within Framework's tab completion capabilities?
• How maintainable is this pattern as it scales?

Are these directions Framework wants to explore?