ronin 0.2.4 → 0.3.0

data/lib/ronin/network/extensions/telnet.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/network/extensions/telnet/net'

data/lib/ronin/network/extensions/telnet/net.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/network/telnet'
@@ -27,47 +24,70 @@ require 'net/telnet'
 
 module Net
   #
-  # Creates a new Telnet object with the specified _host_, given port
-  # and the given _options_. If a _block_ is given, it will be passed
-  # the newly created Telnet object.
-  #
-  # _options_ may contain the following keys:
-  # <tt>:port</tt>:: The port to connect to. Defaults to
-  #                  <tt>Ronin::Network::Telnet.default_port</tt>, if not
-  #                  given.
-  # <tt>:binmode</tt>:: Indicates that newline substitution shall not
-  #                     be performed.
-  # <tt>:output_log</tt>:: The name of the file to write connection
-  #                        status messages and all received traffic to.
-  # <tt>:dump_log</tt>:: Similar to the <tt>:output_log</tt> option,
-  #                      but connection output is also written in
-  #                      hexdump format.
-  # <tt>:prompt</tt>:: A regular expression matching the host's
-  #                    command-line prompt sequence, used to determine
-  #                    when a command has finished. Defaults to
-  #                    <tt>Ronin::Network::Telnet.default_prompt</tt>, if
-  #                    not given.
-  # <tt>:telnet</tt>:: Indicates that the connection shall behave as a
-  #                    telnet connection. Defaults to +true+.
-  # <tt>:plain</tt>:: Indicates that the connection shall behave as a
-  #                   normal TCP connection.
-  # <tt>:timeout</tt>:: The number of seconds to wait before timing out
-  #                     both the initial attempt to connect to host,
-  #                     and all attempts to read data from the host.
-  #                     Defaults to
-  #                     <tt>Ronin::Network::Telnet.default_timeout</tt>,
-  #                     if not given.
-  # <tt>:wait_time</tt>:: The amount of time to wait after seeing what
-  #                       looks like a prompt.
-  # <tt>:proxy</tt>:: A proxy object to used instead of opening a
-  #                   direct connection to the host. Must be either
-  #                   another telnet object or an IO object.
-  #                   Defaults to
-  #                   <tt>Ronin::Network::Telnet.proxy</tt>, if not given.
-  # <tt>:user</tt>:: The user to login with.
-  # <tt>:password</tt>:: The password to login with.
-  #
-  #   Telnet.connect('towel.blinkenlights.nl') # => Telnet
+  # Creates a new Telnet connection.
+  #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Integer] :port (Ronin::Network::Telnet.default_port)
+  #   The port to connect to.
+  #
+  # @option options [Boolean] :binmode
+  #   Indicates that newline substitution shall not be performed.
+  #
+  # @option options [String] :output_log
+  #   The name of the file to write connection status messages and all
+  #   received traffic to.
+  #
+  # @option options [String] :dump_log
+  #   Similar to the +:output_log+ option, but connection output is also
+  #   written in hexdump format.
+  #
+  # @option options [Regexp] :prompt (Ronin::Network::Telnet.default_prompt)
+  #   A regular expression matching the host command-line prompt sequence,
+  #   used to determine when a command has finished.
+  #
+  # @option options [Boolean] :telnet (true)
+  #   Indicates that the connection shall behave as a telnet connection.
+  #
+  # @option options [Boolean] :plain
+  #   Indicates that the connection shall behave as a normal TCP
+  #   connection.
+  #
+  # @option options [Integer] :timeout (Ronin::Network::Telnet.default_timeout)
+  #   The number of seconds to wait before timing out both the initial
+  #   attempt to connect to host, and all attempts to read data from the
+  #   host.
+  #
+  # @option options [Integer] :wait_time
+  #   The amount of time to wait after seeing what looks like a prompt.
+  #
+  # @option options [Net::Telnet, IO] :proxy (Ronin::Network::Telnet.proxy)
+  #   A proxy object to used instead of opening a direct connection to the
+  #   host.
+  #
+  # @option options [String] :user
+  #   The user to login as.
+  #
+  # @option options [String] :password
+  #   The password to login with.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed the newly created Telnet
+  #   session.
+  #
+  # @yieldparam [Net::Telnet] session
+  #   The newly created Telnet session.
+  #
+  # @return [Net::Telnet]
+  #   The Telnet session
+  #
+  # @example
+  #   Net.telnet_connect('towel.blinkenlights.nl')
+  #   # => #<Net::Telnet: ...>
   #
   def Net.telnet_connect(host,options={},&block)
     sess_opts = {}
