Skip to content

Add ModuleExecution and related data models#228

Open
cdelafuente-r7 wants to merge 4 commits into
rapid7:masterfrom
cdelafuente-r7:module-execution-data-models
Open

Add ModuleExecution and related data models#228
cdelafuente-r7 wants to merge 4 commits into
rapid7:masterfrom
cdelafuente-r7:module-execution-data-models

Conversation

@cdelafuente-r7

@cdelafuente-r7 cdelafuente-r7 commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

This adds ModuleExecution, ModuleExecutionError and ModuleExecutionEvent data models as part of the reporting refactor in Metasploit Framework.

Testing can be done following the testing steps in rapid7/metasploit-framework#21576.

@cdelafuente-r7 cdelafuente-r7 force-pushed the module-execution-data-models branch from fd6f050 to a091880 Compare June 16, 2026 16:19
@cdelafuente-r7 cdelafuente-r7 marked this pull request as ready for review June 16, 2026 16:19
Comment thread app/models/mdm/module_execution.rb Outdated
Comment on lines +23 to +25
# Terminal lifecycle states. `running` is the only non-terminal value
# and is permitted while {#ended_at} is `NULL`.
TERMINAL_STATUSES = %w[running success neutral expected_failure unhandled_exception].freeze

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If unhandled_exception is the inverse of expected_failure, it might be more intuitive to track it as unexpected_failure.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me give more details about these status:

  • expected_failure: the module explicitly declared failure via fail_with. It is an error the module author has anticipated with a proper failure_reason.
  • unhandled_exception: a Ruby exception that escaped the module's rescue chain (NoMethodError, Rex::ConnectionError outside a rescue, etc.). The author did not anticipate this; there's an exception_class and backtrace.

So, unhandled_exception and expected_failure aren't strict inverses. For example, unhandled_exception will help answer question like "which modules are buggy?"

Comment thread app/models/mdm/module_execution.rb Outdated
MODULE_TYPES = %w[exploit auxiliary post payload encoder evasion nop external].freeze

# User interface or programmatic surface that initiated this execution.
ORIGINATING_UIS = %w[console rpc json_rpc mcp external import plugin autocheck].freeze

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ORIGINATING_UIS = %w[console rpc json_rpc mcp external import plugin autocheck].freeze
ORIGINATORS = %w[console rpc json_rpc mcp external import plugin autocheck module].freeze

I'd suggest adding 'module' as an originator to account for modules running other modules. Additionally since some of these aren't exactly user-interfaces, it may be better to use a slightly more generic name like ORIGINATORS vs ORIGINATING_UIS.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right it's not accurate. I would prefer using ORIGINATING_INTERFACES, which is more programmatic. ORIGINATORS sounds like a user, which seems slighly wrong with things like autocheck. I'm also fine if you disagree, I'll change it to ORIGINATORS, no problem.

Comment thread app/models/mdm/module_execution_event.rb Outdated
Comment thread app/models/mdm/module_execution_error.rb Outdated
@bwatters-r7 bwatters-r7 moved this from Ready to Todo in Metasploit Kanban Jul 13, 2026
@cdelafuente-r7 cdelafuente-r7 marked this pull request as draft July 13, 2026 17:08
@cdelafuente-r7 cdelafuente-r7 marked this pull request as ready for review July 16, 2026 13:22
@cdelafuente-r7 cdelafuente-r7 force-pushed the module-execution-data-models branch from 24e0185 to f0acdb1 Compare July 16, 2026 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

3 participants