caper 0.2.0

data/.gitignore

@@ -0,0 +1,9 @@
+doc
+pkg
+tmp/*
+ref/*
+.yardoc
+.DS_Store
+*.swp
+*~
+*.gemspec

data/History.rdoc

@@ -0,0 +1,31 @@
+=== 0.2.0 / 2010-04-22
+* Renamed library to 'caper' using Caper as the ruby namespace instead of 
+  FFI::PCap
+* Fully branched as a separate project under the new caper name.
+
+=== 0.1.4 / 2010-04-20
+* Fixes and example for pcap dumper
+
+=== 0.1.3 / 2010-03-05
+* Minor fixes for ruby 1.9 compatability
+
+=== 0.1.2 / 2010-01-03
+
+* Branched from sophsec/ffi-pcap by emonti
+* Using ffi_dry for common struct interface
+* Redesigned  the pcap-specific pcap_pkthdr struct.
+* Dismantled all other network packet parsing code. 
+* 'Handlers' have been split out into type-specific 'Wrappers' by features.
+* The namespace 'Handler' has been reused instead for pcap_handler abstraction
+* Added filtering support and interfaces for compiling filters into bpf code.
+* Added packet injection on Live pcap interfaces.
+* Tackled some minor Jruby compatability issues.
+* Lots of documentation added throughout with yardoc tags.
+* Lots of misc namespace mods and such, and some general refactoring.
+* Lots of other stuff I'm probably forgetting.
+* specs all pass on OS X, Linux, and Win32(except 1 which is a known issue)
+
+=== 0.1.0 / 2009-04-29
+
+* Initial release. (sophsec/ffi-pcap)
+

data/LICENSE.ffi-pcap

@@ -0,0 +1,23 @@
+
+The MIT License
+
+Copyright (c) 2009-2010 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,55 @@
+= caper
+
+* http://github.com/emonti/caper
+* Eric Monti (esmonti at gmail dot com)
+
+This started as a fork of ffi-pcap by postmodern but has diverged 
+significantly from its original version.
+
+* http://github.com/sophsec/ffi-pcap/
+* Postmodern (postmodern.mod3 at gmail.com)
+
+== DESCRIPTION:
+
+Ruby FFI bindings for libpcap.
+
+== FEATURES:
+
+== EXAMPLES:
+
+== REQUIREMENTS:
+
+* libpcap [http://www.tcpdump.org/]
+* ffi >= 0.5.3 [http://github.com/ffi/ffi]
+* ffi_dry [http://github.com/emonti/ffi_dry]
+
+== INSTALL:
+
+  $ sudo gem install caper
+
+== LICENSE:
+
+(please see LICENSE.ffi-pcap for the original ffi-pcap license)
+
+The MIT License
+
+Copyright (c) 2010 Eric Monti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+# -*- ruby -*-
+
+require 'rubygems'
+Dir["tasks/*.rb"].each {|rt| require rt }
+require 'rake/clean'
+require './lib/caper/version.rb'
+
+# Generate a gem using jeweler
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.rubyforge_project = 'caper'
+    gemspec.name = "caper"
+    gemspec.summary = "FFI bindings for libpcap"
+    gemspec.email = "postmodern.mod3@gmail.com"
+    gemspec.homepage = "http://github.com/postmodern/caper"
+    gemspec.description = "Bindings to sniff packets using the FFI interface in Ruby."
+    gemspec.authors = ["Postmodern, Dakrone", "Eric Monti"]
+    gemspec.add_dependency "ffi"
+    gemspec.add_dependency "ffi_dry", ">= 0.1.9"
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+# vim: syntax=Ruby

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/examples/ipfw_divert.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# ipfw add tee 6666 tcp from 192.168.63.128 to any
+# ipfw add tee 6666 tcp from any to 192.168.63.128
+
+require 'caper'
+require "socket"
+require 'pp'
+
+unless Process::Sys.getuid == 0  
+  $stderr.puts "Must run #{$0} as root."
+  exit!
+end
+
+IPPROTO_DIVERT = 254
+
+outfile = ARGV.shift
+#outfile = "test_#{$$}.pcap"
+
+# create a dummy pcap handle for dumping
+pcap        = Caper.open_dead(:datalink => :raw)
+pcap_dumper = pcap.open_dump(outfile)
+
+begin 
+  divert_sock = Socket.open(Socket::PF_INET, Socket::SOCK_RAW, IPPROTO_DIVERT)
+  sockaddr = Socket.pack_sockaddr_in( 6666, '0.0.0.0' )
+  divert_sock.bind(sockaddr)
+
+  puts "ready and waiting...."
+
+  while IO.select([divert_sock], nil, nil)
+    data = divert_sock.recv(65535) # or MTU?
+    pp data
+    pcap_dumper.write_pkt( Caper::Packet.from_string(data) )
+    pcap_dumper.flush 
+  end
+rescue Errno::EPERM
+  $stderr.puts "Must run #{$0} as root."
+  exit!
+ensure 
+  puts "Closing socket."
+  divert_sock.close
+  puts "Closing pcap dumper."
+  pcap_dumper.close
+  pcap.close
+end

data/examples/print_bytes.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'caper'
+
+pcap =
+  Caper::Live.new(:dev => 'en0', 
+                 :promisc => true, 
+                 :handler => Caper::Handler)
+
+pcap.loop() do |this,pkt|
+  puts "#{pkt.time}:"
+
+  pkt.captured.times {|i| print ' %.2x' % pkt.body_ptr.get_uchar(i) }
+  putc "\n"
+end
+

data/examples/test_loop.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'caper'
+require 'rbkb/extends'
+require 'ffi/packets'
+require 'pp'
+
+include FFI
+
+pcap =
+  Caper::Live.new( :dev => 'en0', 
+                  :promisc => true ) 
+
+tblk = lambda do |this,pkt|
+  puts "#{pkt.time.asctime}:"
+
+  puts pkt.body.hexdump
+  putc "\n"
+end
+
+wrap_blk = lambda do |id, phdr, buf|
+  tblk.call(pcap, Caper::Packet.new(phdr, buf))
+end
+#Caper.pcap_loop(pcap.pcap, 10, wrap_blk, nil)
+puts "-"*70
+
+pcap.loop(:count => 3, :handler => Caper::Handler.new, &tblk)
+puts "-"*70
+
+class Parser < Caper::Handler
+  def receive_pcap(*args)
+    pcap, pkt = super(*args)
+    p = pkt.body_ptr
+    parsed = []
+    eth = Packets::Eth::Hdr.new(p)
+    parsed << Packets::Eth::Hdr.new(p)
+    parsed << Packets::Ip::Hdr.new(p += eth.size) if eth.lookup_etype == "IP"
+
+    [pkt, parsed]
+  end
+end
+pcap.loop(:count => 10, :parser => Parser) {|pkt, frames| 
+  pp frames.map {|x| x.class}
+  pp({ frames[1].src => frames[1].dst })
+}
+
+

data/lib/caper.rb

@@ -0,0 +1,40 @@
+begin; require 'rubygems'; rescue LoadError; end
+
+require 'ffi_dry'
+
+module Caper
+  extend FFI::Library
+
+  begin
+    ffi_lib "wpcap"
+  rescue LoadError
+    ffi_lib "pcap"
+  end
+end
+
+require 'caper/crt'
+
+require 'caper/version'
+require 'caper/exceptions'
+
+# FFI typedefs, pointer wrappers, and struct
+require 'caper/typedefs'
+require 'caper/bsd'
+require 'caper/addr'
+require 'caper/interface'
+require 'caper/file_header'
+require 'caper/time_val'
+require 'caper/packet_header'
+require 'caper/stat'
+require 'caper/bpf'
+require 'caper/dumper'
+
+# Ruby FFI function bindings, sugar, and misc wrappers
+require 'caper/error_buffer'
+require 'caper/pcap'
+require 'caper/data_link'
+require 'caper/packet'
+require 'caper/live'
+require 'caper/offline'
+require 'caper/dead'
+

data/lib/caper/addr.rb

@@ -0,0 +1,19 @@
+
+module Caper
+
+  # Representation of an interface address.
+  #
+  # See pcap_addr struct in pcap.h
+  class Addr < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      p_struct :next,       ::Caper::Addr
+      p_struct :addr,       ::Caper::SockAddr, :desc => 'address'
+      p_struct :netmask,    ::Caper::SockAddr, :desc => 'netmask of the address'
+      p_struct :broadcast,  ::Caper::SockAddr, :desc => 'broadcast for the address'
+      p_struct :dest_addr,  ::Caper::SockAddr, :desc => 'p2p destination for address'
+    end
+
+  end
+end

data/lib/caper/bpf.rb

@@ -0,0 +1,104 @@
+
+module Caper
+
+  # Includes structures defined in pcap-bpf.h
+
+  # Berkeley Packet Filter instruction data structure.
+  #
+  # See bpf_insn struct in pcap-bpf.h
+  class BPFInstruction < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field :code,  :ushort
+      field :jt,    :uchar
+      field :jf,    :uchar
+      field :k,     :bpf_int32
+    end
+
+  end
+
+  # Structure for pcap_compile(), pcap_setfilter(), etc.
+  #
+  # See bpf_program struct in pcap-bpf.h
+  class BPFProgram < FFI::Struct
+    include FFI::DRY::StructHelper
+
+    dsl_layout do
+      field    :bf_len,  :uint
+      field    :bf_insn, :pointer
+    end
+
+    def instructions
+      i = 0
+      sz = BPFInstruction.size()
+      Array.new(self.bf_len) do 
+        ins = BPFInstruction.new( self[:bf_insn] + i )
+        i += sz
+        ins
+      end
+    end
+
+    def free!
+      unless @closed
+        @freed = true
+        Caper.pcap_freecode(self)
+      end
+    end
+
+    def freed?
+      return @freed == true
+    end
+
+    # Compiles a bpf filter without a pcap device being open. Downside is
+    # no error messages are available, whereas they are when you use 
+    # open_dead() and use compile() on the resulting Dead.
+    #
+    # @param [Hash] opts
+    #   Additional options for compile
+    #
+    # @option opts [optional, DataLink, Integer, String, Symbol] :datalink
+    #   DataLink layer type. The argument type will be resolved to a DataLink
+    #   value if possible. Defaults to data-link layer type NULL.
+    #
+    # @option opts [optional, Integer] :snaplen
+    #   The snapshot length for the filter. Defaults to SNAPLEN
+    #
+    # @option opts [optional, Integer] :optimize
+    #   Optimization flag. 0 means don't optimize. Defaults to 1.
+    #
+    # @option opts [optional, Integer] :netmask
+    #   A 32-bit number representing the IPv4 netmask of the network on which
+    #   packets are being captured. It is only used when checking for IPv4
+    #   broadcast addresses in the filter program. Default: 0 (unspecified 
+    #   netmask)
+    #
+    # @return [BPFProgram]
+    #   If no errors occur, a compiled BPFProgram is returned.
+    #
+    def self.compile(expr, opts={})
+      datalink = (opts[:datalink] || 1)
+      dl = datalink.kind_of?(DataLink) ? datalink : DataLink.new(datalink)
+      slen     = (opts[:snaplen] || DEFAULT_SNAPLEN)
+      optimize = (opts[:optimize] || 1)
+      mask     = (opts[:netmask] || 0)
+      code = BPFProgram.new()
+      r = Caper.pcap_compile_nopcap(slen, dl.value, code, expr, optimize, mask)
+      raise(LibError, "pcap_compile_nopcap(): unspecified error") if r < 0
+      return code
+    end
+
+  end
+
+
+  attach_function :pcap_compile_nopcap, [:int, :int, BPFProgram, :string, :int, :bpf_uint32], :int
+
+  attach_function :bpf_filter, [BPFInstruction, :pointer, :uint, :uint], :uint
+  attach_function :bpf_validate, [BPFInstruction, :int], :int
+  attach_function :bpf_image, [BPFInstruction, :int], :string
+  attach_function :bpf_dump, [BPFProgram, :int], :void
+  attach_function :pcap_freecode, [BPFProgram], :void
+
+end
+
+

data/lib/caper/bsd.rb

@@ -0,0 +1,96 @@
+# Here's where various BSD sockets typedefs and structures go
+# ... good to have around
+# cribbed from dnet-ffi - EM
+
+require 'socket'
+
+module Caper
+  typedef :uint8, :sa_family_t
+  typedef :uint32, :in_addr_t
+  typedef :uint16, :in_port_t
+
+  # contains AF_* constants culled from Ruby's ::Socket
+  module AF
+    include ::FFI::DRY::ConstMap
+    slurp_constants(::Socket, "AF_")
+    def self.list; @@list ||= super() ; end
+  end
+
+  # Common abstract superclass for all sockaddr struct classes
+  #
+  class SockAddrFamily < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    
+    # returns an address family name for the :family struct member value
+    def lookup_family
+      AF[ self[:family] ]
+    end
+  end
+
+  # generic sockaddr, always good to have around
+  #
+  class SockAddr < SockAddrFamily
+    dsl_layout do
+      field :len,    :uint8,        :desc => 'total length of struct'
+      field :family, :sa_family_t,  :desc => 'address family (AF_*)'
+      field :data,   :char,         :desc => 'variable length bound by :len'
+    end
+  end
+
+
+  # Used to represent a 32-bit IPv4 address in a sock_addr_in structure
+  # 
+  class InAddr < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    dsl_layout { field :in_addr,  :in_addr_t, :desc => 'inet address' }
+  end
+
+  # sockaddr inet, always good to have around
+  #
+  class SockAddrIn < SockAddrFamily
+    dsl_layout do
+      field :len,    :uint8,        :desc => 'length of structure (16)'
+      field :family, :sa_family_t,  :desc => 'address family (AF_INET)'
+      field :port,   :in_port_t,    :desc => '16-bit TCP or UDP port number'
+      field :addr,   :in_addr_t,    :desc => '32-bit IPv4 address'
+      array :_sa_zero, [:uint8,8],  :desc => 'unused'
+    end
+  end
+
+  # Used to represent an IPv6 address in a sock_addr_in6 structure
+  #
+  class In6Addr < ::FFI::Struct
+    include ::FFI::DRY::StructHelper
+    dsl_layout { array :s6_addr, [:uint8, 16], :desc => 'IPv6 address' }
+  end
+
+  # IPv6 socket address
+  #
+  class SockAddrIn6 < SockAddrFamily
+    dsl_layout do
+      field :len,      :uint8,       :desc => 'length of structure(24)'
+      field :family,   :sa_family_t, :desc => 'address family (AF_INET6)'
+      field :port,     :in_port_t,   :desc => 'transport layer port'
+      field :flowinfo, :uint32,      :desc => 'priority & flow label'
+      struct :addr,    ::Caper::In6Addr,     :desc => 'IPv6 address'
+    end
+  end
+
+
+  # data-link socket address
+  #
+  class SockAddrDl < SockAddrFamily
+    dsl_layout do
+      field :len,       :uint8,   :desc => 'length of structure(variable)'
+      field :family, :sa_family_t, :desc => 'address family (AF_LINK)'
+      field :sdl_index, :uint16,  :desc => 'system assigned index, if > 0'
+      field :dltype,    :uint8,   :desc => 'IFT_ETHER, etc. from net/if_types.h'
+      field :nlen,      :uint8,   :desc => 'name length, from :_data'
+      field :alen,      :uint8,   :desc => 'link-layer addres-length'
+      field :slen,      :uint8,   :desc => 'link-layer selector length'
+      field :_data,     :char,    :desc => 'minimum work area=12, can be larger'
+    end
+  end
+
+end
+