caper 0.2.0

data/lib/caper/stat.rb

@@ -0,0 +1,56 @@
+module Caper
+
+  # As returned by pcap_stats()
+  #
+  # See pcap_stat struct in pcap.h.
+  class Stat < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :ps_recv,   :uint, :desc => "number of packets received"
+      field :ps_drop,   :uint, :desc => "numer of packets dropped"
+      field :ps_ifdrop, :uint, :desc => "drops by interface (not yet supported)"
+      # bs_capt field intentionally left off (WIN32 only)
+    end
+
+    alias received ps_recv
+    alias dropped ps_drop
+    alias interface_dropped ps_ifdrop
+
+  end
+
+  # As returned by pcap_stats_ex() (MSDOS only)
+  #
+  # See pcap_stat_ex struct in pcap.h
+  class StatEx < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :rx_packets,  :ulong, :desc => "total packets received"
+      field :tx_packets,  :ulong, :desc => "total packets transmitted"
+      field :rx_bytes,    :ulong, :desc => "total bytes received"
+      field :tx_bytes,    :ulong, :desc => "total bytes transmitted"
+      field :rx_errors,   :ulong, :desc => "bad packets received"
+      field :tx_errors,   :ulong, :desc => "packet transmit problems"
+      field :rx_dropped,  :ulong, :desc => "no space in Rx buffers"
+      field :tx_dropped,  :ulong, :desc => "no space available for Tx"
+      field :multicast,   :ulong, :desc => "multicast packets received"
+      field :collisions,  :ulong
+
+      # detailed rx errors
+      field :rx_length_errors, :ulong
+      field :rx_over_errors,   :ulong, :desc => "ring buff overflow"
+      field :rx_crc_errors,    :ulong, :desc => "pkt with crc error"
+      field :rx_frame_errors,  :ulong, :desc => "frame alignment errors"
+      field :rx_fifo_errors,   :ulong, :desc => "fifo overrun"
+      field :rx_missed_errors, :ulong, :desc => "missed packet"
+
+      # detailed tx_errors
+      field :tx_aborted_errors,   :ulong
+      field :tx_carrier_errors,   :ulong
+      field :tx_fifo_errors,      :ulong
+      field :tx_heartbeat_errors, :ulong
+      field :tx_window_errors,    :ulong
+    end
+  end
+end

data/lib/caper/time_val.rb

@@ -0,0 +1,46 @@
+module Caper
+  class TimeVal < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :tv_sec, :time_t
+      field :tv_usec, :suseconds_t
+    end
+
+    def initialize(*args)
+      if args.size == 1 and (t=args[0]).kind_of?(Time)
+        self.time = t
+      else
+        super(*args)
+      end
+    end
+
+    alias sec tv_sec
+    alias usec tv_usec
+
+    # Returns the time value as a ruby Time object.
+    #
+    # @return [Time]
+    #   A ruby time object derived from this TimeVal.
+    def time
+      Time.at(self.tv_sec, self.tv_usec)
+    end
+
+    alias to_time time
+
+    # Sets the time value from a ruby Time object
+    #
+    # @param [Time] t
+    #   A ruby time object from which to set the time.
+    #
+    # @return [Time]
+    #   Returns the same Time object supplied per convention.
+    #
+    def time=(t)
+      self.tv_sec = t.tv_sec
+      self.tv_usec = t.tv_usec
+      return t
+    end
+
+  end
+end

data/lib/caper/typedefs.rb

@@ -0,0 +1,25 @@
+module Caper
+  typedef :pointer, :FILE
+
+  typedef :int,  :bpf_int32
+  typedef :uint, :bpf_uint32
+
+  enum :pcap_direction_t, [
+    :pcap_d_inout,
+    :pcap_d_in,
+    :pcap_d_out
+  ]
+
+  # For Win32-only pcap_setmode()
+  enum :pcap_w32_modes_enum, [ :capt, :stat, :mon ] 
+
+  typedef :pointer, :pcap_t
+  typedef :pointer, :pcap_dumper_t
+  typedef :pointer, :pcap_addr_t
+
+  # add some of the more temperamental FFI types if needed
+  [ [:long, :time_t],
+    [:uint32, :suseconds_t],
+  ].each {|t, d| begin; find_type(d); rescue TypeError; typedef t,d; end }
+
+end

data/lib/caper/version.rb

@@ -0,0 +1,4 @@
+module Caper
+  # caper version
+  VERSION = '0.1.2'
+end

