Module: Msf::Module::Alert::ClassMethods

Defined in:
lib/msf/core/module/alert.rb

Overview

This mixin provides a way for alert messages to be added to module classes and instances, retrieved from module classes and instances, and displayed from module instances. The two alert levels provided by this mixin are `:error` and `:warning`, though other levels or display methods can be added by subclasses/other mixins if desired by overriding #alert_user method (calling `super` as necessary), adding a proxy method like #add_warning that calls #add_alert or #add_alert and optionally a helper retrieval method like #warnings.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#alertsObject (protected)

Returns the value of attribute alerts


84
85
86
# File 'lib/msf/core/module/alert.rb', line 84

def alerts
  @alerts
end

Instance Method Details

#add_alert(level, msg, &block) ⇒ Object (protected)

Add a message (or block that generates messages) to a module. This message will be displayed once to the user by every instance of this module.


89
90
91
92
93
94
95
96
97
98
99
# File 'lib/msf/core/module/alert.rb', line 89

def add_alert(level, msg, &block)
  self.alerts ||= {}
  self.alerts[level] ||= []
  if block
    self.alerts[level] << block
    true
  elsif msg
    self.alerts[level] << msg
    true
  end
end

#add_error(msg = nil, &block) ⇒ true?

Add an error that will be provided to the user as early possible when using the module, either when they select it with the `use` command, when the module is about to start running, or when the module generates its output. Adding an error will cause #is_usable to return `false`.

Parameters:

  • msg (String) (defaults to: nil)

    an optional error message

  • block (Proc)

    an optional block that will be executed in the context of the module instance at alert time to generate the error message. If provided the msg parameter is ignored.

Returns:

  • (true, nil)

    whether or not the message was added to the list of errors


39
40
41
# File 'lib/msf/core/module/alert.rb', line 39

def add_error(msg = nil, &block)
  add_alert(:error, msg, &block)
end

#add_warning(msg = nil, &block) ⇒ true?

Add a warning that will be provided to the user as early possible when using the module, either when they select it with the `use` command, when the module is about to start running, or when the module generates its output.

Parameters:

  • msg (String) (defaults to: nil)

    an optional warning message

  • block (Proc)

    an optional block that will be executed in the context of the module instance at alert time to generate the warning message. If provided the msg parameter is ignored.

Returns:

  • (true, nil)

    whether or not the message was added to the list of warnings


24
25
26
# File 'lib/msf/core/module/alert.rb', line 24

def add_warning(msg = nil, &block)
  add_alert(:warning, msg, &block)
end

#errorsArray<String, Proc>

Returns a list of error message strings, or blocks (see #get_alerts).

Returns:

  • (Array<String, Proc>)

    a list of error message strings, or blocks (see #get_alerts)


51
52
53
# File 'lib/msf/core/module/alert.rb', line 51

def errors
  get_alerts(:error)
end

#get_alerts(level) ⇒ Array<String, Proc>

Returns a list of `level` alerts, either in string or block form. Blocks expect to be executed in the context of a fully initialized module instance and will return `nil` if the alert they are looking for does not apply or a string or array of strings, each representing an alert.

Parameters:

  • the (Symbol)

    alert level to return

Returns:

  • (Array<String, Proc>)

    a list of `level` alerts, either in string or block form. Blocks expect to be executed in the context of a fully initialized module instance and will return `nil` if the alert they are looking for does not apply or a string or array of strings, each representing an alert.


61
62
63
64
65
# File 'lib/msf/core/module/alert.rb', line 61

def get_alerts(level)
  # Initialize here if needed, thanks to weird metaprogramming side-effects
  self.alerts ||= {}
  self.alerts[level] || []
end

#usable?true, false

This method allows modules to tell the framework if they are usable on the system that they are being loaded on in a generic fashion. By default, all modules are indicated as being usable. An example of where this is useful is if the module depends on something external to ruby, such as a binary.

This looks to have been abandoned at some point in the past, but it may be time to resurrect it.

Returns:

  • (true, false)

    whether or not the module has encountered any fatal errors thus far.


78
79
80
# File 'lib/msf/core/module/alert.rb', line 78

def usable?
  errors.empty?
end

#warningsArray<String, Proc>

Returns a list of warning message strings, or blocks (see #get_alerts).

Returns:

  • (Array<String, Proc>)

    a list of warning message strings, or blocks (see #get_alerts)


45
46
47
# File 'lib/msf/core/module/alert.rb', line 45

def warnings
  get_alerts(:warning)
end