@@ -97,17 +117,29 @@ module Net
   end
 
   #
-  # Creates a new Telnet object with the specified _host, given port
-  # and the given _options_. See telnet for a complete listing the
-  # _options_. If a _block_ is given, it will be passed the newly
-  # created Telnet object. After the telnet connection has been
-  # established, and the given _block_ has completed, the connection
-  # is then closed.
+  # Starts a new Telnet session.
   #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed the newly created
+  #   Telnet session. After the block has returned, the Telnet session
+  #   will be closed.
+  #
+  # @yieldparam [Net::Telnet] session
+  #   The newly created Telnet session.
+  #
+  # @example
   #   Net.telnet_session('towel.blinkenlights.nl') do |movie|
   #     movie.each_line { |line| puts line }
   #   end
   #
+  # @see Net.telnet_session
+  #
   def Net.telnet_session(host,options={},&block)
     Net.telnet_connect(host,options) do |sess|
       block.call(sess) if block

data/lib/ronin/network/extensions/udp.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,7 +16,6 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/network/extensions/udp/net'

data/lib/ronin/network/extensions/udp/net.rb

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,38 +16,83 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'socket'
 
 module Net
   #
-  # Creates a new UDPSocket object with the specified _rhost_, _rport_
-  # and the given _lhost_ and _lport_. If _block_ is given, it will be
-  # passed the newly created UDPSocket object.
+  # Creates a new UDPSocket object with the specified _host_, _port_
+  # and the given _local_host_ and _local_port_.
   #
-  #   Net.udp_connect('www.hackety.org',80) # => UDPSocket
+  # @param [String] host
+  #   The host to connect to.
   #
+  # @param [Integer] port
+  #   The port to connect to.
+  #
+  # @param [String] local_host
+  #   The local host to bind to.
+  #
+  # @param [Integer] local_port
+  #   The local port to bind to.
+  #
+  # @yield [socket]
+  #   If a block is given, it will be passed the newly created socket.
+  #
+  # @yieldparam [UDPsocket] socket
+  #   The newly created UDPSocket object.
+  #
+  # @return [UDPSocket]
+  #   The newly created UDPSocket object.
+  #
+  # @example
+  #   Net.udp_connect('www.hackety.org',80)
+  #   # => UDPSocket
+  #
+  # @example
   #   Net.udp_connect('www.wired.com',80) do |sock|
   #     puts sock.readlines
   #   end
   #
-  def Net.udp_connect(rhost,rport,lhost=nil,lport=nil,&block)
-    sock = UDPSocket.new(@rhost,@rport,@lhost,@lport)
+  def Net.udp_connect(host,port,local_host=nil,local_port=nil,&block)
+    sock = UDPSocket.new(host,port,local_host,local_port)
     block.call(sock) if block
 
     return sock
   end
 
   #
-  # Creates a new UDPSocket object with the specified _rhost_ 
-  # _rport_, and the given _lhost_ and _lport_. The specified _data_ will
-  # then be written to the newly created UDPSocket. If a _block_ is given
-  # it will be passed the UDPSocket object.
+  # Creates a new UDPSocket object with the specified _host_, _port_, and
+  # the given _local_host_ and _local_port_. The specified _data_ will
+  # then be written to the newly created UDPSocket.
+  #
+  # @param [String] data
+  #   The data to send through the connection.
+  #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Integer] port
+  #   The port to connect to.
+  #
+  # @param [String] local_host
+  #   The local host to bind to.
+  #
+  # @param [Integer] local_port
+  #   The local port to bind to.
+  #
+  # @yield [socket]
+  #   If a block is given, it will be passed the newly created socket.
   #
-  def Net.udp_connect_and_send(data,rhost,rport,lhost=nil,lport=nil,&block)
-    Net.udp_connect(rhost,rport,lhost,lport) do |sock|
+  # @yieldparam [UDPsocket] socket
+  #   The newly created UDPSocket object.
+  #
+  # @return [UDPSocket]
+  #   The newly created UDPSocket object.
+  #
+  def Net.udp_connect_and_send(data,host,port,local_host=nil,local_port=nil,&block)
+    Net.udp_connect(host,port,local_host,local_port) do |sock|
       sock.write(data)
 
       block.call(sock) if block
@@ -57,13 +100,30 @@ module Net
   end
 
   #