data/spec/data_link_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe DataLink do
+  before(:all) do
+    @datalink = DataLink.new(0)
+  end
+
+  it "should map datalink names to datalink layer type values" do
+    DataLink.name_to_val(:en10mb).should == 1
+  end
+
+  it "should map datalink layer type values to datalink names" do
+    DataLink.val_to_name(1).should == "EN10MB"
+  end
+
+  it "should be initialized from a pcap datalink value" do
+    @datalink.name.should == 'NULL'
+  end
+
+  it "should support initialization from a pcap datalink name symbol" do
+    @datalink = DataLink.new(:null)
+    DataLink.should === @datalink
+  end
+
+  it "should support initialization from a pcap datalink name string" do
+    dl = DataLink.new('en10mb')
+    DataLink.should === dl
+  end
+
+  it "should allow equality comparison against numeric values" do
+    (@datalink == 0).should == true
+    (@datalink == 1).should == false
+  end
+
+  it "should allow equality comparison against String names" do
+    (@datalink == "null").should == true
+    (@datalink == "en10mb").should == false
+  end
+
+  it "should allow equality comparison against Symbol names" do
+    (@datalink == :null).should == true
+    (@datalink == :en10mb).should == false
+  end
+
+  it "should allow comparison against another DataLink" do
+    (@datalink == DataLink.new(0)).should == true
+    (@datalink == DataLink.new(1)).should == false
+  end
+
+  it "should still compare correctly against any other object" do
+    (@datalink == Object.new).should == false
+  end
+
+  it "should have a description" do
+    @datalink.description.should_not be_empty
+  end
+
+  it "should convert to an Integer for the DLT value" do
+    @datalink.to_i.should == 0
+  end
+
+  it "should convert to a String for the DLT name" do
+    @datalink.to_s.should == 'NULL'
+  end
+end

data/spec/dead_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+require 'wrapper_behaviors'
+
+describe Dead do
+  before(:each) do
+    @pcap = Dead.new()
+  end
+
+  after(:each) do
+    @pcap.close
+  end
+
+  it_should_behave_like "Caper::CommonWrapper"
+
+  describe "yielding to a block" do
+    # Note we also test all the behaviors here together instead of seperately.
+    Dead.new() do |this|
+      @pcap = this
+
+      it "should be in a ready state in the block" do
+        @pcap.should be_ready
+        @pcap.should_not be_closed
+      end
+
+      it_should_behave_like "Caper::CommonWrapper"
+
+      @pcap.close
+    end
+
+
+  end
+
+end
+

data/spec/error_buffer_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe ErrorBuffer do
+  before(:all) do
+    @errbuf = ErrorBuffer.create
+  end
+
+  it "should have a size of 256" do
+    @errbuf.size.should == 256
+  end
+
+  it "should return an error message with to_s" do
+    @errbuf.to_s.should be_empty
+    Caper.pcap_open_offline("/this/file/wont/exist/#{rand(0xFFFF)}", @errbuf )
+    @errbuf.to_s.should_not be_empty
+  end
+end

data/spec/file_header_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe FileHeader do
+  before(:all) do
+    @file_header = FileHeader.new( :raw => File.read(PCAP_TESTFILE) )
+  end
+
+  it "should parse a pcap file correctly" do
+    @file_header.magic.should == 0xa1b2c3d4
+    @file_header.version_major.should == 2
+    @file_header.version_minor.should == 4
+    @file_header.thiszone.should == 0
+    @file_header.sigfigs.should == 0
+    @file_header.snaplen.should == 96
+    @file_header.linktype.should == 1
+  end
+
+  it "should return a file format version string" do
+    String.should === @file_header.version
+    @file_header.version.should == "2.4"
+  end
+
+  it "should return a DataLink for the linktype using datalink()" do
+    DataLink.should === @file_header.datalink
+    (@file_header.datalink == :en10mb).should == true
+  end
+
+end

data/spec/live_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+require 'wrapper_behaviors'
+require 'packet_behaviors'
+
+describe Live do
+  before(:each) do
+    @pcap = Live.new(
+      :device => PCAP_DEV,
+      :promisc => true,
+      :timeout => 1000
+    )
+    start_traffic_generator()
+  end
+
+  after(:each) do
+    stop_traffic_generator()
+    @pcap.close
+  end
+
+  it_should_behave_like "Caper::CaptureWrapper"
+  
+  it "should support non-blocking mode" do
+    @pcap.non_blocking = true
+    @pcap.should be_non_blocking
+  end
+
+  it "should provide statistics about packets received/dropped" do
+    i = 0
+    @pcap.loop {|this,pkt| @pcap.stop if (i += 1) == 10 }
+    i.should_not == 0
+    stats = @pcap.stats
+    Stat.should === stats
+    stats.received.should > 0
+    stats.received.should >= 10
+  end
+
+  it "should yield packets with a timestamp using loop()" do
+    i = 0
+    @pkt = nil
+    @pcap.loop(:count => 2) do |this, pkt|
+      this.should == @pcap
+      pkt.should_not be_nil
+      Packet.should === pkt
+      (Time.now - pkt.time).should_not > 1000
+      i+=1
+    end
+    i.should == 2
+  end
+
+
+  describe "live packets" do
+    before(:all) do
+      @pcap = Live.new(
+        :device => PCAP_DEV,
+        :promisc => true
+      )
+      @pkt = @pcap.next()
+      start_traffic_generator()
+    end
+
+    after(:all) do
+      stop_traffic_generator()
+      @pcap.close
+    end
+    
+    it_should_behave_like "Caper::Packet populated"
+
+  end
+
+  describe "yielding to a block" do
+    # Note we also test all the behaviors here together instead of seperately.
+    Offline.new(PCAP_TESTFILE) do |this|
+      @pcap = this
+
+      it "should be in a ready state in the block" do
+        @pcap.should be_ready
+        @pcap.should_not be_closed
+      end
+
+      start_traffic_generator()
+      it_should_behave_like "Caper::CaptureWrapper"
+      stop_traffic_generator()
+      @pcap.close
+    end
+  end
+end
+

