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

#alerts ⇒ Object (protected)

Returns the value of attribute alerts.



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

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.



110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/msf/core/module/alert.rb', line 110

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_info(msg = nil, &block) ⇒ true?

Add an info message that will be provided to the user as early possible when using this instance of a 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 info message

  • block (Proc) —

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

Returns:

  • (true, nil) —

    whether or not the message was added to the list of info messages



54
55
56
 
# File 'lib/msf/core/module/alert.rb', line 54

def add_info(msg = nil, &block)
  add_alert(:info, 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

#errors ⇒ Array<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)



66
67
68
 
# File 'lib/msf/core/module/alert.rb', line 66

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:

  • level (Symbol) —

    The 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.



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

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

#infos ⇒ Array<String, Proc>

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

Returns:

  • (Array<String, Proc>) —

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



72
73
74
 
# File 'lib/msf/core/module/alert.rb', line 72

def infos
  get_alerts(:info)
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.



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

def usable?
  errors.empty?
end

#warnings ⇒ Array<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)



60
61
62
 
# File 'lib/msf/core/module/alert.rb', line 60

def warnings
  get_alerts(:warning)
end