Class: Ronin::Network::Proxy

Inherits:
Object
  • Object
show all
Defined in:
lib/ronin/network/proxy.rb

Overview

Base class for TCP and UDP Proxies.

Callbacks

The Proxy base class supports several callbacks for proxy events.

client_data

When a client sends data to the proxy.

on_client_data do |client,server,data|
  data.gsub!(/foo/,'bar')
end

server_data

When the server sends data to the proxy.

on_server_data do |client,server,data|
  data.gsub!(/foo/,'bar')
end

data

Alias for #on_client_data and #on_server_data.

Actions

The Proxy base class also provides methods to change how events are handled.

Since:

  • 0.5.0

Direct Known Subclasses

TCP::Proxy, UDP::Proxy

Constant Summary collapse

DEFAULT_HOST =

Default host to bind to

Since:

  • 0.5.0

'0.0.0.0'
DEFAULT_BUFFER_SIZE =

Since:

  • 0.5.0

4096

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|proxy| ... } ⇒ Proxy

Creates a new Proxy.

Examples:

Proxies 0.0.0.0:1337 to victim.com:80:

Proxy.new(:port => 1337, :server => ['victim.com', 80])

Proxies localhost:25 to victim.com:25:

Proxy.new(:port => 25, :host => 'localhost', :server => 'victim.com')

Parameters:

  • options (Hash) (defaults to: {}) —

    Options for the proxy.

Options Hash (options):

  • :host (String) — default: DEFAULT_HOST —

    The host to listen on.

  • :port (Integer) —

    The port to listen on.

  • :server (String, (host, port)) —

    The server to forward connections to.

  • :buffer_size (Integer) — default: DEFAULT_BUFFER_SIZE —

    The maximum amount of data to read in.

Yields:

  • (proxy) —

    If a block is given, it will be passed the new Proxy, before it has been configured.

Yield Parameters:

  • proxy (Proxy) —

    The new Proxy object.

Since:

  • 0.5.0



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/ronin/network/proxy.rb', line 116

def initialize(options={})
  @host = options.fetch(:host,DEFAULT_HOST)
  @port = options.fetch(:port)

  @server_host, @server_port = options.fetch(:server)
  @server_port ||= @port

  @callbacks = {
    :client_data => [],
    :server_data => []
  }

  @buffer_size = options.fetch(:buffer_size,DEFAULT_BUFFER_SIZE)
  @connections = {}

  yield self if block_given?
end

Instance Attribute Details

#buffer_size ⇒ Object

The size of read buffer

Since:

  • 0.5.0



80
81
82
 
# File 'lib/ronin/network/proxy.rb', line 80

def buffer_size
  @buffer_size
end

#connections ⇒ Object (readonly)

The connections maintained by the proxy

Since:

  • 0.5.0



83
84
85
 
# File 'lib/ronin/network/proxy.rb', line 83

def connections
  @connections
end

#host ⇒ Object (readonly)

The host the proxy will listen on

Since:

  • 0.5.0



68
69
70
 
# File 'lib/ronin/network/proxy.rb', line 68

def host
  @host
end

#port ⇒ Object (readonly)

The port the proxy will listen on

Since:

  • 0.5.0



71
72
73
 
# File 'lib/ronin/network/proxy.rb', line 71

def port
  @port
end

#server_host ⇒ Object (readonly)

The remote port the proxy will relay data to

Since:

  • 0.5.0



74
75
76
 
# File 'lib/ronin/network/proxy.rb', line 74

def server_host
  @server_host
end

#server_port ⇒ Object (readonly)

The remote host the proxy will relay data to

Since:

  • 0.5.0



77
78
79
 
# File 'lib/ronin/network/proxy.rb', line 77

def server_port
  @server_port
end

Class Method Details

.start(options = {}, &block) ⇒ Object

Creates a new Proxy and begins relaying data.

See Also:

Since:

  • 0.5.0



141
142
143
 
# File 'lib/ronin/network/proxy.rb', line 141

def self.start(options={},&block)
  new(options,&block).start
end

Instance Method Details

#callback(event, client_connection, server_connection = nil, data = nil) { ... } ⇒ Object (protected)

Triggers the callbacks registered for an event.

Parameters:

  • event (Symbol) —

    The event being triggered.

  • client_connection (connection) —

    The connection from the client to the proxy.

  • server_connection (connection) (defaults to: nil) —

    The connection from the proxy to the server.

  • data (String) (defaults to: nil) —

    The data being sent.

Yields:

  • [] If none of the callbacks interrupted the event, the given block will be called.

Since:

  • 0.5.0



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/ronin/network/proxy.rb', line 512

def callback(event,client_connection,server_connection=nil,data=nil)
  action = catch(:action) do
    @callbacks[event].each do |block|
      case block.arity
      when 1
        block.call(client_connection)
      when 2
        block.call(client_connection,server_connection)
      when 3, -1
        block.call(client_connection,server_connection,data)
      end
    end
  end

  case action
  when :ignore
    # no-op
  when :reset
    reset_connection(client_connection,server_connection)
  when :close
    close_connection(client_connection,server_connection)
  when :stop
    stop
  else
    yield if block_given?
  end
