Class: Msf::Module

Inherits:
Object
  • Object
show all
Extended by:
Framework::Offspring
Includes:
Alert, Arch, Auth, Author, Compatibility, DataStore, Failure, FullName, ModuleInfo, ModuleStore, Network, Options, Privileged, Ranking, Reliability, SideEffects, Stability, Type, UI, UUID
Defined in:
lib/msf/core/module.rb

Overview

The module base class is responsible for providing the common interface that is used to interact with modules at the most basic levels, such as by inspecting a given module’s attributes (name, description, version, authors, etc) and by managing the module’s data store.

Direct Known Subclasses

Auxiliary, Encoder, Evasion, Exploit, Nop, Payload, Post

Defined Under Namespace

Modules: Alert, Arch, Auth, Author, Compatibility, DataStore, Deprecated, External, Failure, FullName, HasActions, ModuleInfo, ModuleStore, Network, Options, Privileged, Ranking, Reliability, SideEffects, Stability, Type, UI, UUID Classes: AuxiliaryAction, Platform, PlatformList, Reference, SiteReference, Target

Constant Summary collapse

REPLICANT_EXTENSION_DS_KEY =

The key where a comma-separated list of Ruby module names will live in the datastore, consumed by #replicant to allow clean override of MSF module methods.

'ReplicantExtensions'

Constants included from ModuleInfo

ModuleInfo::UpdateableOptions

Constants included from Failure

Failure::BadConfig, Failure::Disconnected, Failure::NoAccess, Failure::NoTarget, Failure::None, Failure::NotFound, Failure::NotVulnerable, Failure::PayloadFailed, Failure::TimeoutExpired, Failure::UnexpectedReply, Failure::Unknown, Failure::Unreachable, Failure::UserInterrupt

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes included from UUID

#uuid

Attributes included from Rex::Ui::Subscriber::Input

#user_input

Attributes included from Rex::Ui::Subscriber::Output

#user_output

Attributes included from Privileged

#priveli, #privileged

Attributes included from Options

#options

Attributes included from ModuleStore

#module_store

Attributes included from ModuleInfo

#module_info

Attributes included from FullName

#aliased_as

Attributes included from DataStore

#datastore

Attributes included from Author

#author

Attributes included from Arch

#arch

Attributes included from Alert

#alerts, #you_have_been_warned

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Reliability

#reliability, #reliability_to_s

Methods included from Stability

#stability, #stability_to_s

Methods included from SideEffects

#side_effects, #side_effects_to_s

Methods included from UI

#init_ui

Methods included from UI::Message

#print_error, #print_good, #print_prefix, #print_status, #print_warning

Methods included from UI::Message::Verbose

#vprint_error, #vprint_good, #vprint_status, #vprint_warning

Methods included from UI::Line

#print_line, #print_line_prefix

Methods included from UI::Line::Verbose

#vprint_line

Methods included from Rex::Ui::Subscriber

#copy_ui, #init_ui, #reset_ui

Methods included from Rex::Ui::Subscriber::Input

#gets

Methods included from Rex::Ui::Subscriber::Output

#flush, #print, #print_blank_line, #print_error, #print_good, #print_line, #print_status, #print_warning

Methods included from Type

#auxiliary?, #encoder?, #evasion?, #exploit?, #nop?, #payload?, #post?, #type

Methods included from Ranking

#rank, #rank_to_h, #rank_to_s

Methods included from Privileged

#privileged?

Methods included from Options

#deregister_option_group, #deregister_options, #register_advanced_options, #register_evasion_options, #register_option_group, #register_options, #validate

Methods included from Network

#comm, #support_ipv6?, #target_host, #target_port

Methods included from ModuleStore

#[], #[]=

Methods included from ModuleInfo

#alias, #description, #disclosure_date, #info_fixups, #merge_check_key, #merge_info, #merge_info_advanced_options, #merge_info_alias, #merge_info_description, #merge_info_evasion_options, #merge_info_name, #merge_info_options, #merge_info_string, #merge_info_version, #name, #notes, #update_info

Methods included from FullName

#aliases, #fullname, #promptname, #realname, #refname, #shortname

Methods included from Failure

#report_failure

Methods included from DataStore

#import_defaults, #import_target_defaults, #share_datastore

Methods included from Compatibility

#compat, #compatible?, #init_compat

Methods included from Author

#author_to_s, #each_author

Methods included from Auth

#store_valid_credential

Methods included from Arch

#arch?, #arch_to_s, #each_arch

Methods included from Alert

#add_alert, #add_error, #add_info, #add_warning, #alert_user, #errors, #get_alerts, included, #infos, #is_usable?, #warnings, #without_prompt

Constructor Details

#initialize(info = {}) ⇒ Module

