class Ronin::Support::Network::Proxy

Base class for {TCP::Proxy TCP} and {UDP::Proxy 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

Constants

DEFAULT_BUFFER_SIZE
DEFAULT_HOST

Default host to bind to

Attributes

buffer_size[RW]

The size of read buffer

@return [Integer]

connections[R]

The connections maintained by the proxy

@return [Hash{Socket => Socket}]

host[R]

The host the proxy will listen on

@return [String]

port[R]

The port the proxy will listen on

@return [Integer]

server_host[R]

The remote port the proxy will relay data to

@return [String]

server_port[R]

The remote host the proxy will relay data to

@return [Integer]

Public Class Methods

new(host: DEFAULT_HOST, port: , server: , buffer_size: DEFAULT_BUFFER_SIZE) { |self| ... } click to toggle source

Creates a new Proxy.

@param [String] host

The host to listen on.

@param [Integer] port

The port to listen on.

@param [String, (host, port)] server

The server to forward connections to.

@param [Integer] buffer_size

The maximum amount of data to read in.

@yield [proxy]

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

@yieldparam [Proxy] proxy

The new Proxy object.

@example Proxies ‘0.0.0.0:1337` to `victim.com:80`:

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

@example Proxies ‘localhost:25` to `victim.com:25`:

Proxy.new(port: 25, host: 'localhost', server: 'victim.com')
# 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
start(**kwargs,&block) click to toggle source

Creates a new Proxy and begins relaying data.

@param [Hash{Symbol => Object}] kwargs

Additional keyword arguments for {#initialize}.

@see initialize

@api public

# File lib/ronin/support/network/proxy.rb, line 153
def self.start(**kwargs,&block)
  new(**kwargs,&block).start
end

Public Instance Methods

client_connection_for(server_connection) click to toggle source

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

@param [Socket] server_connection

The connection to the server.

@return [Socket]

The connection from the client.
# File lib/ronin/support/network/proxy.rb, line 406
def client_connection_for(server_connection)
  @connections.key(server_connection)
end
client_connections() click to toggle source

Connections from clients.

@return [Array<Socket>]

Client connections.
# File lib/ronin/support/network/proxy.rb, line 369
def client_connections
  @connections.keys
end
close() click to toggle source

Closes the proxy.

@api public

# File lib/ronin/support/network/proxy.rb, line 244
def close
  close_connections
  close_proxy
end
close!() click to toggle source

Causes the proxy to close a connection.

@api public

# File lib/ronin/support/network/proxy.rb, line 341
def close!
  throw(:action,:close)
end
ignore!() click to toggle source

Causes the proxy to ignore a message.

@api public

# File lib/ronin/support/network/proxy.rb, line 332
def ignore!
  throw(:action,:ignore)
end
inspect() click to toggle source

Inspects the proxy.

@return [String]

The inspected proxy.
# File lib/ronin/support/network/proxy.rb, line 426
def inspect
  "#<#{self.class}:#{self.object_id}: #{self}>"
end
listen() click to toggle source

Polls the connections for data.

@api public

# 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(&block) click to toggle source

Registers a callback for when a client sends data.

@yield [client, server, data]

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

@yieldparam [Socket] client

The connection to the client.

@yieldparam [Socket] server

The connection to the server.

@yieldparam [String] data

The recieved data.

@api public

# File lib/ronin/support/network/proxy.rb, line 277
def on_client_data(&block)
  @callbacks[:client_data] << block
end
on_data(&block) click to toggle source

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

@yield [client, server, data]

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

@yieldparam [Socket] client

The connection to the client.

@yieldparam [Socket] server

The connection to the server.

@yieldparam [String] data

The recieved data.

@api public

# 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(&block) click to toggle source

Registers a callback for when a server sends data.

@yield [client, server, data]

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

@yieldparam [Socket] client

The connection to the client.

@yieldparam [Socket] server

The connection to the server.

@yieldparam [String] data

The recieved data.

@api public

# File lib/ronin/support/network/proxy.rb, line 299
def on_server_data(&block)
  @callbacks[:server_data] << block
end
open() click to toggle source

Opens the proxy.

@api public

@abstract

# File lib/ronin/support/network/proxy.rb, line 179
def open
end
poll() click to toggle source

Polls the connections for data or errors.

@api public

@abstract

# File lib/ronin/support/network/proxy.rb, line 189
def poll
end
recv(connection) click to toggle source

Receives data from a connection.

@param [Socket] connection

The connection.

@api public

@abstract

# File lib/ronin/support/network/proxy.rb, line 236
def recv(connection)
end
reset!() click to toggle source

Causes the proxy to restart a connection.

@api public

# File lib/ronin/support/network/proxy.rb, line 350
def reset!
  throw(:action,:reset)
end
send(connection,data) click to toggle source

Sends data to a connection.

@param [Socket] connection

The connection.

@param [String] data

The data to send.

@api public

@abstract

# File lib/ronin/support/network/proxy.rb, line 223
def send(connection,data)
end
server_connection_for(client_connection) click to toggle source

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

@param [Socket] client_connection

The connection from the client.

@return [Socket]

The connection to the server.
# File lib/ronin/support/network/proxy.rb, line 392
def server_connection_for(client_connection)
  @connections[client_connection]
end
server_connections() click to toggle source

Connections to the server.

@return [Array<Socket>]

Server connections.
# File lib/ronin/support/network/proxy.rb, line 379
def server_connections
  @connections.values
end
start() click to toggle source

Starts the proxy and begins relaying data.

@return [Proxy]

The proxy object.

@api public

# File lib/ronin/support/network/proxy.rb, line 165
def start
  open
  listen
  close
  return self
end
stop() click to toggle source

Stops the proxy from listening.

@api public

# File lib/ronin/support/network/proxy.rb, line 254
def stop
  @listening = false
  return self
end
stop!() click to toggle source

Causes the proxy to stop processing data entirely.

@api public

# File lib/ronin/support/network/proxy.rb, line 359
def stop!
  throw(:action,:stop)
end
to_s() click to toggle source

Converts the proxy to a String.

@return [String]

The String form of the proxy.
# File lib/ronin/support/network/proxy.rb, line 416
def to_s
  "#{@host}:#{@port} <-> #{@server_host}:#{@server_port}"
end

Protected Instance Methods

callback(event,client_connection,server_connection=nil,data=nil) { || ... } click to toggle source

Triggers the callbacks registered for an event.

@param [Symbol] event

The event being triggered.

@param [Socket] client_connection

The connection from the client to the proxy.

@param [Socket] server_connection

The connection from the proxy to the server.

@param [String] data

The data being sent.

@yield []

If none of the callbacks interrupted the event, the given block
will be called.
# 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_data(client_connection,server_connection,data) click to toggle source

Triggers the ‘client_data` event.

@param [Socket] client_connection

The connection from a client to the proxy.

@param [Socket] server_connection

The connection from the proxy to the server.

@param [String] data

The data sent by the client.
# 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_client_connection(connection) click to toggle source

Closes a client connection to the proxy.

@param [Socket] connection

The client connection.

@abstract

# File lib/ronin/support/network/proxy.rb, line 451
def close_client_connection(connection)
end
close_connection(client_connection,server_connection=nil) click to toggle source

Closes both the client and server connections.

@param [Socket] client_connection

The connection from the client to the proxy.

@param [Socket] server_connection

The connection from the proxy to the server.
# 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() click to toggle source

Closes all active connections.

# 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() click to toggle source

Closes the proxy.

@abstract

# File lib/ronin/support/network/proxy.rb, line 470
def close_proxy
end
close_server_connection(connection) click to toggle source

Closes a connection to the server.

@param [Socket] connection

The server connection.

@abstract

# File lib/ronin/support/network/proxy.rb, line 462
def close_server_connection(connection)
end
open_server_connection() click to toggle source

Creates a new connection to the server.

@return [Socket]

The new connection.

@abstract

# File lib/ronin/support/network/proxy.rb, line 440
def open_server_connection
end
reset_connection(client_connection,server_connection) click to toggle source

Resets a server connection.

@param [Socket] client_connection

The connection from the client to the proxy.

@param [Socket] server_connection

The connection from the proxy to the server.
# 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
server_data(client_connection,server_connection,data) click to toggle source

Triggers the ‘server_data` event.

@param [Socket] client_connection

The connection from a client to the proxy.

@param [Socket] server_connection

The connection from the proxy to the server.

@param [String] data

The data sent from the server.
# 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