end

#client_connection_for(server_connection) ⇒ connection

Finds the connection from the client, associated with the server connection.

Parameters:

  • server_connection (connection) —

    The connection to the server.

Returns:

  • (connection) —

    The connection from the client.

Since:

  • 0.5.0



368
369
370
 
# File 'lib/ronin/network/proxy.rb', line 368

def client_connection_for(server_connection)
  @connections.index(server_connection)
end

#client_connections ⇒ Array<connection>

Connections from clients.

Returns:

  • (Array<connection>) —

    Client connections.

Since:

  • 0.5.0



330
331
332
 
# File 'lib/ronin/network/proxy.rb', line 330

def client_connections
  @connections.keys
end

#client_data(client_connection, server_connection, data) ⇒ Object (protected)

Triggers the client_data event.

Parameters:

  • client_connection (connection) —

    The connection from a client to the proxy.

  • server_connection (connection) —

    The connection from the proxy to the server.

  • data (String) —

    The data sent by the client.

Since:

  • 0.5.0



552
553
554
555
556
 
# File 'lib/ronin/network/proxy.rb', line 552

def client_data(client_connection,server_connection,data)
  callback(:client_data,client_connection,server_connection,data) do
    send(server_connection,data)
  end
end

#close ⇒ Object

Closes the proxy.

Since:

  • 0.5.0



232
233
234
235
 
# File 'lib/ronin/network/proxy.rb', line 232

def close
  close_connections
  close_proxy
end

#close! ⇒ Object

Causes the proxy to close a connection.

Since:

  • 0.5.0



302
303
304
 
# File 'lib/ronin/network/proxy.rb', line 302

def close!
  throw(:action,:close)
end

#close_client_connection(connection) ⇒ Object (protected)

This method is abstract.

Closes a client connection to the proxy.

Parameters:

  • connection (connection) —

    The client connection.

Since:

  • 0.5.0



428
429
 
# File 'lib/ronin/network/proxy.rb', line 428

def close_client_connection(connection)
end

#close_connection(client_connection, server_connection = nil) ⇒ Object (protected)

Closes both the client and server connections.

Parameters:

  • client_connection (connection) —

    The connection from the client to the proxy.

  • server_connection (connection) (defaults to: nil) —

    The connection from the proxy to the server.

Since:

  • 0.5.0



474
475
476
477
478
479
 
# File 'lib/ronin/network/proxy.rb', line 474

def close_connection(client_connection,server_connection=nil)
  close_server_connection(server_connection) if server_connection
  close_client_connection(client_connection)

  @connections.delete(client_connection)
end

#close_connections ⇒ Object (protected)

Closes all active connections.

Since:

  • 0.5.0



484
485
486
487
488
489
490
491
 
# File 'lib/ronin/network/proxy.rb', line 484

def close_connections
  @connections.each do |client_connection,server_connection|
    close_server_connection(server_connection)
    close_client_connection(client_connection)
  end

  @connections.clear
end

#close_proxy ⇒ Object (protected)

This method is abstract.

Closes the proxy.

Since:

  • 0.5.0



447
448
 
# File 'lib/ronin/network/proxy.rb', line 447

def close_proxy
end

#close_server_connection(connection) ⇒ Object (protected)

This method is abstract.

Closes a connection to the server.

Parameters:

  • connection (connection) —

    The server connection.

Since:

  • 0.5.0



439
440
 
# File 'lib/ronin/network/proxy.rb', line 439

def close_server_connection(connection)
end

#ignore! ⇒ Object

Causes the proxy to ignore a message.

Since:

  • 0.5.0



293
294
295
 
# File 'lib/ronin/network/proxy.rb', line 293

def ignore!
  throw(:action,:ignore)
end

#inspect ⇒ String

Inspects the proxy.

Returns:

  • (String) —

    The inspected proxy.

Since:

  • 0.5.0



403
404
405
 
# File 'lib/ronin/network/proxy.rb', line 403

def inspect
  "#<#{self.class}:#{self.object_id}: #{self}>"
end

#listen ⇒ Object

Polls the connections for data.

Since:

  • 0.5.0



185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/ronin/network/proxy.rb', line 185

def listen
  @listening = true

  while @listening
    begin
      poll
    rescue Interrupt
      @listening = false
      break
    end
  end
end

#on_client_data {|client, server, data| ... } ⇒ Object

Registers a callback for when a client sends data.

Yields:

  • (client, server, data)

Yield Parameters:

Since:

  • 0.5.0



256
257
258
 
# File 'lib/ronin/network/proxy.rb', line 256

def on_client_data(&block)
  @callbacks[:client_data] << block
end

#on_data {|client, server, data| ... } ⇒ Object

Registers a callback for when either the client or the server sends data.

