Class: Msf::EventDispatcher

Inherits:
Object
  • Object
show all
Includes:
Framework::Offspring
Defined in:
lib/msf/core/event_dispatcher.rb

Overview

This class manages subscriber registration and is the entry point for dispatching various events that occur for modules, such as exploit results and auxiliary module data. The framework and external modules can register themselves as subscribers to various events such that they can perform custom actions when a specific event or events occur.

Instance Attribute Summary

Attributes included from Framework::Offspring

#framework

Instance Method Summary collapse

Constructor Details

#initialize(framework) ⇒ EventDispatcher

Returns a new instance of EventDispatcher


59
60
61
62
63
64
65
66
67
# File 'lib/msf/core/event_dispatcher.rb', line 59

def initialize(framework)
  self.framework = framework
  self.general_event_subscribers = []
  self.custom_event_subscribers  = []
  self.exploit_event_subscribers = []
  self.session_event_subscribers = []
  self.db_event_subscribers      = []
  self.ui_event_subscribers      = []
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ Object

Capture incoming events and pass them off to the subscribers

When receiving an on_* event, look for a subscriber type matching the type of the event. If one exists, send the event on to each subscriber of that type. Otherwise, try to send the event each of the general subscribers.

Event method names should be like “on_<type>_<event>”, e.g.: on_exploit_success.


172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
# File 'lib/msf/core/event_dispatcher.rb', line 172

def method_missing(name, *args)

  event,type,rest = name.to_s.split("_", 3)
  subscribers = "#{type}_event_subscribers"
  found = false
  case event
  when "on"
    if respond_to?(subscribers)
      found = true
      self.send(subscribers).each do |sub|
        next if not sub.respond_to?(name)
        sub.send(name, *args)
      end
    else
      (general_event_subscribers + custom_event_subscribers).each do |sub|
        next if not sub.respond_to?(name)
        sub.send(name, *args)
        found = true
      end
    end
  when "add"
    if respond_to?(subscribers)
      found = true
      add_event_subscriber(self.send(subscribers), *args)
    end
  when "remove"
    if respond_to?(subscribers)
      found = true
      remove_event_subscriber(self.send(subscribers), *args)
    end
  end

  return found
end

Instance Method Details

#add_db_subscriber(subscriber) ⇒ Object

This method adds a db event subscriber. db event subscribers receive notifications when events occur that pertain to db changes. The subscriber provided must implement the DatabaseEvent module methods in some form.


96
97
98
# File 'lib/msf/core/event_dispatcher.rb', line 96

def add_db_subscriber(subscriber)
  add_event_subscriber(db_event_subscribers, subscriber)
end

#add_exploit_subscriber(subscriber) ⇒ Object

This method adds an exploit event subscriber. Exploit event subscribers receive notifications when events occur that pertain to exploits, such as the success or failure of an exploitation attempt. The subscriber provided must implement the ExploitEvent module methods in some form.


114
115
116
# File 'lib/msf/core/event_dispatcher.rb', line 114

def add_exploit_subscriber(subscriber)
  add_event_subscriber(exploit_event_subscribers, subscriber)
end

#add_general_subscriber(subscriber) ⇒ Object

This method adds a general subscriber. General subscribers receive notifications when all events occur.


79
80
81
# File 'lib/msf/core/event_dispatcher.rb', line 79

def add_general_subscriber(subscriber)
  add_event_subscriber(general_event_subscribers, subscriber)
end

#add_session_subscriber(subscriber) ⇒ Object

This method adds a session event subscriber. Session event subscribers receive notifications when sessions are opened and closed. The subscriber provided must implement the SessionEvent module methods in some form.


131
132
133
# File 'lib/msf/core/event_dispatcher.rb', line 131

def add_session_subscriber(subscriber)
  add_event_subscriber(session_event_subscribers, subscriber)
end

#on_module_load(name, mod) ⇒ Object

Called when a module is loaded into the framework. This, in turn, notifies all registered general event subscribers.

This is covered by the method_missing logic, but defining it manually reduces startup time by about 10%.


155
156
157
158
159
# File 'lib/msf/core/event_dispatcher.rb', line 155

def on_module_load(name, mod)
  general_event_subscribers.each { |subscriber|
    subscriber.on_module_load(name, mod)
  }
end

#remove_db_subscriber(subscriber) ⇒ Object

Removes a db event subscriber.


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

def remove_db_subscriber(subscriber)
  remove_event_subscriber(db_event_subscribers, subscriber)
end

#remove_exploit_subscriber(subscriber) ⇒ Object

Removes an exploit event subscriber.


121
122
123
# File 'lib/msf/core/event_dispatcher.rb', line 121

def remove_exploit_subscriber(subscriber)
  remove_event_subscriber(exploit_event_subscribers, subscriber)
end

#remove_general_subscriber(subscriber) ⇒ Object

Removes a general subscriber.


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

def remove_general_subscriber(subscriber)
  remove_event_subscriber(general_event_subscribers, subscriber)
end

#remove_session_subscriber(subscriber) ⇒ Object

Removes a session event subscriber.


138
139
140
# File 'lib/msf/core/event_dispatcher.rb', line 138

def remove_session_subscriber(subscriber)
  remove_event_subscriber(session_event_subscribers, subscriber)
end