data/spec/offline_spec.rb

@@ -0,0 +1,61 @@
+require 'spec_helper'
+require 'wrapper_behaviors'
+
+describe Offline do
+  before(:each) do
+    @pcap = Offline.new(PCAP_TESTFILE)
+  end
+
+  after(:each) do
+    @pcap.close
+  end
+
+  it_should_behave_like "Caper::CaptureWrapper"
+
+  it "should return a nil from next() at the end of the dump file" do
+    i = 0
+    @pcap.loop {|this,pkt| i+=1 }
+    i.should > 0
+    @pcap.next.should be_nil
+  end
+
+  it "should yield packets with a timestamp using loop()" do
+    i = 0
+    @pkt = nil
+    @pcap.loop(:count => 2) do |this, pkt|
+      this.should == @pcap
+      pkt.should_not be_nil
+      Packet.should === pkt
+      pkt.time.to_i.should > 0
+      i+=1
+    end
+    i.should == 2
+  end
+
+  it "should supply a file version" do
+    @pcap.file_version.should =~ /^\d+\.\d+$/
+  end
+
+  it "should indicate whether it is endian swapped" do
+    [true,false].include?(@pcap.swapped?).should == true
+  end
+
+  describe "yielding to a block" do
+
+    # Note we also test all the behaviors here together instead of seperately.
+    Offline.new(PCAP_TESTFILE) do |this|
+      @pcap = this
+
+      it "should be in a ready state in the block" do
+        @pcap.should be_ready
+        @pcap.should_not be_closed
+      end
+
+      it_should_behave_like "Caper::CaptureWrapper"
+
+      @pcap.close
+    end
+
+  end
+end
+

data/spec/packet_behaviors.rb

@@ -0,0 +1,68 @@
+
+shared_examples_for "Caper::Packet" do
+  it "should supply a way to get a pointer for the body" do
+    @pkt.body_ptr.should_not be_nil
+    ::FFI::Pointer.should === @pkt.body_ptr
+  end
+
+  it "should supply a way to get a String for the body" do
+    @pkt.body.should_not be_nil
+    String.should === @pkt.body
+  end
+
+  it "should supply a timestamp as a Time object" do
+    @pkt.time.should_not be_nil
+    Time.should === @pkt.time
+  end
+
+  it "should allow time timestamp to be changed" do
+    t = Time.now
+    lambda {@pkt.time = t}.should_not raise_error(Exception)
+    @pkt.time.should == t
+  end
+
+  it "should return a deep copy of itself with copy()" do
+    cp = @pkt.copy()
+    cp.object_id.should_not == @pkt.object_id
+    cp.body_ptr.object_id.should_not == @pkt.body_ptr.object_id
+    cp.body.should == @pkt.body
+  end
+end
+
+shared_examples_for "Caper::Packet populated" do
+  it_should_behave_like "Caper::Packet"
+
+  it "should have a non-zero packet length in the header" do
+    @pkt.length.should_not == 0
+  end
+
+  it "should have a non-zero captured length in the header" do
+    @pkt.captured.should_not == 0
+  end
+
+  it "should have a non-empty body" do
+    @pkt.body.should_not be_empty
+  end
+
+  it "should have a non-null body pointer" do
+    @pkt.body_ptr.should_not be_null
+  end
+
+end
+
+shared_examples_for "Caper::Packet composed" do
+  it "should return the expected header" do
+    @pkt.header.should be_kind_of(PacketHeader)
+    @pkt.header.len.should  == @test_body.size
+    @pkt.header.caplen.should == @test_body.size
+    @pkt.header.timestamp.to_time.to_i.should == 0
+  end
+
+  it "should return the expected body String" do
+    @pkt.body.should == @test_body
+  end
+
+  it "should return a pointer to the expected body String" do
+    @pkt.body_ptr.read_string(@pkt.caplen).should == @test_body
+  end
+end