-  # Creates a new UDPSocket object with the specified _rhost_, _rport_
-  # and the given _lhost_ and _lport_. If _block_ is given, it will be
-  # passed the newly created UDPSocket object. After the UDPSocket object
-  # has been passed to the given _block_ it will be closed.
+  # Creates a new UDPSocket object with the specified _host_, _port_
+  # and the given _local_host_ and _local_port_.
+  #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Integer] port
+  #   The port to connect to.
+  #
+  # @param [String] local_host
+  #   The local host to bind to.
+  #
+  # @param [Integer] local_port
+  #   The local port to bind to.
+  #
+  # @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.
   #
-  def Net.udp_session(rhost,rport,lhost=nil,lport=nil,&block)
-    Net.udp_connect(rhost,rport,lhost,lport) do |sock|
+  # @yieldparam [UDPsocket] socket
+  #   The newly created UDPSocket object.
+  #
+  def Net.udp_session(host,port,local_host=nil,local_port=nil,&block)
+    Net.udp_connect(host,port,local_host,local_port) do |sock|
       block.call(sock) if block
       sock.close
     end
@@ -72,16 +132,93 @@ module Net
   end
 
   #
-  # Connects to the specified _rhost_ and _rport_ with the given _lhost_
-  # and _lport_, reads the banner then closes the connection, returning the
-  # received banner. If a _block_ is given it will be passed the banner.
+  # Connects to the specified _host_ and _port_ with the given _local_host_
+  # and _local_port_, reads the banner then closes the connection,
+  # returning the received banner.
+  #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Integer] port
+  #   The port to connect to.
+  #
+  # @param [String] local_host
+  #   The local host to bind to.
+  #
+  # @param [Integer] local_port
+  #   The local port to bind to.
+  #
+  # @yield [banner]
+  #   If a block is given, it will be passed the grabbed banner.
   #
-  def Net.udp_banner(rhost,rport,lhost=nil,lport=nil,&block)
-    Net.udp_session(rhost,rport,lhost,lport) do |sock|
+  # @yieldparam [String] banner
+  #   The grabbed banner.
+  #
+  # @return [String]
+  #   The grabbed banner.
+  #
+  def Net.udp_banner(host,port,local_host=nil,local_port=nil,&block)
+    Net.udp_session(host,port,local_host,local_port) do |sock|
       banner = sock.readline
     end
 
     block.call(banner) if block
     return banner
   end
+
+  #
+  # Creates a new UDPServer listening on the specified _host_ and _port_.
+  #
+  # @param [Integer] port
+  #   The local port to listen on.
+  #
+  # @param [String] host
+  #   The host to bind to.
+  #
+  # @return [UDPServer]
+  #   The new UDP server.
+  #
+  # @example
+  #   Net.udp_server(1337)
+  #
+  # @since 0.3.0
+  #
+  def Net.udp_server(port,host='0.0.0.0',&block)
+    server = UDPServer.new(host,port)
+
+    block.call(server) if block
+    return server
+  end
+
+  #
+  # Creates a new UDPServer listening on the specified _host_ and _port_,
+  # passing it to the given _block_ and then closing the server.
+  #
+  # @param [Integer] port
+  #   The local port to bind to.
+  #
+  # @param [String] host
+  #   The host to bind to.
+  #
+  # @yield [server]
+  #   The block which will be called after the _server_ has been created.
+  #   After the block has finished, the _server_ will be closed.
+  #
+  # @yieldparam [UDPServer] server
+  #   The newly created UDP server.
+  #
+  # @return [nil]
+  #
+  # @example
+  #   Net.udp_server_session(1337) do |server|
+  #     data, sender = server.recvfrom(1024)
+  #   end
+  #
+  # @since 0.3.0
+  #
+  def Net.udp_server_session(port,host='0.0.0.0',&block)
+    server = Net.udp_server(port,host,&block)
+    server.close()
+    return nil
+  end
 end

data/lib/ronin/{sessions.rb → network/helpers.rb}

@@ -1,7 +1,5 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
@@ -18,15 +16,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
-require 'ronin/sessions/session'
-require 'ronin/sessions/tcp'
-require 'ronin/sessions/udp'
-require 'ronin/sessions/smtp'
-require 'ronin/sessions/esmtp'
-require 'ronin/sessions/pop3'
-require 'ronin/sessions/imap'
-require 'ronin/sessions/telnet'
-require 'ronin/sessions/web'
+require 'ronin/network/helpers/helper'
+require 'ronin/network/helpers/tcp'
+require 'ronin/network/helpers/udp'
+require 'ronin/network/helpers/smtp'
+require 'ronin/network/helpers/esmtp'
+require 'ronin/network/helpers/pop3'
+require 'ronin/network/helpers/imap'
+require 'ronin/network/helpers/telnet'
+require 'ronin/network/helpers/web'