ronin-support 0.4.1 → 0.5.0.rc1

data/lib/ronin/network/mixins/unix.rb

@@ -0,0 +1,279 @@
+#
+# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of Ronin Support.
+#
+# Ronin Support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ronin Support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'ronin/network/mixins/mixin'
+require 'ronin/network/unix'
+
+module Ronin
+  module Network
+    module Mixins
+      #
+      # Adds UNIX Socket convenience methods and connection parameters to a
+      # class.
+      #
+      # Defines the following parameters:
+      #
+      # * `path` (`String`) - UNIX Socket path.
+      #
+      # @since 0.5.0
+      #
+      module UNIX
+        include Mixin, Network::UNIX
+
+        # UNIX path
+        parameter :path, :type        => String,
+                         :description => 'UNIX Socket path'
+
+        protected
+
+        #
+        # Connects to a UNIX socket specified by the `path` parameter.
+        #
+        # @yield [socket]
+        #   If a block is given, it will be passed an UNIX socket object.
+        #
+        # @yieldparam [UNIXSocket] socket
+        #   The UNIX socket.
+        #
+        # @return [UNIXSocket]
+        #   The UNIX socket.
+        #
+        # @example
+        #   socket = unix_connect
+        #
+        # @see Network::UNIX#unix_connect
+        #
+        # @api public
+        #
+        def unix_connect(&block)
+          print_info "Connecting to #{self.path} ..."
+
+          super(self.path,&block)
+        end
+
+        #
+        # Creates a new UNIXSocket object, connected to the `path` parameter.
+        # The given data will then be written to the newly created UNIXSocket.
+        #
+        # @param [String] data
+        #   The data to send to the socket.
+        #
+        # @yield [socket]
+        #   If a block is given, it will be passed the newly created socket.
+        #
+        # @yieldparam [UNIXSocket] socket
+        #   The newly created UNIXSocket object.
+        #
+        # @return [UNIXSocket]
+        #   The newly created UNIXSocket object.
+        #
+        # @see Network::UNIX#unix_connect_and_send
+        #
+        # @api public
+        #
+        def unix_connect_and_send(data,&block)
+          print_info "Connecting to #{self.path} ..."
+          print_debug "Sending data: #{data.inspect}"
+
+          return super(data,self.path,&block)
+        end
+
+        #
+        # Creates a UNIX session to the host and port specified by the
+        # `host` and `port` parameters. If the `local_host` and `local_port`
+        # parameters are set, they will be used for the local host and port
+        # of the UNIX connection.
+        #
+        # @yield [socket]
+        #   If a block is given, it will be passed the newly created socket.
+        #   After the block has returned, the socket will then be closed.
+        #
+        # @yieldparam [UNIXsocket] socket
+        #   The newly created UNIXSocket object.
+        #
+        # @see Network::UNIX#unix_session
+        #
+        # @api public
+        #
+        def unix_session(&block)
+          print_info "Connecting to #{self.path} ..."
+
+          super(self.host,&block)
+
+          print_info "Disconnected from #{self.path}"
+          return nil
+        end
+
+        #
+        # Connects to the UNIX socket, specified by the `path` parameter,
+        # sends the given data and then disconnects.
+        #
+        # @param [String] data
+        #   The data to send to the UNIX socket.
+        #
+        # @return [true]
+        #   The data was successfully sent.
+        #
+        # @example
+        #   buffer = "GET /" + ('A' * 4096) + "\n\r"
+        #   unix_send(buffer)
+        #   # => true
+        #
+        # @see Network::UNIX#unix_send
+        #
+        # @api public
+        #
+        # @since 0.4.0
+        #
+        def unix_send(data)
+          print_info "Connecting to #{self.path} ..."
+          print_debug "Sending data: #{data.inspect}"
+
+          super(data,self.path,&block)
+
+          print_info "Disconnected from #{self.path}"
+          return true
+        end
+
+        #
+        # Opens a UNIX socket, listening on the `path` parameter.
+        #
+        # @yield [server]
+        #   The given block will be passed the newly created server.
+        #
+        # @yieldparam [UNIXServer] server
+        #   The newly created server.
+        #
+        # @return [UNIXServer]
+        #   The newly created server.
+        #
+        # @example
+        #   unix_server
+        #
+        # @see Network::UNIX#unix_server
+        #
+        # @api public
+        #
+        def unix_server(&block)
+          print_info "Listening on #{self.path} ..."
+
+          return super(self.path,&block)
+        end
+
+        #
+        # Opens a UNIX socket temporarily, listening on the `path` parameter.
+        #
+        # @yield [server]
+        #   The given block will be passed the newly created server.
+        #   When the block has finished, the server will be closed.
+        #
+        # @yieldparam [UNIXServer] server
+        #   The newly created server.
+        #
+        # @return [nil]
+        #
+        # @example
+        #   unix_server_session do |server|
+        #     # ...
+        #   end
+        #
+        # @see Network::UNIX#unix_server_session
+        #
+        # @api public
+        #
+        def unix_server_session(&block)
+          print_info "Listening on #{self.path} ..."
+
+          super(self.path,&block)
+
+          print_info "Closed #{self.path}"
+          return nil
+        end
+
+        #
+        # Opens a UNIX socket specified by the `path` parameter,
+        # accepts a connection, then closes the socket.
+        #
+        # @yield [client]
+        #   If a block is given, it will be passed the accepted connection.
+        #
+        # @yieldparam [UNIXSocket] client
+        #   The accepted connection to UNIX socket.
+        #
+        # @example
+        #   unix_accept do |client|
+        #     # ...
+        #   end
+        #
+        # @see Network::UNIX#unix_accept
+        #
+        # @api public
+        #
+        def unix_accept
+          print_info "Listening on #{self.path} ..."
+
+          super(self.path) do |client|
+            print_info "Client connected to #{self.path}"
+
+            yield client if block_given?
+
+            print_info "Client disconnecting from #{self.path} ..."
+          end
+
+          print_info "Closed #{self.path}"
+          return nil
+        end
+
+        #
+        # Opens a UNIX socket specified by the `path` parameter,
+        # accepts connections in a loop.
+        #
+        # @yield [client]
+        #   If a block is given, it will be passed each accepted connection.
+        #
+        # @yieldparam [UNIXSocket] client
+        #   An accepted connection to UNIX socket.
+        #
+        # @example
+        #   unix_server_loop do |client|
+        #     # ...
+        #   end
+        #
+        # @see Network::UNIX#unix_server_loop
+        #
+        # @api public
+        #
+        def unix_server_loop
+          print_info "Listening on #{self.path} ..."
+
+          super(self.path) do |client|
+            print_info "Client connected: #{self.path}"
+
+            yield client if block_given?
+
+            print_info "Client disconnecting: #{self.path} ..."
+          end
+
+          print_info "Closed #{self.path}"
+          return nil
+        end
+      end
+    end
+  end
+end

