Module: Msf::Handler::ReverseTcp

Includes:
Msf::Handler, Reverse, Msf::Handler::Reverse::Comm
Included in:
ReverseTcpAllPorts, ReverseTcpSsl
Defined in:
lib/msf/core/handler/reverse_tcp.rb

Overview

This module implements the reverse TCP handler. This means that it listens on a port waiting for a connection until either one is established or it is told to abort.

This handler depends on having a local host and port to listen on.

Constant Summary

Constants included from Msf::Handler

Claimed, Unused

Instance Attribute Summary collapse

Attributes included from Msf::Handler

#exploit_config, #parent_payload, #pending_connections, #session_waiter_event, #sessions

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Msf::Handler::Reverse::Comm

#select_comm, #via_string_for_ip

Methods included from Reverse

#bind_addresses, #bind_port, #is_loopback_address?, #setup_handler

Methods included from Msf::Handler

#add_handler, #create_session, #handle_connection, #handler, #handler_name, #interrupt_wait_for_session, #register_session, #setup_handler, #wait_for_session, #wfs_delay

Instance Attribute Details

#conn_threadsObject (protected)

:nodoc:


239
240
241
# File 'lib/msf/core/handler/reverse_tcp.rb', line 239

def conn_threads
  @conn_threads
end

#handler_threadObject (protected)

:nodoc:


238
239
240
# File 'lib/msf/core/handler/reverse_tcp.rb', line 238

def handler_thread
  @handler_thread
end

#listener_sockObject (protected)

:nodoc:


236
237
238
# File 'lib/msf/core/handler/reverse_tcp.rb', line 236

def listener_sock
  @listener_sock
end

#listener_threadObject (protected)

:nodoc:


237
238
239
# File 'lib/msf/core/handler/reverse_tcp.rb', line 237

def listener_thread
  @listener_thread
end

Class Method Details

.general_handler_typeObject

Returns the connection-described general handler type, in this case 'reverse'.


34
35
36
# File 'lib/msf/core/handler/reverse_tcp.rb', line 34

def self.general_handler_type
  "reverse"
end

.handler_typeObject

Returns the string representation of the handler type, in this case 'reverse_tcp'.


26
27
28
# File 'lib/msf/core/handler/reverse_tcp.rb', line 26

def self.handler_type
  "reverse_tcp"
end

Instance Method Details

#cleanup_handlerObject

Closes the listener socket if one was created.


67
68
69
70
71
72
73
74
75
76
77
78
79
# File 'lib/msf/core/handler/reverse_tcp.rb', line 67

def cleanup_handler
  stop_handler

  # Kill any remaining handle_connection threads that might
  # be hanging around
  conn_threads.each do |thr|
    begin
      thr.kill
    rescue
      nil
    end
  end
end

#human_nameString

A string suitable for displaying to the user

Returns:

  • (String)

84
85
86
# File 'lib/msf/core/handler/reverse_tcp.rb', line 84

def human_name
  "reverse TCP"
end

#initialize(info = {}) ⇒ Object

Initializes the reverse TCP handler and ads the options that are required for all reverse TCP payloads, like local host and local port.


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# File 'lib/msf/core/handler/reverse_tcp.rb', line 42

def initialize(info = {})
  super

  # XXX: Not supported by all modules
  register_advanced_options(
    [
      OptAddress.new(
        'ReverseListenerBindAddress',
        [ false, 'The specific IP address to bind to on the local system' ]
      ),
      OptBool.new(
        'ReverseListenerThreaded',
        [ true, 'Handle every connection in a new thread (experimental)', false ]
      )
    ] +
    Msf::Opt::stager_retry_options,
    Msf::Handler::ReverseTcp
  )

  self.conn_threads = []
end

#listener_uri(addr = datastore['ReverseListenerBindAddress']) ⇒ String

A URI describing where we are listening

Parameters:

  • addr (String) (defaults to: datastore['ReverseListenerBindAddress'])

    the address that

Returns:

  • (String)

    A URI of the form scheme://host:port/


99
100
101
102
103
# File 'lib/msf/core/handler/reverse_tcp.rb', line 99

def listener_uri(addr = datastore['ReverseListenerBindAddress'])
  addr = datastore['LHOST'] if addr.nil? || addr.empty?
  uri_host = Rex::Socket.is_ipv6?(addr) ? "[#{addr}]" : addr
  "tcp://#{uri_host}:#{bind_port}"
end

#payload_uriObject

A URI describing what the payload is configured to use for transport