Creates an instance of an abstract module using the supplied information hash.



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
155
156
 
# File 'lib/msf/core/module.rb', line 113

def initialize(info = {})
  @module_info_copy = info.dup

  self.module_info = info
  # Initialize UUID for RPC compatibility
  uuid

  set_defaults

  # Initialize module compatibility hashes
  init_compat

  # Fixup module fields as needed
  info_fixups

  # Transform some of the fields to arrays as necessary
  self.author = Msf::Author.transform(module_info['Author'])
  self.arch = Rex::Transformer.transform(module_info['Arch'], Array, [ String ], 'Arch')
  self.platform = PlatformList.transform(module_info['Platform'])
  self.references = Rex::Transformer.transform(module_info['References'], Array, [ SiteReference, Reference ], 'Ref')

  # Create and initialize the option container for this module
  self.options = Msf::OptionContainer.new
  self.options.add_options(info['Options'], self.class)
  self.options.add_advanced_options(info['AdvancedOptions'], self.class)
  self.options.add_evasion_options(info['EvasionOptions'], self.class)

  # Create and initialize the data store for this module
  self.datastore = Msf::ModuleDataStore.new(self)

  # Import default options into the datastore
  import_defaults

  self.privileged = module_info['Privileged'] || false
  self.license = module_info['License'] || MSF_LICENSE

  # Allow all modules to track their current workspace
  register_advanced_options(
    [
      OptString.new('WORKSPACE', [ false, "Specify the workspace for this module" ]),
      OptBool.new('VERBOSE',     [ false, 'Enable detailed status messages', false ])
    ], Msf::Module)

end

Class Attribute Details

.adapted_refname ⇒ String?

Returns Reference name of the payload being adapted.

Returns:

  • (String, nil) —

    Reference name of the payload being adapted



89
90
91
 
# File 'lib/msf/core/module.rb', line 89

def adapted_refname
  @adapted_refname
end

.adapter_refname ⇒ String?

Returns Reference name of the payloads adapter.

Returns:

  • (String, nil) —

    Reference name of the payloads adapter



92
93
94
 
# File 'lib/msf/core/module.rb', line 92

def adapter_refname
  @adapter_refname
end

.file_path ⇒ Object

The path from which the module was loaded.



86
87
88
 
# File 'lib/msf/core/module.rb', line 86

def file_path
  @file_path
end

.orig_cls ⇒ Object

This attribute holds the non-duplicated copy of the module implementation. This attribute is used for reloading purposes so that it can be re-duplicated.



81
82
83
 
# File 'lib/msf/core/module.rb', line 81

def orig_cls
  @orig_cls
end

.stage_refname ⇒ String?

Returns Reference name of the payload stage.

Returns:

  • (String, nil) —

    Reference name of the payload stage



95
96
97
 
# File 'lib/msf/core/module.rb', line 95

def stage_refname
  @stage_refname
end

.stager_refname ⇒ String?

Returns Reference name of the payloads stager.

Returns:

  • (String, nil) —

    Reference name of the payloads stager



98
99
100
 
# File 'lib/msf/core/module.rb', line 98

def stager_refname
  @stager_refname
end

Instance Attribute Details

#error ⇒ Object

The last exception to occur using this module



429
430
431
 
# File 'lib/msf/core/module.rb', line 429

def error
  @error
end

#job_id ⇒ Object

The job identifier that this module is running as, if any.



424
425
426
 
# File 'lib/msf/core/module.rb', line 424

def job_id
  @job_id
end

#license ⇒ Object

The license under which this module is provided.



419
420
421
 
# File 'lib/msf/core/module.rb', line 419

def license
  @license
end

#platform ⇒ Object

The array of zero or more platforms.



409
410
411
 
# File 'lib/msf/core/module.rb', line 409

def platform
  @platform
end

#privileged=(value) ⇒ Object (writeonly, protected)

:nodoc:



461
462
463
 
# File 'lib/msf/core/module.rb', line 461

def privileged=(value)
  @privileged = value
end

#references ⇒ Object

The reference count for the module.



414
415
416
 
# File 'lib/msf/core/module.rb', line 414

def references
  @references
end

#user_data ⇒ Object

An opaque bag of data to attach to a module. This is useful for attaching some piece of identifying info on to a module before calling Simple::Exploit#exploit_simple or Simple::Auxiliary#run_simple for correlating where modules came from.



437
438
439
 
# File 'lib/msf/core/module.rb', line 437

def user_data
  @user_data
end

Class Method Details

.cached? ⇒ Boolean

Returns false since this is the real module

Returns:

  • (Boolean) 


334
335
336
 
# File 'lib/msf/core/module.rb', line 334

def self.cached?
  false
end

Instance Method Details

#adapted_refname ⇒ String?