data/lib/ronin/network/pop3.rb

@@ -34,7 +34,7 @@ module Ronin
       #
       # @api public
       #
-      def POP3.default_port
+      def self.default_port
         @default_port ||= DEFAULT_PORT
       end
 
@@ -46,7 +46,7 @@ module Ronin
       #
       # @api public
       #
-      def POP3.default_port=(port)
+      def self.default_port=(port)
         @default_port = port
       end
 
@@ -80,9 +80,9 @@ module Ronin
       # @api public
       #
       def pop3_connect(host,options={})
-        host = host.to_s
-        port = (options[:port] || POP3.default_port)
-        user = options[:user]
+        host     = host.to_s
+        port     = (options[:port] || POP3.default_port)
+        user     = options[:user]
         password = options[:password]
 
         session = Net::POP3.start(host,port,user,password)

data/lib/ronin/network/proxy.rb

@@ -0,0 +1,578 @@
+#
+# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# This file is part of Ronin Support.
+#
+# Ronin Support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ronin Support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Network
+    #
+    # 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.
+    #
+    # * {#ignore!}
+    # * {#close!}
+    # * {#reset!}
+    #
+    # @since 0.5.0
+    #
+    class Proxy
+
+      # Default host to bind to
+      DEFAULT_HOST = '0.0.0.0'
+
+      DEFAULT_BUFFER_SIZE = 4096
+
+      # The host the proxy will listen on
+      attr_reader :host
+
+      # The port the proxy will listen on
+      attr_reader :port
+
+      # The remote port the proxy will relay data to
+      attr_reader :server_host
+
+      # The remote host the proxy will relay data to
+      attr_reader :server_port
+
+      # The size of read buffer
+      attr_accessor :buffer_size
+
+      # The connections maintained by the proxy
+      attr_reader :connections
+
+      #
+      # Creates a new Proxy.
+      #
+      # @param [Hash] options
+      #   Options for the proxy.
+      #
+      # @option options [String] :host (DEFAULT_HOST)
+      #   The host to listen on.
+      #
+      # @option options [Integer] :port
+      #   The port to listen on.
+      #
+      # @option options [String, (host, port)] :server
+      #   The server to forward connections to.
+      #
+      # @option options [Integer] :buffer_size (DEFAULT_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')
+      #
+      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
+
+      #
+      # Creates a new Proxy and begins relaying data.
+      #
+      # @see #initialize
+      #
+      # @api public
+      #
+      def self.start(options={},&block)
+        new(options,&block).start
+      end
+
+      #
+      # Starts the proxy and begins relaying data.
+      #
+      # @return [Proxy]
+      #   The proxy object.
+      #
+      # @api public
+      #
+      def start
+        open
+        listen
+        close
+        return self
+      end
+
+      #
+      # Opens the proxy.
+      #
+      # @api public
+      #
+      # @abstract
+      #
+      def open
+      end
+
+      #
+      # Polls the connections for data or errors.
+      #
+      # @api public
+      #
+      # @abstract
+      #
+      def poll
+      end
+
+      #
+      # Polls the connections for data.
+      #
+      # @api public
+      #
+      def listen
+        @listening = true
+
+        while @listening
+          begin
+            poll
+          rescue Interrupt
+            @listening = false
+            break
+          end
+        end
+      end
+
+      #
+      # Sends data to a connection.
+      #
+      # @param [connection] connection
+      #   The connection.
+      #
+      # @param [String] data
+      #   The data to send.
+      #
+      # @api public
+      #
+      # @abstract
+      #
+      def send(connection,data)
+      end
+
+      #
+      # Receives data from a connection.
+      #
+      # @param [connection] connection
+      #   The connection.
+      #
+      # @api public
+      #
+      # @abstract
+      #
+      def recv(connection)
+      end
+
+      #
+      # Closes the proxy.
+      #
+      # @api public
+      # 
+      def close
+        close_connections
+        close_proxy
+      end
+
+      #
+      # Stops the proxy from listening.
+      #
+      # @api public
+      #
+      def stop
+        @listening = false
+        return self
+      end
+
+      #
+      # Registers a callback for when a client sends data.
+      #
+      # @yield [client, server, data]
+      #
+      # @yieldparam [String] data
+      #
+      # @api public
+      #
+      def on_client_data(&block)
+        @callbacks[:client_data] << block
+      end
+
+      #
+      # Registers a callback for when a server sends data.
+      #
+      # @yield [client, server, data]
+      #
+      # @yieldparam [String] data
+      #
+      # @api public
+      #
+      def on_server_data(&block)
+        @callbacks[:server_data] << block
+      end
+
+      #
+      # Registers a callback for when either the client or the server sends
+      # data.
+      #
+      # @yield [client, server, data]
+      #
+      # @yieldparam [String] data
+      #
+      # @api public
+      #
+      def on_data(&block)
+        on_client_data(&block)
+        on_server_data(&block)
+      end
+
+      #
+      # Causes the proxy to ignore a message.
+      #
+      # @api public
+      #
+      def ignore!
+        throw(:action,:ignore)
+      end
+
+      #
+      # Causes the proxy to close a connection.
+      #
+      # @api public
+      #
+      def close!
+        throw(:action,:close)
+      end
+
+      #
+      # Causes the proxy to restart a connection.
+      #
+      # @api public
+      #
+      def reset!
+        throw(:action,:reset)
+      end
+
+      #
+      # Causes the proxy to stop processing data entirely.
+      #
+      # @api public
+      #
+      def stop!
+        throw(:action,:stop)
+      end
+
+      #
+      # Connections from clients.
+      #
+      # @return [Array<connection>]
+      #   Client connections.
+      #
+      def client_connections
+        @connections.keys
+      end
+
+      #
+      # Connections to the server.
+      #
+      # @return [Array<connection>]
+      #   Server connections.
+      #
+      def server_connections
+        @connections.values
+      end
+
+      #
+      # Finds the connection to the server, associated with the client.
+      #
+      # @param [connection] client_connection
+      #   The connection from the client.
+      #
+      # @return [connection]
+      #   The connection to the server.
+      #
+      def server_connection_for(client_connection)
+        @connections[client_connection]
+      end
+
+      if RUBY_VERSION < '1.9.'
+        #
+        # Finds the connection from the client, associated with the server
+        # connection.
+        #
+        # @param [connection] server_connection
+        #   The connection to the server.
+        #
+        # @return [connection]
+        #   The connection from the client.
+        #
+        def client_connection_for(server_connection)
+          @connections.index(server_connection)
+        end
+      else
+        #
+        # Finds the connection from the client, associated with the server
+        # connection.
+        #
+        # @param [connection] server_connection
+        #   The connection to the server.
+        #
+        # @return [connection]
+        #   The connection from the client.
+        #
+        def client_connection_for(server_connection)
+          @connections.key(server_connection)
+        end
+      end
+
+      #
+      # Converts the proxy to a String.
+      #
+      # @return [String]
+      #   The String form of the proxy.
+      #
+      def to_s
+        "#{@host}:#{@port} <-> #{@server_host}:#{@server_port}"
+      end
+
+      #
+      # Inspects the proxy.
+      #
+      # @return [String]
+      #   The inspected proxy.
+      #
+      def inspect
+        "#<#{self.class}:#{self.object_id}: #{self}>"
+      end
+
+      protected
+
+      #
+      # Creates a new connection to the server.
+      #
+      # @return [connection]
+      #   The new connection.
+      #
+      # @abstract
+      #
+      def open_server_connection
+      end
+
+      #
+      # Closes a client connection to the proxy.
+      #
+      # @param [connection] connection
+      #   The client connection.
+      #
+      # @abstract
+      #
+      def close_client_connection(connection)
+      end
+
+      #
+      # Closes a connection to the server.
+      #
+      # @param [connection] connection
+      #   The server connection.
+      #
+      # @abstract
+      #
+      def close_server_connection(connection)
+      end
+
+      #
+      # Closes the proxy.
+      #
+      # @abstract
+      #
+      def close_proxy
+      end
+
+      #
+      # Resets a server connection.
+      #
+      # @param [connection] client_connection
+      #   The connection from the client to the proxy.
+      #
+      # @param [connection] server_connection
+      #   The connection from the proxy to the server.
+      #
+      def reset_connection(client_connection,server_connection)
+        close_server_connection(server_connection) if server_connection
+
+        @connections[client_connection] = open_server_connection
+      end
+
+      #
+      # Closes both the client and server connections.
+      #
+      # @param [connection] client_connection
+      #   The connection from the client to the proxy.
+      #
+      # @param [connection] server_connection
+      #   The connection from the proxy to the server.
+      #
+      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
+
+      #
+      # Closes all active connections.
+      #
+      def close_connections
+        @connections.each do |client_connection,server_connection|
+          close_server_connection(server_connection)
+          close_client_connection(client_connection)
+        end
+
+        @connections.clear
+      end
+
+      #
+      # Triggers the callbacks registered for an event.
+      #
+      # @param [Symbol] event
+      #   The event being triggered.
+      #
+      # @param [connection] client_connection
+      #   The connection from the client to the proxy.
+      #
+      # @param [connection] 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.
+      #
+      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
+
+      #
+      # Triggers the `client_data` event.
+      #
+      # @param [connection] client_connection
+      #   The connection from a client to the proxy.
+      #
+      # @param [connection] server_connection
+      #   The connection from the proxy to the server.
+      #
+      # @param [String] data
+      #   The data sent by the client.
+      #
+      def client_data(client_connection,server_connection,data)
+        callback(:client_data,client_connection,server_connection,data) do
+          send(server_connection,data)
+        end
+      end
+
+      #
+      # Triggers the `server_data` event.
+      #
+      # @param [connection] client_connection
+      #   The connection from a client to the proxy.
+      #
+      # @param [connection] server_connection
+      #   The connection from the proxy to the server.
+      #
+      # @param [String] data
+      #   The data sent from the server.
+      #
+      def server_data(client_connection,server_connection,data)
+        callback(:server_data,client_connection,server_connection,data) do
+          send(client_connection,data)
+        end
+      end
+
+    end
+  end
+end