Module: Msf::Module::Alert

Included in:
Msf::Module
Defined in:
lib/msf/core/module/alert.rb

Defined Under Namespace

Modules: ClassMethods

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#alerts ⇒ Object (protected)

Returns the value of attribute alerts.



184
185
186
 
# File 'lib/msf/core/module/alert.rb', line 184

def alerts
  @alerts
end

#you_have_been_warned ⇒ Object (protected)

Returns the value of attribute you_have_been_warned.



184
185
186
 
# File 'lib/msf/core/module/alert.rb', line 184

def you_have_been_warned
  @you_have_been_warned
end

Class Method Details

.included(base) ⇒ Object 



103
104
105
 
# File 'lib/msf/core/module/alert.rb', line 103

def self.included(base)
  base.extend(ClassMethods)
end

Instance Method Details

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

Add an alert for _this instance_ of a module (see Msf::Module::Alert::ClassMethods#add_alert)



187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/msf/core/module/alert.rb', line 187

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 a error 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. 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



134
135
136
 
# File 'lib/msf/core/module/alert.rb', line 134

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



118
119
120
 
# File 'lib/msf/core/module/alert.rb', line 118

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

#alert_user ⇒ Object (protected)

Display alerts with ‘print_warning` for warnings and `print_error` for errors. Alerts that have already been displayed by this module instance with this method will not be displayed again.



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/msf/core/module/alert.rb', line 202

def alert_user
  self.you_have_been_warned ||= {}

  errors.each do |msg|
    if msg && !self.you_have_been_warned[msg.hash]
      print_error(msg)
      self.you_have_been_warned[msg.hash] = true
    end
  end

  warnings.each do |msg|
    if msg && !self.you_have_been_warned[msg.hash]
      print_warning(msg)
      self.you_have_been_warned[msg.hash] = true
    end
  end
end

#errors ⇒ Array<String>

Returns a list of error strings to show the user.

Returns:

  • (Array<String>) —

    a list of error strings to show the user



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

def errors
  get_alerts(:error)
end

#get_alerts(level) ⇒ Array<String>

Similar to Msf::Module::Alert::ClassMethods#get_alerts, but executes each registered block in the context of this module instance and returns a flattened list of strings. (see Msf::Module::Alert::ClassMethods#get_alerts)

Parameters:

  • level (Symbol) —

    The alert level to return

Returns:

  • (Array<String>) 


168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/msf/core/module/alert.rb', line 168

def get_alerts(level)
  self.alerts ||= {}
  self.alerts[level] ||= []
  all_alerts = self.class.get_alerts(level) + self.alerts[level]
  all_alerts.map do |alert|
    case alert
    when Proc
      self.instance_exec &alert
    else
      alert
    end
  end.flatten.compact
end

#is_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.



149
150
151
 
# File 'lib/msf/core/module/alert.rb', line 149

def is_usable?
  errors.empty?
end

#warnings ⇒ Array<String>

Returns a list of warning strings to show the user.

Returns:

  • (Array<String>) —

    a list of warning strings to show the user



154
155
156
 
# File 'lib/msf/core/module/alert.rb', line 154

def warnings
  get_alerts(:warning)
end