MCP server support for "dangerous" actions & new tools by cdelafuente-r7 · Pull Request #21632 · rapid7/metasploit-framework

cdelafuente-r7 · 2026-07-01T16:27:30Z

Description

This adds three related features to the MCP server:

Complete job tracking across every module type for module execution as job via RPC: Exploit, Auxiliary, Post and Evasion modules now return a (run_uuid, job_id) pair from module.execute, which can be polled via module.results. This is invisible to msfconsole users but is a prerequisite for the new MCP tools.
Eight new MCP tools: that wrap the existing RPC endpoints for module and session control, backed by strict per-tool input validation.
A "dangerous actions" opt-in gate: Four of the eight tools can perform destructive operations. They now fail closed unless the operator explicitly enables them through one of three well-known paths (CLI flag, env var, or config file), with clearly documented precedence.

The eight new tools

Tool	RPC backing	Class	Annotations
`msf_module_execute`	`module.execute`	dangerous	`read_only_hint: false, destructive_hint: true, idempotent_hint: false`
`msf_module_check`	`module.check`	dangerous	`read_only_hint: false, destructive_hint: true, idempotent_hint: false`
`msf_module_results`	`module.results`	read-only	`read_only_hint: true, destructive_hint: false, idempotent_hint: true`
`msf_running_stats`	`module.running_stats`	read-only	`read_only_hint: true, destructive_hint: false, idempotent_hint: true`
`msf_session_list`	`session.list`	read-only	`read_only_hint: true, destructive_hint: false, idempotent_hint: true`
`msf_session_stop`	`session.stop`	dangerous	`read_only_hint: false, destructive_hint: true, idempotent_hint: false`
`msf_session_read`	`session.interactive_read`	read-only	`read_only_hint: true, destructive_hint: false, idempotent_hint: true`
`msf_session_write`	`session.interactive_write`	dangerous	`read_only_hint: false, destructive_hint: true, idempotent_hint: false`

Dangerous-mode gate

Dangerous tools fail closed. The gate is opened by any one of:

--enable-dangerous-actions on the msfmcpd CLI.
MSF_MCP_DANGEROUS_ACTIONS=true (or 1, yes, on) in the environment.
mcp.dangerous_actions: true in config/mcp_config.yaml (or the JSON-RPC variant).

Related Issue:
This resolves #21270.

Breaking Changes

Minor changes:

module.execute RPC for exploit, post, and evasion modules: uuid field semantics changed (now 24-character)
module.results RPC: HTTP status code changed for unknown UUIDs (404 -> 500)
RPC top-level exception handler broadened: rescue ::StandardError -> After: rescue ::StandardError, ::ScriptError

Verification Steps

Follow the steps in the documentation to setup and start the RPC and MCP servers.

The verification can be done manually using the MCP Inspector and test the MCP tools individually:

npx @modelcontextprotocol/inspector

Or you can use your favorite LLM to test live. (see the documentation)

I also included an integration test script that simulates a MCP client and performs standard operations with the MCP tools. The script can be found here: tools/dev/msfmcp_integration_test.rb

> ruby tools/dev/msfmcp_integration_test.rb --help
Usage: ruby tools/dev/msfmcp_integration_test.rb [options]
        --url URL                    MCP HTTP endpoint (default: http://127.0.0.1:3000)
        --token TOKEN                Bearer token (or set $MSF_MCP_TOKEN)
        --enable-dangerous           Run the dangerous-tool execution paths too
        --rhost IP                   RHOSTS target for dangerous tests (e.g. 192.0.2.10)
        --lhost IP                   LHOST for payload-bound dangerous tests
        --lport PORT                 LPORT for payload-bound dangerous tests
        --session-id N               Existing session id for session read test
        --check-module SPEC          Module spec for msf_module_check as TYPE:NAME
                                     (default: exploit:windows/smb/ms17_010_eternalblue)
        --check-option K=V           Datastore option for msf_module_check (repeatable, overrides defaults)
        --execute-module SPEC        Module spec for msf_module_execute as TYPE:NAME
                                     (default: auxiliary:scanner/portscan/tcp)
        --execute-option K=V         Datastore option for msf_module_execute (repeatable, overrides defaults)
        --exploit-timeout SEC        Seconds to wait for the exploit run to reach a terminal state (default: 120)
        --filter PAT                 Only run tests whose name matches PAT
    -v, --verbose                    Print full responses on failure
    -d, --debug                      Print the full HTTP request/response for every call (succeeds too)
    -h, --help                       Show this help

AI Usage Disclosure

AI was used to help designing and implementing these changes (Copilot).

Pre-Submission Checklist

Included a corresponding documentation markdown file in documentation/modules (new modules only)
No sensitive information (IP addresses, credentials, API keys, hashes) in code or documentation
Tested on the target environment specified in the Environment section above
Included RSpec tests for library changes (encouraged for lib/ changes)
Read the CONTRIBUTING.md and module acceptance guidelines

Hardware and Complex Software Module Guidance

If your module targets specialized hardware (routers, IoT, PLCs, etc.) or complex software (licensed, multi-service, or multi-version), provide a pcap, screen recording, or video showing successful execution.

Email sanitized pcaps/recordings to msfdev@metasploit.com — remove real IPs, credentials, and hostnames before sending. If hardware/software is unavailable, explain in the PR description.

Responsiveness and PR Takeover Policy

We want every contribution to make it into the project. If approximately 2 weeks pass after a review request without a comment or code update from you, the team may take over the PR and complete the work on your behalf.

If this happens, you will remain credited as a co-author on the final commit — your contribution is always recognized.

This policy exists to keep the project moving forward. It is not a reflection on the quality of your work or your involvement. Life happens, and we would rather finish the work together than let a good contribution go stale.

- module_execute, module_check, module_results, running_stats, session_list, session_stop, session_read, session_write

cdelafuente-r7 · 2026-07-01T16:30:02Z

            default: 0
          }
