Module: Msf::Handler

Included in:
BindTcp, FindPort, None, ReverseHttp, ReverseTcp, ReverseTcpDouble, ReverseTcpDoubleSSL
Defined in:
lib/msf/core/handler.rb,
lib/msf/core/handler/none.rb,
lib/msf/core/handler/find_tag.rb,
lib/msf/core/handler/bind_tcp.rb,
lib/msf/core/handler/find_tty.rb,
lib/msf/core/handler/find_port.rb,
lib/msf/core/handler/find_shell.rb,
lib/msf/core/handler/reverse_tcp.rb,
lib/msf/core/handler/reverse_http.rb,
lib/msf/core/handler/reverse_https.rb,
lib/msf/core/handler/reverse_tcp_ssl.rb,
lib/msf/core/handler/reverse_ipv6_http.rb,
lib/msf/core/handler/reverse_ipv6_https.rb,
lib/msf/core/handler/reverse_tcp_double.rb,
lib/msf/core/handler/reverse_https_proxy.rb,
lib/msf/core/handler/reverse_tcp_allports.rb,
lib/msf/core/handler/reverse_tcp_double_ssl.rb,
lib/msf/core/handler/reverse_http/uri_checksum.rb

Overview

This module acts as a base for all handler pseudo-modules. They aren't really modules, so don't get the wrong idea champs! They're merely mixed into dynamically generated payloads to handle monitoring for a connection. Handlers are layered in between the base payload class and any other payload class. A super cool ASCII diagram would look something like this

 Module
   ^
   |
Payload
   ^
   |
Handler
   ^
   |
 Stager
   ^
   |
  Stage

Defined Under Namespace

Modules: BindTcp, FindPort, FindShell, FindTag, FindTty, None, ReverseHttp, ReverseHttps, ReverseHttpsProxy, ReverseIPv6Http, ReverseIPv6Https, ReverseTcp, ReverseTcpAllPorts, ReverseTcpDouble, ReverseTcpDoubleSSL, ReverseTcpSsl

Constant Summary collapse

Claimed =

Returned by handlers to indicate that a socket has been claimed for use by the payload.

"claimed"
Unused =

Returned by handlers to indicate that a socket has not been claimed for use.

"unused"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#exploit_configObject

Set by the exploit module to configure handler


165
166
167
# File 'lib/msf/core/handler.rb', line 165

def exploit_config
  @exploit_config
end

#parent_payloadObject

This will be non-nil if the handler has a parent payload that it was spawned from. Right now, this is only the case with generic payloads. The parent payload is used to create a session rather than using the instance itself.


173
174
175
# File 'lib/msf/core/handler.rb', line 173

def parent_payload
  @parent_payload
end

Class Method Details

.general_handler_typeObject

Returns the transport-independent handler type.


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

def self.general_handler_type
  "none"
end

.handler_typeObject

Returns the handler type.


53
54
55
# File 'lib/msf/core/handler.rb', line 53

def self.handler_type
  return "none"
end

Instance Method Details

#add_handler(opts = {}) ⇒ Object

Start another connection monitor


106
107
# File 'lib/msf/core/handler.rb', line 106

def add_handler(opts={})
end

#cleanup_handlerObject

Terminates the connection handler.


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

def cleanup_handler
end

#handle_connection(conn, opts = {}) ⇒ Object

Handles an established connection supplied in the in and out handles. The handles are passed as parameters in case this handler is capable of handling multiple simultaneous connections. The default behavior is to attempt to create a session for the payload. This path will not be taken for multi-staged payloads.


130
131
132
# File 'lib/msf/core/handler.rb', line 130

def handle_connection(conn, opts={})
  create_session(conn, opts)
end

#handler(sock) ⇒ Object

Checks to see if a payload connection has been established on the supplied connection. This is necessary for find-sock style payloads.


120
121
# File 'lib/msf/core/handler.rb', line 120

def handler(sock)
end

#handler_nameObject

Returns the handler's name, if any.


67
68
69
# File 'lib/msf/core/handler.rb', line 67

def handler_name
  module_info['HandlerName']
end

#initialize(info = {}) ⇒ Object

Initializes the session waiter event and other fun stuff.


74
75
76
77
78
79
80
81
82
83
# File 'lib/msf/core/handler.rb', line 74

def initialize(info = {})
  super

  # Initialize the pending_connections counter to 0
  self.pending_connections = 0

  # Create the waiter event with auto_reset set to false so that
  # if a session is ever created, waiting on it returns immediately.
  self.session_waiter_event = Rex::Sync::Event.new(false, false)
end

#setup_handlerObject

Sets up the connection handler.


88
89
# File 'lib/msf/core/handler.rb', line 88

def setup_handler
end

#start_handlerObject

Start monitoring for a connection.


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

def start_handler
end

#stop_handlerObject

Stop monitoring for a connection.


112
113
# File 'lib/msf/core/handler.rb', line 112

def stop_handler
end

#wait_for_session(t = wfs_delay) ⇒ Object

Waits for a session to be created as the result of a handler connection coming in. The return value is a session object instance on success or nil if the timeout expires.


146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# File 'lib/msf/core/handler.rb', line 146

def wait_for_session(t = wfs_delay)
  session = nil

  begin
    session = session_waiter_event.wait(t)
  rescue ::Timeout::Error
  end

  # If a connection has arrived, wait longer...
  if (pending_connections > 0)
    session = session_waiter_event.wait
  end

  return session
end

#wfs_delayObject

The amount of time to wait for a session to come in.


137
138
139
# File 'lib/msf/core/handler.rb', line 137

def wfs_delay
  2
end