Class: Ronin::Support::Network::Proxy

Inherits:
Object
  • Object
show all
Defined in:
lib/ronin/support/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(host: DEFAULT_HOST, port:, server:, buffer_size: DEFAULT_BUFFER_SIZE) {|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:

  • host (String) (defaults to: 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) (defaults to: 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



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/ronin/support/network/proxy.rb', line 125

def initialize(host: DEFAULT_HOST,
               port: ,
               server: ,
               buffer_size: DEFAULT_BUFFER_SIZE)
  @host = host
  @port = port

  @server_host, @server_port = server
  @server_port             ||= @port

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

  @buffer_size = buffer_size
  @connections = {}

  yield self if block_given?
end

Instance Attribute Details

#buffer_size ⇒ Integer

The size of read buffer

Returns:

Since:

  • 0.5.0



90
91
92
 
# File 'lib/ronin/support/network/proxy.rb', line 90

def buffer_size
  @buffer_size
end

#connections ⇒ Hash{Socket => Socket} (readonly)

The connections maintained by the proxy

Returns:

  • (Hash{Socket => Socket})

Since:

  • 0.5.0



95
96
97
 
# File 'lib/ronin/support/network/proxy.rb', line 95

def connections
  @connections
end

#host ⇒ String (readonly)

The host the proxy will listen on

Returns:

Since:

  • 0.5.0



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

def host
  @host
end

#port ⇒ Integer (readonly)

The port the proxy will listen on

Returns:

Since:

  • 0.5.0



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

def port
  @port
end

#server_host ⇒ String (readonly)

The remote port the proxy will relay data to

Returns:

Since:

  • 0.5.0



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

def server_host
  @server_host
end

#server_port ⇒ Integer (readonly)

The remote host the proxy will relay data to

Returns:

Since:

  • 0.5.0



85
86
87
 
# File 'lib/ronin/support/network/proxy.rb', line 85

def server_port
  @server_port
end

Class Method Details

.start(**kwargs, &block) ⇒ Object

Creates a new Proxy and begins relaying data.

Parameters:

  • kwargs (Hash{Symbol => Object}) —

    Additional keyword arguments for #initialize.

See Also:

Since:

  • 0.5.0



153
154
155
 
# File 'lib/ronin/support/network/proxy.rb', line 153

def self.start(**kwargs,&block)
  new(**kwargs,&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 (Socket) —

    The connection from the client to the proxy.

  • server_connection (Socket) (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



535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/ronin/support/network/proxy.rb', line 535

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) ⇒ Socket

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

Parameters:

  • server_connection (Socket) —

    The connection to the server.

Returns:

  • (Socket) —

    The connection from the client.

Since:

  • 0.5.0



406
407
408
 
# File 'lib/ronin/support/network/proxy.rb', line 406

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

#client_connections ⇒ Array<Socket>

Connections from clients.

Returns:

  • (Array<Socket>) —

    Client connections.

Since:

  • 0.5.0



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

def client_connections
  @connections.keys
end

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

Triggers the client_data event.

Parameters:

  • client_connection (Socket) —

    The connection from a client to the proxy.

  • server_connection (Socket) —

    The connection from the proxy to the server.

  • data (String) —

    The data sent by the client.

Since:

  • 0.5.0



575
576
577
578
579
 
# File 'lib/ronin/support/network/proxy.rb', line 575

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



244
245
246
247
 
# File 'lib/ronin/support/network/proxy.rb', line 244

def close
  close_connections
  close_proxy
end

#close! ⇒ Object

Causes the proxy to close a connection.

Since:

  • 0.5.0



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

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 (Socket) —

    The client connection.

Since:

  • 0.5.0



451
452
 
# File 'lib/ronin/support/network/proxy.rb', line 451

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 (Socket) —

    The connection from the client to the proxy.

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

    The connection from the proxy to the server.

Since:

  • 0.5.0



497
498
499
500
501
502
 
# File 'lib/ronin/support/network/proxy.rb', line 497

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



507
508
509
510
511
512
513
514
 
# File 'lib/ronin/support/network/proxy.rb', line 507

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



470
471
 
# File 'lib/ronin/support/network/proxy.rb', line 470

def close_proxy
end

#close_server_connection(connection) ⇒ Object (protected)

This method is abstract.

Closes a connection to the server.

Parameters:

  • connection (Socket) —

    The server connection.

Since:

  • 0.5.0



462
463
 
# File 'lib/ronin/support/network/proxy.rb', line 462

def close_server_connection(connection)
end

#ignore! ⇒ Object

Causes the proxy to ignore a message.

Since:

  • 0.5.0



332
333
334
 
# File 'lib/ronin/support/network/proxy.rb', line 332

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

#inspect ⇒ String

Inspects the proxy.

Returns:

  • (String) —

    The inspected proxy.

Since:

  • 0.5.0



426
427
428
 
# File 'lib/ronin/support/network/proxy.rb', line 426

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

#listen ⇒ Object

Polls the connections for data.

Since:

  • 0.5.0



197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/ronin/support/network/proxy.rb', line 197

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) —

    The given block will be passed the client connection, the server connection, and the received data.

Yield Parameters:

  • client (Socket) —

    The connection to the client.

  • server (Socket) —

    The connection to the server.

  • data (String) —

    The recieved data.

Since:

  • 0.5.0



277
278
279
 
# File 'lib/ronin/support/network/proxy.rb', line 277

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) —

    The given block will be passed the client connection, the server connection, and the received data.

Yield Parameters:

  • client (Socket) —

    The connection to the client.

  • server (Socket) —

    The connection to the server.

  • data (String) —

    The recieved data.

Since:

  • 0.5.0



322
323
324
325
 
# File 'lib/ronin/support/network/proxy.rb', line 322

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) —

    The given block will be passed the client connection, the server connection, and the received data.

