caper 0.2.0

data/lib/caper/offline.rb

@@ -0,0 +1,51 @@
+require 'caper/capture_wrapper'
+
+module Caper
+  # A wrapper class for pcap devices opened with open_offline()
+  #
+  class Offline < CaptureWrapper
+    attr_accessor :path
+
+    # Creates a pcap interface for reading saved capture files.
+    #
+    # @param [String] path
+    #   The path to the file to open.
+    #
+    # @param [Hash] opts
+    #   Options are ignored and passed to the super-class except for those 
+    #   below.
+    #
+    # @option opts [ignored] :path
+    #   The :path option will be overridden with the value of the path 
+    #   argument.  If specified in opts, its value will be ignored.
+    #
+    # @return [Offline]
+    #   A Caper::Offline wrapper.
+    #
+    # @raise [LibError]
+    #   On failure, an exception is raised with the relevant error 
+    #   message from libpcap.
+    #
+    def initialize(path, opts={}, &block)
+      @path = path
+      @errbuf = ErrorBuffer.create()
+      @pcap = Caper.pcap_open_offline(File.expand_path(@path), @errbuf)
+      raise(LibError, "pcap_open_offline(): #{@errbuf.to_s}") if @pcap.null?
+      super(@pcap, opts, &block)
+    end
+
+    def swapped?
+      Caper.pcap_is_swapped(_pcap) == 1 ? true : false
+    end
+
+    def file_version
+      "#{Caper.pcap_major_version(_pcap)}.#{Caper.pcap_minor_version(_pcap)}"
+    end
+  end
+
+  attach_function :pcap_open_offline, [:string, :pointer], :pcap_t
+  attach_function :pcap_is_swapped, [:pcap_t], :int
+  attach_function :pcap_major_version, [:pcap_t], :int
+  attach_function :pcap_minor_version, [:pcap_t], :int
+
+end

data/lib/caper/packet.rb