-        },
-        required: [:workspace]


Removing workspace from required since it defaults to the default workspace if not provided. This also applies to the other DB tools.

cdelafuente-r7 · 2026-07-01T16:34:56Z

      {"status" => "ready"}
    else
-      error(404, "Results not found for module instance #{uuid}")
+      error(500, "Results not found for module instance #{uuid}")


It is an application level error and not an HTTP error (cannot find the requested resource).

cdelafuente-r7 · 2026-07-01T16:35:43Z

      res.message = e.http_msg
-    rescue ::StandardError => e
-      elog('Unknown Exception', error: e)
+    rescue ::StandardError, ::ScriptError => e


::ScriptError is there to catch any ::NotImplementedError (e.g. check method not implemented)

dwelch-r7 · 2026-07-02T13:46:37Z

Let's see if we can make the run_simple changes work here too

I think it may also need updated here

metasploit-framework/lib/msf/core/exploit/local.rb

Lines 22 to 24 in 1617b3e

def run_simple(opts = {}, &block)

Msf::Simple::Exploit.exploit_simple(self, opts, &block)

end

dwelch-r7 · 2026-07-02T13:47:56Z

      mod.init_ui(nil, nil)
    end

+    run_uuid = Rex::Text.rand_text_alphanumeric(24)


Investigate using a real UUID for this

dwelch-r7 · 2026-07-02T13:53:22Z

      'RunAsJob' => true,
-      'Options'  => opts
+      'Options'  => opts,
+      'JobListener' => self.job_status_tracker


This will also need updated when ou make exploit work like the rest

dwelch-r7 · 2026-07-02T13:55:06Z

    {
      "job_id" => mod.job_id,
-      "uuid" => mod.uuid
+      "uuid" => mod.run_uuid || mod.uuid


Let's verify if the old uuid actually makes sense to fall back to

dwelch-r7 · 2026-07-02T14:15:54Z

+      # all inherited mixins, so 100 is a comfortable ceiling. This is a
+      # defence-in-depth cap against DoS-style input abuse from an MCP client,
+      # not a transport limit (MCP itself does not restrict payload size).
+      MODULE_OPTIONS_MAX_KEYS = 100


should this kind of validation live on the RPC side of things rather than MCP?

dwelch-r7 · 2026-07-02T14:21:47Z

+                         'Values must be scalars (string, integer, float, boolean, or null). ' \
+                         'Example: {"RHOSTS": "192.0.2.10", "RPORT": 445}. ' \
+                         'No nested objects or arrays.',
+            additionalProperties: { type: %w[string integer number boolean null] }


Verify this includes floats

dwelch-r7 · 2026-07-02T14:29:19Z

+            minLength: 1,
+            maxLength: 50


this might need updated

dwelch-r7 · 2026-07-02T14:33:08Z

+            results: raw_result['results'] || []
+          }
+
+          metadata = { query_time: (Time.now - start_time).round(3) }


Rex::StopWatch or MonotonicClock (check my spelling there)

cdelafuente-r7 added 8 commits July 1, 2026 17:02

Add job tracking to exploit execution

0c77e47

Add job tracking for post and evasion modules & specs

40410a7

Add 8 new MCP tools:

699a2a5

- module_execute, module_check, module_results, running_stats, session_list, session_stop, session_read, session_write

Add dangerous_actions configuration gate

500d0cd

Expose UUID via a accessor instead of returning it

22cf08a

Fix regression with JSON-RPC

49097b5

Update the documentation

721d73a

Add integration test script

8f8d690

cdelafuente-r7 added this to Metasploit Kanban Jul 1, 2026

cdelafuente-r7 added docs enhancement rn-enhancement release notes enhancement labels Jul 1, 2026

github-project-automation Bot moved this to Todo in Metasploit Kanban Jul 1, 2026

cdelafuente-r7 commented Jul 1, 2026

View reviewed changes

Fix documentaiton and DB tools required field

8b0ebbb

cdelafuente-r7 force-pushed the mcp-server-enhancement branch from 4125e03 to 8b0ebbb Compare July 1, 2026 16:32

cdelafuente-r7 commented Jul 1, 2026

View reviewed changes

cdelafuente-r7 marked this pull request as draft July 1, 2026 17:24

Fix issue with non-meterpreter sessions

99bb37f

cdelafuente-r7 marked this pull request as ready for review July 2, 2026 13:24

dwelch-r7 self-assigned this Jul 2, 2026

dwelch-r7 reviewed Jul 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

MCP server support for "dangerous" actions & new tools#21632

MCP server support for "dangerous" actions & new tools#21632
cdelafuente-r7 wants to merge 10 commits into
rapid7:masterfrom
cdelafuente-r7:mcp-server-enhancement

cdelafuente-r7 commented Jul 1, 2026 •

edited

Loading

Uh oh!

cdelafuente-r7 Jul 1, 2026

Uh oh!

cdelafuente-r7 Jul 1, 2026

Uh oh!

cdelafuente-r7 Jul 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

dwelch-r7 Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	def run_simple(opts = {}, &block)
	Msf::Simple::Exploit.exploit_simple(self, opts, &block)
	end

Uh oh!

Conversation

cdelafuente-r7 commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

The eight new tools

Dangerous-mode gate

Breaking Changes

Verification Steps

AI Usage Disclosure

Pre-Submission Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cdelafuente-r7 Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cdelafuente-r7 commented Jul 1, 2026 •

edited

Loading

cdelafuente-r7 Jul 1, 2026 •

edited

Loading