Yield Parameters:

  • client (Socket) —

    The connection to the client.

  • server (Socket) —

    The connection to the server.

  • data (String) —

    The recieved data.

Since:

  • 0.5.0



299
300
301
 
# File 'lib/ronin/support/network/proxy.rb', line 299

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

#open ⇒ Object

This method is abstract.

Opens the proxy.

Since:

  • 0.5.0



179
180
 
# File 'lib/ronin/support/network/proxy.rb', line 179

def open
end

#open_server_connection ⇒ Socket (protected)

This method is abstract.

Creates a new connection to the server.

Returns:

  • (Socket) —

    The new connection.

Since:

  • 0.5.0



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

def open_server_connection
end

#poll ⇒ Object

This method is abstract.

Polls the connections for data or errors.

Since:

  • 0.5.0



189
190
 
# File 'lib/ronin/support/network/proxy.rb', line 189

def poll
end

#recv(connection) ⇒ Object

This method is abstract.

Receives data from a connection.

Parameters:

  • connection (Socket) —

    The connection.

Since:

  • 0.5.0



236
237
 
# File 'lib/ronin/support/network/proxy.rb', line 236

def recv(connection)
end

#reset! ⇒ Object

Causes the proxy to restart a connection.

Since:

  • 0.5.0



350
351
352
 
# File 'lib/ronin/support/network/proxy.rb', line 350

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

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

Resets a server connection.

Parameters:

  • client_connection (Socket) —

    The connection from the client to the proxy.

  • server_connection (Socket) —

    The connection from the proxy to the server.

Since:

  • 0.5.0



482
483
484
485
486
 
# File 'lib/ronin/support/network/proxy.rb', line 482

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 (Socket) —

    The connection.

  • data (String) —

    The data to send.

Since:

  • 0.5.0



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

def send(connection,data)
end

#server_connection_for(client_connection) ⇒ Socket

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

Parameters:

  • client_connection (Socket) —

    The connection from the client.

Returns:

  • (Socket) —

    The connection to the server.

Since:

  • 0.5.0



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

def server_connection_for(client_connection)
  @connections[client_connection]
end

#server_connections ⇒ Array<Socket>

Connections to the server.

Returns:

  • (Array<Socket>) —

    Server connections.

Since:

  • 0.5.0



379
380
381
 
# File 'lib/ronin/support/network/proxy.rb', line 379

def server_connections
  @connections.values
end

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

Triggers the server_data event.

Parameters:

  • client_connection (Socket) —

    The connection from a client to the proxy.

  • server_connection (Socket) —

    The connection from the proxy to the server.

  • data (String) —

    The data sent from the server.

Since:

  • 0.5.0



593
594
595
596
597
 
# File 'lib/ronin/support/network/proxy.rb', line 593

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



165
166
167
168
169
170
 
# File 'lib/ronin/support/network/proxy.rb', line 165

def start
  open
  listen
  close
  return self
end

#stop ⇒ Object

Stops the proxy from listening.

Since:

  • 0.5.0



254
255
256
257
 
# File 'lib/ronin/support/network/proxy.rb', line 254

def stop
  @listening = false
  return self
end

#stop! ⇒ Object

Causes the proxy to stop processing data entirely.

Since:

  • 0.5.0



359
360
361
 
# File 'lib/ronin/support/network/proxy.rb', line 359

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



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

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