@@ -0,0 +1,163 @@
+
+module Caper
+  class Packet
+    attr_reader :body_ptr, :header
+
+    # Creates a Packet from a Ruby string object.
+    #
+    # see new() for more information about the arguments.
+    def self.from_string(body, opts={})
+      new(nil, body, opts)
+    end
+
+    # Allocates a Packet using new memory. Used primarily for pcap_loop
+    # and pcap_dispatch to retain packets after new ones have been received
+    # or a pcap device is closed.
+    def self.allocate(phdr, buf)
+      new(phdr, buf).copy()
+    end
+
+    # @param [PacketHeader, nil] hdr
+    #   The pcap pkthdr struct for this packet or nil.  hdr may only be
+    #   nil if a string is supplied for the body. A header will be 
+    #   created automatically and set_body called with opts.
+    #
+    # @param [FFI::Pointer, String] body
+    #   A string or pointer for the body of the packet. A String may
+    #   only be specified if hdr is set to nil.
+    #
+    # @param [optional, Hash] opts
+    #   Specifies additional options at creation time. Only those
+    #   below are applicable for all initiatialization styles.
+    #   All other options are sent to set_body(), but only if the header
+    #   is nil and body is a String. See set_body() for more info.
+    # 
+    # @option opts [optional, Time] :time, :timestamp
+    #   Sets the timestamp in the header.
+    #
+    # @raise [ArgumentError, TypeError]
+    #   An exception is raised if any of the parameter rules described 
+    #   are not followed.
+    #
+    def initialize(hdr, body, opts={})
+      o = opts.dup
+      ts = o.delete(:time) || o.delete(:timestamp)
+      case hdr
+      when PacketHeader
+        raise(ArgumentError, "NULL header pointer") if hdr.to_ptr.null?
+        @header = hdr
+      when ::FFI::Pointer
+        raise(ArgumentError, "NULL header pointer") if hdr.null?
+        @header = PacketHeader.new(hdr)
+      when nil 
+        if body.is_a? String
+          set_body(body, o)
+        else
+          raise(TypeError, "invalid body with nil header: #{body.class}")
+        end
+      else
+        raise(TypeError, "invalid header: #{hdr.class}")
+      end
+        
+      @header.ts.time = ts if ts
+
+      unless @body_ptr
+        if body.is_a?(FFI::Pointer) and not body.null?
+          @body_ptr = body
+        else
+          raise(TypeError, "invalid body for header: #{body.class}")
+        end
+      end
+    end
+
+    # Sets the body from a string. A pointer is automatically derived from
+    #
+    # @param [String] data
+    #   The body to set
+    #
+    # @param [Hash] opts
+    #   Body length options.
+    #
+    # @option opts [optional, Integer] :caplen, :captured
+    #   The captured length (or snaplen) for this packet.
+    #   Length of data portion present. Defaults to body.size(). If
+    #   caplen is larger than the body, then it is overridden with body.size.
+    #   
+    # @option opts [optional, Integer] :len, :length
+    #   The total length of the packet (off wire). Defaults to caplen. If
+    #   If :length is less than the :caplen, it is overridden as :caplen.
+    #
+    #
+    # @return [String]
+    #   Returns the data as supplied per attr_writer convention.
+    #
+    def set_body(data, opts={})
+      cl = opts[:caplen] || opts[:captured] || data.size
+      l = opts[:length] || opts[:len] || cl
+      clen = (cl < data.size) ? cl : data.size
+      len = (l < clen) ? clen : l
+
+      @header ||= PacketHeader.new
+      @header.caplen = len || @header.caplen
+      @header.len = len || @header.caplen
+      @body_ptr = FFI::MemoryPointer.from_string(data)
+      return self
+    end
+
+    alias body= set_body
+
+    # @return [String]
+    #   A String representation of the packet data.
+    #   The reference to the string is not kept by the object and changes
+    #   won't affect the data in this packet.
+    def body
+      @body_ptr.read_string(@header.caplen)
+    end
+
+    # @return [Time]
+    #   Returns the pcap timestamp as a Time object
+    def time
+      @header.ts.time
+    end
+
+    alias timestamp time
+
+    # Sets the pcap timestamp.
+    def time=(t)
+      @header.ts.time=(t)
+    end
+
+    def caplen
+      @header.caplen
+    end
+
+    alias captured caplen
+
+    def len
+      @header.len
+    end
+
+    alias length len
+
+    # An optimized copy which allocates new memory for a PacketHeader and
+    # body.
+    #
+    # DANGEROUS: This method uses direct FFI bindings for the copy and
+    # may crash Ruby if the packet header or body is incorrect.
+    #
+    # @raise [StandardError]
+    #   An exception is raised if the header or body is a NULL pointer.
+    #
+    def copy
+      raise(StandardError, "header is a NULL pointer") if @header.to_ptr.null?
+      raise(StandardError, "body is a NULL pointer") if body_ptr.null?
+      cpy_hdr = PacketHeader.new
+      cpy_buf = FFI::MemoryPointer.new(@header.caplen)
+      CRT.memcpy(cpy_hdr, @header, PacketHeader.size)
+      CRT.memcpy(cpy_buf, @body_ptr, @header.caplen)
+      self.class.new( cpy_hdr, cpy_buf )
+    end
+
+  end
+
+end

data/lib/caper/packet_header.rb

@@ -0,0 +1,23 @@
+module Caper
+
+  # Generic per-packet information, as supplied by libpcap. This structure
+  # is used to track only the libpcap header and just contains the timestamp
+  # and length information used by libpcap.
+  #
+  # See pcap_pkthdr struct in pcap.h
+  class PacketHeader < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      struct :ts,      ::Caper::TimeVal,     :desc => 'time stamp'
+      field  :caplen,  :bpf_uint32, :desc => 'length of portion present'
+      field  :len,     :bpf_uint32, :desc => 'length of packet (off wire)'
+    end
+
+    alias timestamp ts
+    alias captured caplen
+    alias length len
+
+  end
+
+end

data/lib/caper/pcap.rb