89
90
91
92
93
# File 'lib/msf/core/handler/reverse_tcp.rb', line 89

def payload_uri
  addr = datastore['LHOST']
  uri_host = Rex::Socket.is_ipv6?(addr) ? "[#{addr}]" : addr
  "tcp://#{uri_host}:#{datastore['LPORT']}"
end

#start_handlerObject

Starts monitoring for an inbound connection.


108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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/handler/reverse_tcp.rb', line 108

def start_handler
  queue = ::Queue.new

  local_port = bind_port

  handler_name = "ReverseTcpHandlerListener-#{local_port}"
  self.listener_thread = framework.threads.spawn(handler_name, false, queue) { |lqueue|
    loop do
      # Accept a client connection
      begin
        client = listener_sock.accept
        if client
          self.pending_connections += 1
          lqueue.push(client)
        end
      rescue Errno::ENOTCONN
        nil
      rescue StandardError => e
        wlog [
          "#{handler_name}: Exception raised during listener accept: #{e.class}",
          $ERROR_INFO.to_s,
          $ERROR_POSITION.join("\n")
        ].join("\n")
      end
    end
  }

  worker_name = "ReverseTcpHandlerWorker-#{local_port}"
  self.handler_thread = framework.threads.spawn(worker_name, false, queue) { |cqueue|
    loop do
      begin
        client = cqueue.pop

        unless client
          elog("#{worker_name}: Queue returned an empty result, exiting...")
        end

        # Timeout and datastore options need to be passed through to the client
        opts = {
          datastore:     datastore,
          expiration:    datastore['SessionExpirationTimeout'].to_i,
          comm_timeout:  datastore['SessionCommunicationTimeout'].to_i,
          retry_total:   datastore['SessionRetryTotal'].to_i,
          retry_wait:    datastore['SessionRetryWait'].to_i
        }

        if datastore['ReverseListenerThreaded']
          thread_name = "#{worker_name}-#{client.peerhost}"
          conn_threads << framework.threads.spawn(thread_name, false, client) do |client_copy|
            handle_connection(wrap_aes_socket(client_copy), opts)
          end
        else
          handle_connection(wrap_aes_socket(client), opts)
        end
      rescue StandardError => e
        elog('Exception raised from handle_connection', error: e)
      end
    end
  }
end

#stop_handlerObject

Stops monitoring for an inbound connection.


219
220
221
222
223
224
225
226
227
228
229
230
231
232
# File 'lib/msf/core/handler/reverse_tcp.rb', line 219

def stop_handler
  # Terminate the listener thread
  listener_thread.kill if listener_thread && listener_thread.alive? == true

  # Terminate the handler thread
  handler_thread.kill if handler_thread && handler_thread.alive? == true

  begin
    listener_sock.close if listener_sock
  rescue IOError
    # Ignore if it's listening on a dead session
    dlog("IOError closing listener sock; listening on dead session?", LEV_1)
  end
end

#wrap_aes_socket(sock) ⇒ Object


169
170
171
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
206
207
208
209
210
211
212
213
214
# File 'lib/msf/core/handler/reverse_tcp.rb', line 169

def wrap_aes_socket(sock)
  if datastore["PAYLOAD"] !~ %r{java/} || (datastore["AESPassword"] || "") == ""
    return sock
  end

  socks = Rex::Socket.tcp_socket_pair
  socks[0].extend(Rex::Socket::Tcp)
  socks[1].extend(Rex::Socket::Tcp)

  m = OpenSSL::Digest.new('md5')
  m.reset
  key = m.digest(datastore["AESPassword"] || "")

  Rex::ThreadFactory.spawn('Session-AESEncrypt', false) do
    c1 = OpenSSL::Cipher.new('aes-128-cfb8')
    c1.encrypt
    c1.key = key
    sock.put([0].pack('N'))
    sock.put((c1.iv = c1.random_iv))
    buf1 = socks[0].read(4096)
    while buf1 && buf1 != ""
      sock.put(c1.update(buf1))
      buf1 = socks[0].read(4096)
    end
    sock.close
  end

  Rex::ThreadFactory.spawn('Session-AESDecrypt', false) do
    c2 = OpenSSL::Cipher.new('aes-128-cfb8')
    c2.decrypt
    c2.key = key

    iv = ""
    iv << sock.read(16 - iv.length) while iv.length < 16

    c2.iv = iv
    buf2 = sock.read(4096)
    while buf2 && buf2 != ""
      socks[0].put(c2.update(buf2))
      buf2 = sock.read(4096)
    end
    socks[0].close
  end

  socks[1]
end