Returns Reference name of the payload being adapted.

Returns:

  • (String, nil) —

    Reference name of the payload being adapted



226
227
228
 
# File 'lib/msf/core/module.rb', line 226

def adapted_refname
  self.class.adapted_refname
end

#adapter_refname ⇒ String?

Returns Reference name of the payloads adapter.

Returns:

  • (String, nil) —

    Reference name of the payloads adapter



231
232
233
 
# File 'lib/msf/core/module.rb', line 231

def adapter_refname
  self.class.adapter_refname
end

#black_listed_auth_filenames ⇒ Object 



359
360
361
362
363
364
365
366
 
# File 'lib/msf/core/module.rb', line 359

def black_listed_auth_filenames
  @black_listed_auth_filenames ||= lambda {
    [
      'fileformat',
      'browser'
    ]
  }.call
end

#debugging? ⇒ Boolean

Returns true if this module is being debugged.

Returns:

  • (Boolean) 


302
303
304
 
# File 'lib/msf/core/module.rb', line 302

def debugging?
  datastore['DEBUG']
end

#default_cred? ⇒ Boolean

Returns:

  • (Boolean) 


388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
 
# File 'lib/msf/core/module.rb', line 388

def default_cred?
  return false unless post_auth?

  required_cred_options.all? do |name, opt|
    if opt.type == 'string'
      if !opt.default.blank?
        true
      else
        false
      end
    else
      true
    end
  end

  false
end

#default_options ⇒ Object 



338
339
340
 
# File 'lib/msf/core/module.rb', line 338

def default_options
  self.module_info['DefaultOptions']
end

#fail_with(reason, msg = nil) ⇒ void

Note:

If you are writing an exploit, you don't use this API. Instead, please refer to the API documentation from lib/msf/core/exploit.rb.

This method returns an undefined value.

Raises a RuntimeError failure message. This is meant to be used for all non-exploits, and allows specific classes to override.

Examples:

fail_with('No Access', 'Unable to login')

Parameters:

  • reason (String) —

    A reason about the failure.

  • msg (String) (defaults to: nil) —

    (Optional) A message about the failure.

Raises:

  • (RuntimeError)

See Also:



320
321
322
 
# File 'lib/msf/core/module.rb', line 320

def fail_with(reason, msg=nil)
  raise RuntimeError, "#{reason.to_s}: #{msg}"
end

#file_path ⇒ Object

The path to the file in which the module can be loaded from.



221
222
223
 
# File 'lib/msf/core/module.rb', line 221

def file_path
  self.class.file_path
end

#framework ⇒ Object

Returns the class reference to the framework



105
106
107
 
# File 'lib/msf/core/module.rb', line 105

def framework
  self.class.framework
end

#has_check? ⇒ Boolean

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/msf/core/module.rb', line 158

def has_check?
  respond_to?(:check)
end

#orig_cls ⇒ Object

Returns the unduplicated class associated with this module.



214
215
216
 
# File 'lib/msf/core/module.rb', line 214

def orig_cls
  self.class.orig_cls
end

#owner ⇒ Object

Returns the username that instantiated this module, this tries a handful of methods to determine what actual user ran this module.



257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/msf/core/module.rb', line 257

def owner
  # Generic method to configure a module owner
  username = self.datastore['MODULE_OWNER'].to_s.strip

  # Specific method used by the commercial products
  if username.empty?
    username = self.datastore['PROUSER'].to_s.strip
  end

  # Fallback when neither prior method is available, common for msfconsole
  if username.empty?
    username = (ENV['LOGNAME'] || ENV['USERNAME'] || ENV['USER'] || "unknown").to_s.strip
  end

  username
end

#perform_extensions ⇒ void

This method returns an undefined value.

Extends self with the constant list in the datastore



190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/msf/core/module.rb', line 190

def perform_extensions
  if datastore[REPLICANT_EXTENSION_DS_KEY].present?
    if datastore[REPLICANT_EXTENSION_DS_KEY].respond_to?(:each)
      datastore[REPLICANT_EXTENSION_DS_KEY].each do |const|
        self.extend(const)
      end
    else
      fail "Invalid settings in datastore at key #{REPLICANT_EXTENSION_DS_KEY}"
    end
  end
end

#platform?(what) ⇒ Boolean

Checks to see if this module is compatible with the supplied platform

Returns:

  • (Boolean) 


295
296
297
 
# File 'lib/msf/core/module.rb', line 295

def platform?(what)
  (platform & what).empty? == false
end

#platform_to_s ⇒ Object

Return a comma separated list of supported platforms, if any.



288
289
290
 
# File 'lib/msf/core/module.rb', line 288

def platform_to_s
  platform.all? ? "All" : platform.names.join(", ")
end

