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 collapse

Attributes included from Framework::Offspring

#framework

Instance Method Summary collapse

Constructor Details

#initialize(framework) ⇒ EventDispatcher

Returns a new instance of EventDispatcher.



21
22
23
24
25
26
27
28
29
 
# File 'lib/msf/core/event_dispatcher.rb', line 21

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.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/msf/core/event_dispatcher.rb', line 134

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, true)
      found = true
      self.send(subscribers).each do |sub|
        next if not sub.respond_to?(name, true)
        sub.send(name, *args)
      end
    else
      (general_event_subscribers + custom_event_subscribers).each do |sub|
        next if not sub.respond_to?(name, true)
        sub.send(name, *args)
        found = true
      end
    end
  when "add"
    if respond_to?(subscribers, true)
      found = true
      add_event_subscriber(self.send(subscribers), *args)
    end
  when "remove"
    if respond_to?(subscribers, true)
      found = true
      remove_event_subscriber(self.send(subscribers), *args)
    end
  end

  return found
end

Instance Attribute Details

#custom_event_subscribers ⇒ Object (protected)

:nodoc:



186
187
188
 
# File 'lib/msf/core/event_dispatcher.rb', line 186

def custom_event_subscribers
  @custom_event_subscribers
end

#db_event_subscribers ⇒ Object (protected)

:nodoc:



187
188
189
 
# File 'lib/msf/core/event_dispatcher.rb', line 187

def db_event_subscribers
  @db_event_subscribers
end

#exploit_event_subscribers ⇒ Object (protected)

:nodoc:



188
189
190
 
# File 'lib/msf/core/event_dispatcher.rb', line 188

def exploit_event_subscribers
  @exploit_event_subscribers
end

#general_event_subscribers ⇒ Object (protected)

:nodoc:



189
190
191
 
# File 'lib/msf/core/event_dispatcher.rb', line 189

def general_event_subscribers
  @general_event_subscribers
end

#session_event_subscribers ⇒ Object (protected)

:nodoc:



190
191
192
 
# File 'lib/msf/core/event_dispatcher.rb', line 190

def session_event_subscribers
  @session_event_subscribers
end

#ui_event_subscribers ⇒ Object (protected)

:nodoc:



191
192
193
 
# File 'lib/msf/core/event_dispatcher.rb', line 191

def ui_event_subscribers
  @ui_event_subscribers
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.



58
59
60
 
# File 'lib/msf/core/event_dispatcher.rb', line 58

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

#add_event_subscriber(array, subscriber) ⇒ Object (protected)

Adds an event subscriber to the supplied subscriber array.



175
176
177
 
# File 'lib/msf/core/event_dispatcher.rb', line 175

def add_event_subscriber(array, subscriber) # :nodoc:
  array << 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.



76
77
78
 
# File 'lib/msf/core/event_dispatcher.rb', line 76

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.



41
42
43
 
# File 'lib/msf/core/event_dispatcher.rb', line 41

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.



93
94
95
 
# File 'lib/msf/core/event_dispatcher.rb', line 93

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



117
118
119
120
121
 
# File 'lib/msf/core/event_dispatcher.rb', line 117

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.



65
66
67
 
# File 'lib/msf/core/event_dispatcher.rb', line 65

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

#remove_event_subscriber(array, subscriber) ⇒ Object (protected)

Removes an event subscriber from the supplied subscriber array.



182
183
184
 
# File 'lib/msf/core/event_dispatcher.rb', line 182

def remove_event_subscriber(array, subscriber) # :nodoc:
  array.delete(subscriber)
end

#remove_exploit_subscriber(subscriber) ⇒ Object

Removes an exploit event subscriber.



83
84
85
 
# File 'lib/msf/core/event_dispatcher.rb', line 83

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

#remove_general_subscriber(subscriber) ⇒ Object

Removes a general subscriber.



48
49
50
 
# File 'lib/msf/core/event_dispatcher.rb', line 48

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

#remove_session_subscriber(subscriber) ⇒ Object

Removes a session event subscriber.



100
101
102
 
# File 'lib/msf/core/event_dispatcher.rb', line 100

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