Yields:

  • (client, server, data)

Yield Parameters:

Since:

  • 0.5.0



283
284
285
286
 
# File 'lib/ronin/network/proxy.rb', line 283

def on_data(&block)
  on_client_data(&block)
  on_server_data(&block)
end

#on_server_data {|client, server, data| ... } ⇒ Object

Registers a callback for when a server sends data.

Yields:

  • (client, server, data)

Yield Parameters:

Since:

  • 0.5.0



269
270
271
 
# File 'lib/ronin/network/proxy.rb', line 269

def on_server_data(&block)
  @callbacks[:server_data] << block
end

#open ⇒ Object

This method is abstract.

Opens the proxy.

Since:

  • 0.5.0



167
168
 
# File 'lib/ronin/network/proxy.rb', line 167

def open
end

#open_server_connection ⇒ connection (protected)

This method is abstract.

Creates a new connection to the server.

Returns:

  • (connection) —

    The new connection.

Since:

  • 0.5.0



417
418
 
# File 'lib/ronin/network/proxy.rb', line 417

def open_server_connection
end

#poll ⇒ Object

This method is abstract.

Polls the connections for data or errors.

Since:

  • 0.5.0



177
178
 
# File 'lib/ronin/network/proxy.rb', line 177

def poll
end

#recv(connection) ⇒ Object

This method is abstract.

Receives data from a connection.

Parameters:

  • connection (connection) —

    The connection.

Since:

  • 0.5.0



224
225
 
# File 'lib/ronin/network/proxy.rb', line 224

def recv(connection)
end

#reset! ⇒ Object

Causes the proxy to restart a connection.

Since:

  • 0.5.0



311
312
313
 
# File 'lib/ronin/network/proxy.rb', line 311

def reset!
  throw(:action,:reset)
end

#reset_connection(client_connection, server_connection) ⇒ Object (protected)

Resets a server connection.

Parameters:

  • client_connection (connection) —

    The connection from the client to the proxy.

  • server_connection (connection) —

    The connection from the proxy to the server.

Since:

  • 0.5.0



459
460
461
462
463
 
# File 'lib/ronin/network/proxy.rb', line 459

def reset_connection(client_connection,server_connection)
  close_server_connection(server_connection) if server_connection

  @connections[client_connection] = open_server_connection
end

#send(connection, data) ⇒ Object

This method is abstract.

Sends data to a connection.

Parameters:

  • connection (connection) —

    The connection.

  • data (String) —

    The data to send.

Since:

  • 0.5.0



211
212
 
# File 'lib/ronin/network/proxy.rb', line 211

def send(connection,data)
end

#server_connection_for(client_connection) ⇒ connection

Finds the connection to the server, associated with the client.

Parameters:

  • client_connection (connection) —

    The connection from the client.

Returns:

  • (connection) —

    The connection to the server.

Since:

  • 0.5.0



353
354
355
 
# File 'lib/ronin/network/proxy.rb', line 353

def server_connection_for(client_connection)
  @connections[client_connection]
end

#server_connections ⇒ Array<connection>

Connections to the server.

Returns:

  • (Array<connection>) —

    Server connections.

Since:

  • 0.5.0



340
341
342
 
# File 'lib/ronin/network/proxy.rb', line 340

def server_connections
  @connections.values
end

#server_data(client_connection, server_connection, data) ⇒ Object (protected)

Triggers the server_data event.

Parameters:

  • client_connection (connection) —

    The connection from a client to the proxy.

  • server_connection (connection) —

    The connection from the proxy to the server.

  • data (String) —

    The data sent from the server.

Since:

  • 0.5.0



570
571
572
573
574
 
# File 'lib/ronin/network/proxy.rb', line 570

def server_data(client_connection,server_connection,data)
  callback(:server_data,client_connection,server_connection,data) do
    send(client_connection,data)
  end
end

#start ⇒ Proxy

Starts the proxy and begins relaying data.

Returns:

  • (Proxy) —

    The proxy object.

Since:

  • 0.5.0



153
154
155
156
157
158
 
# File 'lib/ronin/network/proxy.rb', line 153

def start
  open
  listen
  close
  return self
end

#stop ⇒ Object

Stops the proxy from listening.

Since:

  • 0.5.0



242
243
244
245
 
# File 'lib/ronin/network/proxy.rb', line 242

def stop
  @listening = false
  return self
end

#stop! ⇒ Object

Causes the proxy to stop processing data entirely.

Since:

  • 0.5.0



320
321
322
 
# File 'lib/ronin/network/proxy.rb', line 320

def stop!
  throw(:action,:stop)
end

#to_s ⇒ String

Converts the proxy to a String.

Returns:

  • (String) —

    The String form of the proxy.

Since:

  • 0.5.0



393
394
395
 
# File 'lib/ronin/network/proxy.rb', line 393

def to_s
  "#{@host}:#{@port} <-> #{@server_host}:#{@server_port}"
end