#post_auth? ⇒ Boolean

Returns:

  • (Boolean) 


368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/msf/core/module.rb', line 368

def post_auth?
  if self.kind_of?(Msf::Auxiliary::AuthBrute)
    return true
  else
    # Some modules will never be post auth, so let's not waste our time
    # determining it and create more potential false positives.
    # If these modules happen to be post auth for some reason, then we it
    # should manually override the post_auth? method as true.
    directory_name = self.fullname.split('/')[0..-2]
    black_listed_auth_filenames.each do |black_listed_name|
      return false if directory_name.include?(black_listed_name)
    end

    # Some modules create their own username and password datastore
    # options, not relying on the AuthBrute mixin. In that case we
    # just have to go through the options and try to identify them.
    !required_cred_options.empty?
  end
end

#register_extensions(*rb_modules) ⇒ void

This method returns an undefined value.

Parameters:

  • rb_modules (Constant) —

    One or more Ruby constants



204
205
206
207
208
209
 
# File 'lib/msf/core/module.rb', line 204

def register_extensions(*rb_modules)
  datastore[REPLICANT_EXTENSION_DS_KEY] = [] unless datastore[REPLICANT_EXTENSION_DS_KEY].present?
  rb_modules.each do |rb_mod|
    datastore[REPLICANT_EXTENSION_DS_KEY] << rb_mod unless datastore[REPLICANT_EXTENSION_DS_KEY].include? rb_mod
  end
end

#register_parent(ref) ⇒ Object

Scans the parent module reference to populate additional information. This is used to inherit common settings (owner, workspace, parent uuid, etc).



278
279
280
281
282
283
 
# File 'lib/msf/core/module.rb', line 278

def register_parent(ref)
  self.datastore['WORKSPACE']    = (ref.datastore['WORKSPACE'] ? ref.datastore['WORKSPACE'].dup : nil)
  self.datastore['PROUSER']      = (ref.datastore['PROUSER']   ? ref.datastore['PROUSER'].dup   : nil)
  self.datastore['MODULE_OWNER'] = ref.owner.dup
  self.datastore['ParentUUID']   = ref.uuid.dup
end

#replicant ⇒ Object

Creates a fresh copy of an instantiated module



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/msf/core/module.rb', line 165

def replicant
  obj = self.clone
  self.instance_variables.each { |k|
    old_value = instance_variable_get(k)
    begin
      new_value = old_value.is_a?(Rex::Ref) ? old_value.ref : old_value.dup
    rescue => e
      elog("#{self.class} replicant failed to dup #{k}", error: e)
      new_value = old_value
    end

    obj.instance_variable_set(k, new_value)
  }

  obj.datastore    = self.datastore.copy
  obj.user_input   = self.user_input
  obj.user_output  = self.user_output
  obj.module_store = self.module_store.clone

  obj.perform_extensions
  obj
end

#required_cred_options ⇒ Object 



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/msf/core/module.rb', line 342

def required_cred_options
  @required_cred_options ||= lambda {
    self.options.select { |name, opt|
      (
        opt.type?('string') &&
        opt.required &&
        (opt.name.match(/user(name)*$/i) || name.match(/pass(word)*$/i))
      ) ||
      (
        opt.type?('bool') &&
        opt.required &&
        opt.name.match(/^allow_guest$/i)
      )
    }
  }.call
end

#set_defaults ⇒ Object (protected)

Sets the modules unsupplied info fields to their default values.



444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/msf/core/module.rb', line 444

def set_defaults
  self.module_info = {
    'Name'        => 'No module name',
    'Description' => 'No module description',
    'Version'     => '0',
    'Author'      => nil,
    'Arch'        => nil, # No architectures by default.
    'Platform'    => [],  # No platforms by default.
    'Ref'         => nil,
    'Privileged'  => false,
    'License'     => MSF_LICENSE,
    'Notes'       => {}
  }.update(self.module_info)
  self.module_store = {}
end

#stage_refname ⇒ String?

Returns Reference name of the payload stage.

Returns:

  • (String, nil) —

    Reference name of the payload stage



236
237
238
 
# File 'lib/msf/core/module.rb', line 236

def stage_refname
  self.class.stage_refname
end

#stager_refname ⇒ String?

Returns Reference name of the payloads stager.

Returns:

  • (String, nil) —

    Reference name of the payloads stager



241
242
243
 
# File 'lib/msf/core/module.rb', line 241

def stager_refname
  self.class.stager_refname
end

#workspace ⇒ Object

Returns the current workspace



248
249
250
251
 
# File 'lib/msf/core/module.rb', line 248

def workspace
  self.datastore['WORKSPACE'] ||
    (framework.db and framework.db.active and framework.db.workspace and framework.db.workspace.name)
end