@@ -0,0 +1,250 @@
+require 'enumerator'
+
+module Caper
+  DEFAULT_SNAPLEN = 65535  # Default snapshot length for packets
+
+  attach_function :pcap_lookupdev, [:pointer], :string
+
+  # Find the default device on which to capture.
+  # 
+  # @return [String]
+  #   Name of default device
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error 
+  #   message from libpcap.
+  #
+  def Caper.lookupdev
+    e = ErrorBuffer.create()
+    unless name = Caper.pcap_lookupdev(e)
+      raise(LibError, "pcap_lookupdev(): #{e.to_s}")
+    end
+    return name
+  end
+
+
+  attach_function :pcap_lookupnet, [:string, :pointer, :pointer, :pointer], :int
+
+  # Determine the IPv4 network number and mask relevant with a network 
+  # device.
+  # 
+  # @param [String] device
+  #   The name of the device to look up.
+  #
+  # @yield [netp, maskp]
+  #
+  # @yieldparam [FFI::MemoryPointer] netp
+  #   A pointer to the network return value.
+  #
+  # @yieldparam [FFI::MemoryPointer] maskp
+  #   A pointer to the netmask return value.
+  #
+  # @return [nil, String] 
+  #   The IPv4 network number and mask presented as "n.n.n.n/m.m.m.m".
+  #   nil is returned when a block is specified.
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error message 
+  #   from libpcap. 
+  #
+  def Caper.lookupnet(device)
+    netp  = FFI::MemoryPointer.new(find_type(:bpf_uint32))
+    maskp = FFI::MemoryPointer.new(find_type(:bpf_uint32))
+    errbuf = ErrorBuffer.create()
+    unless Caper.pcap_lookupnet(device, netp, maskp, errbuf) == 0
+      raise(LibError, "pcap_lookupnet(): #{errbuf.to_s}")
+    end
+    if block_given?
+      yield(netp, maskp)
+    else
+      return( netp.get_array_of_uchar(0,4).join('.') << "/" <<
+              maskp.get_array_of_uchar(0,4).join('.') )
+    end
+  end
+  
+
+  # Opens a new Live device for capturing from the network. See Live.new()
+  # for arguments.
+  #
+  # If passed a block, the block is passed to Live.new() and the Live
+  # object is closed after completion of the block
+  def Caper.open_live(opts={},&block)
+    ret = Live.new(opts, &block)
+    return block_given? ? ret.close : ret
+  end
+
+
+  # Opens a new Dead pcap interface for compiling filters or opening
+  # a capture for output. See Dead.new() for arguments.
+  def Caper.open_dead(opts={}, &block)
+    ret = Dead.new(opts, &block)
+    return block_given? ? ret.close : ret
+  end
+
+
+  # Opens a saved capture file for reading. See Offline.new for arguments.
+  def Caper.open_offline(path, opts={}, &block)
+    ret = Offline.new(path, opts={}, &block)
+    return block_given? ? ret.close : ret
+  end
+
+  # Same as open_offline
+  def Caper.open_file(path, opts={}, &block)
+    open_offline(path, opts, &block)
+  end
+
+  attach_function :pcap_findalldevs, [:pointer, :pointer], :int
+  attach_function :pcap_freealldevs, [Interface], :void
+
+  # List all capture devices and yield them each to a block
+  #
+  # @yield [dev]
+  #
+  # @yieldparam [Interface] dev
+  #   An Interface structure for each device.
+  #
+  # @return [nil]
+  #
+  # @raise [LibError]
+  #   On failure, an exception is raised with the relevant error 
+  #   message from libpcap.
+  #
+  def Caper.each_device
+    devices = ::FFI::MemoryPointer.new(:pointer)
+    errbuf = ErrorBuffer.create()
+
+    Caper.pcap_findalldevs(devices, errbuf)
+    node = devices.get_pointer(0)
+
+    if node.null?
+      raise(LibError, "pcap_findalldevs(): #{errbuf.to_s}")
+    end
+
+    device = Interface.new(node)
+
+    while device
+      yield(device)
+      device = device.next
+    end
+
+    Caper.pcap_freealldevs(node)
+    return nil
+  end
+
+
+  # Returns an array of device name and network/netmask pairs for
+  # each interface found on the system.
+  #
+  # If an interface does not have an address assigned, its network/netmask
+  # value is returned as a nil value.
+  def Caper.dump_devices
+    Caper.enum_for(:each_device).map do |dev| 
+      net = begin; Caper.lookupnet(dev.name); rescue LibError; end
+      [dev.name, net]
+    end
+  end
+
+
+  # Returns an array of device names for each interface found on the system.
+  def Caper.device_names
+    Caper.enum_for(:each_device).map {|dev| dev.name }
+  end
+
+  attach_function :pcap_lib_version, [], :string
+
+
+  # Get the version information for libpcap.
+  #
+  # @return [String]
+  #  Information about the version of the libpcap library being used; 
+  #  note that it  contains more information than just a version number.
+  #   
+  def Caper.lib_version
+    Caper.pcap_lib_version
+  end
+
+
+  # Extract just the version number from the lib_version string.
+  #
+  # @return [String]
+  #  Version number.
+  #   
+  def Caper.lib_version_number
+    if lib_version() =~ /libpcap version (\d+\.\d+.\d+)/
+      return $1
+    end
+  end
+
+
+  # Unix Only:
+  begin
+
+    attach_function :pcap_get_selectable_fd, [:pcap_t], :int
+
+
+    # Drops privileges back to the uid of the SUDO_USER environment 
+    # variable.
+    #
+    # Only available on Unix.
+    #
+    # This is useful for the paranoid when sudo is used to run a 
+    # ruby pcap program as root.
+    #
+    # This method can generally be called right after a call to 
+    # open_live() has returned a pcap handle or another privileged
+    # call has completed. Note, however, that once privileges are 
+    # dropped, pcap functions that a require higher privilege will 
+    # no longer work.
+    #
+    # @raise [StandardError]
+    #   An error is raised if privileges cannot be dropped for 
+    #   some reason. This may be because the SUDO_USER environment 
+    #   variable is not set, because we already have a lower
+    #   privilige and the SUDO_USER id is not the current uid,
+    #   or because the SUDO_USER environment variable is not
+    #   a valid user.
+    #
+    def Caper.drop_sudo_privs
+      if ENV["SUDO_USER"] and pwent=Etc.getpwnam(ENV["SUDO_USER"])
+        Process::Sys.setgid(pwent.gid) 
+        Process::Sys.setegid(pwent.gid) 
+        Process::Sys.setuid(pwent.uid)
+        Process::Sys.seteuid(pwent.uid)
+        return true if ( 
+          Process::Sys.getuid  == pwent.uid and 
+          Process::Sys.geteuid == pwent.uid and 
+          Process::Sys.getgid  == pwent.gid and 
+          Process::Sys.getegid == pwent.gid )
+      end
+      raise(StandardError, "Unable to drop privileges")
+    end
+
+  rescue FFI::NotFoundError
+    $pcap_not_unix=true
+  end
+
+  # Win32 only:
+  begin
+    attach_function :pcap_setbuff, [:pcap_t, :int], :int
+    attach_function :pcap_setmode, [:pcap_t, :pcap_w32_modes_enum], :int
+    attach_function :pcap_setmintocopy, [:pcap_t, :int], :int
+  rescue FFI::NotFoundError
+    $pcap_not_win32=true
+  end if $pcap_not_unix
+
+  # MSDOS only???:
+  begin
+    attach_function :pcap_stats_ex, [:pcap_t, StatEx], :int
+    attach_function :pcap_set_wait, [:pcap_t, :pointer, :int], :void
+    attach_function :pcap_mac_packets, [], :ulong
+  rescue FFI::NotFoundError
+  end if $pcap_not_win32
+
+
+  #### XXX not sure if we even want FILE io stuff yet (or ever).
+
+  #attach_function :pcap_fopen_offline, [:FILE, :pointer], :pcap_t
+  #attach_function :pcap_file, [:pcap_t], :FILE
+  #attach_function :pcap_dump_fopen, [:pcap_t, :FILE], :pcap_dumper_t
+  #attach_function :pcap_fileno, [:pcap_t], :int
+end