Class: Msf::MCP::Tools::SearchModules

Inherits:
MCP::Tool
  • Object
show all
Extended by:
ToolHelper
Defined in:
lib/msf/core/mcp/tools/search_modules.rb

Overview

MCP Tool: Search Metasploit Modules

Searches the Metasploit Framework module database using various criteria. Supports keyword search, filtering by type, platform, and pagination.

Class Method Summary collapse

Methods included from ToolHelper

tool_error_response

Class Method Details

.call(query:, limit: Msf::MCP::Security::InputValidator::LIMIT_DEFAULT, offset: 0, server_context:) ⇒ MCP::Tool::Response

Execute module search

Parameters:

  • query (String) —

    Search query

  • limit (Integer) (defaults to: Msf::MCP::Security::InputValidator::LIMIT_DEFAULT) —

    Maximum results (default: 100)

  • offset (Integer) (defaults to: 0) —

    Results offset (default: 0)

  • server_context (Hash) —

    Server context with msf_client, rate_limiter, config

Returns:

  • (MCP::Tool::Response) —

    Structured response with search results



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/msf/core/mcp/tools/search_modules.rb', line 92

def call(query:, limit: Msf::MCP::Security::InputValidator::LIMIT_DEFAULT, offset: 0, server_context:)
  start_time = Time.now

  # Extract dependencies from server context
  msf_client = server_context[:msf_client]
  rate_limiter = server_context[:rate_limiter]

  # Check rate limit
  rate_limiter.check_rate_limit!('search_modules')

  # Validate inputs
  Msf::MCP::Security::InputValidator.validate_search_query!(query)
  Msf::MCP::Security::InputValidator.validate_pagination!(limit, offset)

  # Call Metasploit API
  raw_modules = msf_client.search_modules(query)

  # Transform response
  transformed = Metasploit::ResponseTransformer.transform_modules(raw_modules)

  # Apply pagination
  #
  # Note that to get the total number of entries, we gather the entire data set and apply pagination here
  # instead of sending the limit and offset to the API call to be processed by MSF.
  # This is needed to provide accurate total_items count in the metadata.
  total_items = transformed.size
  paginated_data = transformed[offset, limit] || []

  # Build metadata
  metadata = {
    query: query,
    query_time: (Time.now - start_time).round(3),
    total_items: total_items,
    returned_items: paginated_data.size,
    limit: limit,
    offset: offset
  }

  # Return MCP response
  ::MCP::Tool::Response.new(
    [
      {
        type: 'text',
        text: JSON.generate(
          metadata: metadata,
          data: paginated_data
        )
      }
    ],
    structured_content: {
      metadata: metadata,
      data: paginated_data
    }
  )
rescue Msf::MCP::Security::RateLimitExceededError => e
  tool_error_response("Rate limit exceeded: #{e.message}")
rescue Msf::MCP::Metasploit::AuthenticationError => e
  tool_error_response("Authentication failed: #{e.message}")
rescue Msf::MCP::Metasploit::APIError => e
  tool_error_response("Metasploit API error: #{e.message}")
rescue Msf::MCP::Security::ValidationError => e
  tool_error_response(e.message)
end