ffi-pcap 0.2.0 → 0.2.1

data/.gitignore

@@ -3,8 +3,9 @@ rdoc
 pkg
 tmp/*
 ref/*
+.bundle
 .yardoc
 .DS_Store
 *.swp
 *~
-*.gemspec
+.justrake

data/.pkg_ignore

@@ -0,0 +1,25 @@
+## This File...
+.pkg_ignore
+## MAC OS X
+.DS_Store
+## TEXTMATE
+*.tmproj
+tmtags
+## EMACS
+*~
+\#*
+.\#*
+## VIM
+*.swp
+.*.swp
+## MISC
+.git
+.gitignore
+.yardoc
+.document
+coverage
+rdoc
+pkg
+## PROJECT::SPECIFIC
+*.gemspec
+.justrake

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.specopts

@@ -0,0 +1 @@
+--colour --format specdoc

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title 'FFI PCap Documentation' --protected --files ChangeLog.md,LICENSE.txt

data/{ChangeLog.rdoc → ChangeLog.md}

@@ -1,14 +1,23 @@
-=== 0.2.0 / 2010-04-22
+### 0.2.1 / 2010-08-04
+* Experimental selectable IO support
+* Added Marshal support to Packet objects
+* Irrelevent tweaks made to project dev environment/pkg mgmt
+
+### 0.2.0 / 2010-04-22
+
 * emonti fork merged back into sophsec/ffi-pcap 
 * ... ignore that whole "caper" thing.  It will return as another lib entirely.
 
-=== 0.1.4 / 2010-04-20 (emonti/ffi-pcap)
+### 0.1.4 / 2010-04-20 (emonti/ffi-pcap)
+
 * Fixes and example for pcap dumper
 
-=== 0.1.3 / 2010-03-05 (emonti/ffi-pcap)
+### 0.1.3 / 2010-03-05 (emonti/ffi-pcap)
+
 * Minor fixes for ruby 1.9 compatability
 
-=== 0.1.2 / 2010-01-03 (emonti/ffi-pcap)
+### 0.1.2 / 2010-01-03 (emonti/ffi-pcap)
+
 * Branched from sophsec/ffi-pcap by emonti
 * Using ffi_dry for common struct interface
 * Redesigned  the pcap-specific pcap_pkthdr struct.
@@ -23,5 +32,6 @@
 * 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 (sophsec/ffi-pcap)
+### 0.1.0 / 2009-04-29 (sophsec/ffi-pcap)
+
 * Initial release. 

data/LICENSE.txt

@@ -1,7 +1,4 @@
-
-The MIT License
-
-Copyright (c) 2009-2010 Hal Brodigan
+Copyright (c) 2009-2013 Hal Brodigan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,92 @@
+# ffi-pcap
+
+* [Source](https://github.com/sophsec/ffi-pcap/)
+* [Issues](https://github.com/sophsec/ffi-pcap/issues)
+* [Documentation](http://rubydoc.info/gems/ffi-pcap/frames)
+* Postmodern (postmodern.mod3 at gmail.com)
+* Eric Monti (esmonti at gmail.com)
+
+## Description
+
+Ruby FFI bindings for libpcap.
+
+## Features
+
+Exposes all features of the libpcap library including live packet capture, 
+offline packet capture, live packet injection, etc..
+
+Currently, FFI::PCap does _not_ supply any packet dissection routines. 
+The choice of what to use is left up to you.
+
+Packet dissection libraries:
+
+* [ffi-packets] - Maps raw packets to `FFI::Struct` objects.
+
+## Examples
+
+Reading ICMP packets from a live interface.
+
+    require 'rubygems'
+    require 'ffi/pcap'
+
+    pcap =
+      FFI::PCap::Live.new(:dev => 'lo0',
+                          :timeout => 1,
+                          :promisc => true,
+                          :handler => FFI::PCap::Handler)
+
+    pcap.setfilter("icmp")
+
+    pcap.loop() do |this,pkt|
+      puts "#{pkt.time}:"
+
+      pkt.body.each_byte {|x| print "%0.2x " % x }
+      putc "\n"
+    end
+
+Reading packets from a pcap dump file:
+
+    require 'rubygems'
+    require 'ffi/pcap'
+
+    pcap = FFI::PCap::Offline.new("./foo.cap")
+
+    pcap.loop() do |this,pkt|
+      puts "#{pkt.time}:"
+
+      pkt.body.each_byte {|x| print "%0.2x " % x }
+      putc "\n"
+    end
+
+Replaying packets from a pcap dump file on a live interface:
+
+    require 'rubygems'
+    require 'ffi/pcap'
+
+    live = FFI::PCap::Live.new(:device => 'en0')
+    offline = FFI::PCap::Offline.new("./foo.cap")
+
+    if live.datalink == offline.datalink
+      offline.loop() {|this,pkt| live.inject(pkt) }
+    end
+
+## Requirements
+
+* [libpcap] or [winpcap] >= 1.0.0
+* [ffi] ~> 0.6.0
+* [ffi_dry] ~> 0.1.9
+
+## Install
+
+    $ sudo gem install ffi-pcap
+
+## License
+
+See {file:LICENSE.txt} for license information.
+
+[libpcap]: http://www.tcpdump.org/
+[winpcap]: http://winpcap.org/
+
+[ffi]: https://github.com/ffi/ffi#readme
+[ffi_dry]: https://github.com/emonti/ffi_dry#readme
+[ffi-packets]: http://github.com/emonti/ffi-packets#readme

data/Rakefile

@@ -1,26 +1,36 @@
-# -*- ruby -*-
-
 require 'rubygems'
-Dir["tasks/*.rb"].each {|rt| require rt }
-require 'rake/clean'
-require './lib/ffi/pcap/version.rb'
+require 'rake'
+
+begin
+  gem 'rubygems-tasks', '~> 0.2'
+  require 'rubygems/tasks'
+
+  Gem::Tasks.new
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install rubygems-tasks` to install 'rubygems/tasks'."
+end
 
-# Generate a gem using jeweler
 begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.rubyforge_project = 'ffi-pcap'
-    gemspec.name = "ffi-pcap"
-    gemspec.summary = "FFI bindings for libpcap"
-    gemspec.email = "postmodern.mod3@gmail.com"
-    gemspec.homepage = "http://github.com/sophsec/ffi-pcap"
-    gemspec.description = "Bindings to libpcap via FFI interface in Ruby."
-    gemspec.authors = ["Postmodern", "Dakrone", "Eric Monti"]
-    gemspec.add_dependency "ffi", ">= 0.5.0"
-    gemspec.add_dependency "ffi_dry", ">= 0.1.9"
+  gem 'rspec', '~> 2.0'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
   end
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
 end
+task :test => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.8'
+  require 'yard'
 
-# vim: syntax=Ruby
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end

data/examples/em_selectable_pcap.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
+
+require 'rubygems'
+require 'ffi/pcap'
+require 'eventmachine'
+
+class PcapWatcher < EM::Connection
+  def initialize(pcap)
+    @pcap = pcap
+  end
+
+  def notify_readable(*args)
+    puts "Dispatch!"
+    @pcap.dispatch() do |this, pkt|
+      puts "#{pkt.time}:"
+      puts pkt.body.bytes.to_a.map{|c|  "%0.2x" % c }.join(" ")
+    end
+    puts "end dispatch"
+  end
+
+end
+
+dev = ARGV.shift || 'lo0'
+if ARGV[0]
+  filter = ARGV.join(' ')
+end
+
+EM.run{
+  pcap = FFI::PCap::Live.new(:device => dev, :timeout => 1)
+  pcap.nonblocking=true
+  pcap.setfilter filter if filter
+
+  conn = EM.watch pcap.selectable_fd, PcapWatcher, pcap
+  conn.notify_readable = true
+}
+

data/examples/em_timer.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
+
+require 'rubygems'
+require 'ffi/pcap'
+require 'eventmachine'
+
+dev = ARGV.shift || 'lo0'
+if ARGV[0]
+  filter = ARGV.join(' ')
+end
+
+EM.run{
+  pcap = FFI::PCap::Live.new(:device => dev, :timeout => 1)
+  pcap.setfilter filter if filter
+
+  timer = EM::PeriodicTimer.new(0.0001) do
+    puts "Dispatch!" if $DEBUG
+    pcap.dispatch(:count => -1) do |this, pkt|
+      puts "#{pkt.time}:"
+      puts pkt.body.bytes.to_a.map{|c|  "%0.2x" % c }.join(" ")
+    end
+    puts "end dispatch" if $DEBUG
+  end
+}
+

data/examples/ipfw_divert.rb

@@ -3,35 +3,55 @@
 # Thanks to justfalter(Mike Ryan) for turning me onto Divert Sockets for
 # this example.
 #
-# ipfw add tee 6666 tcp from 192.168.63.128 to any
-# ipfw add tee 6666 tcp from any to 192.168.63.128
+# This example was written to demonstrate a workaround for a specific
+# problem using pcap on VMWare Fusion vmnet interfaces.
+#
+# It demos the ability to use PCAP dump to write a pcap file with
+# packets captured using a divert socket. In order to generate 
+# packets that are diverted you need a system that supports IPFW
+# with divert sockets and you need to establish some ipfw rules that 
+# divert packets to a chosen port. 
+#
+# Below are some example IPFW rules that will capture tcp packets to 
+# or from 192.168.63.128 using port 6666:
+#
+#   ipfw add tee 6666 tcp from 192.168.63.128 to any
+#   ipfw add tee 6666 tcp from any to 192.168.63.128
+#
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
 
+require 'rubygems'
 require 'ffi/pcap'
 require "socket"
 require 'pp'
 
+IPPROTO_DIVERT = 254
+
 unless Process::Sys.getuid == 0  
   $stderr.puts "Must run #{$0} as root."
   exit!
 end
 
-IPPROTO_DIVERT = 254
-
+# First argument is an output pcap file
 outfile = ARGV.shift
-#outfile = "test_#{$$}.pcap"
 
-# create a dummy pcap handle for dumping
+# Second argument is optional for an alternate divert port
+my_divert_port = ARGV.shift || 6666
+
+# Create a dummy pcap handle for dumping
+puts "Dumping packets to #{outfile}"
 pcap        = FFI::PCap.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' )
+  sockaddr = Socket.pack_sockaddr_in( my_divert_port, '0.0.0.0' )
   divert_sock.bind(sockaddr)
 
-  puts "ready and waiting...."
+  puts "IPFW divert socket is listening. Press ctrl-C to end capture"
 
   while IO.select([divert_sock], nil, nil)
+
     data = divert_sock.recv(65535) # or MTU?
     pp data
     pcap_dumper.write_pkt( FFI::PCap::Packet.from_string(data) )

data/examples/print_bytes.rb

@@ -1,10 +1,14 @@
 #!/usr/bin/env ruby
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
 
 require 'rubygems'
 require 'ffi/pcap'
 
+dev = ARGV.shift || 'lo0'
+
 pcap =
-  FFI::PCap::Live.new(:dev => 'en0', 
+  FFI::PCap::Live.new(:dev => dev, 
+                      :timeout => 1,
                  :promisc => true, 
                  :handler => FFI::PCap::Handler)
 

data/examples/replay.rb

@@ -0,0 +1,11 @@
+
+require 'rubygems'
+require 'ffi/pcap'
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
+
+live = FFI::PCap::Live.new(:device => 'en0')
+offline = FFI::PCap::Offline.new("./foo.cap")
+
+if live.datalink == offline.datalink
+  offline.loop() {|this,pkt| live.inject(pkt) }
+end

data/examples/selectable_pcap.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+
+$: << File.expand_path( File.join(File.dirname(__FILE__), '../lib'))
+
+require 'rubygems'
+require 'ffi/pcap'
+require 'eventmachine'
+
+dev = ARGV.shift || 'lo0'
+if ARGV[0]
+  filter = ARGV.join(' ')
+end
+
+EM.run{
+  pcap = FFI::PCap::Live.new(:device => dev, :timeout => 1)
+  pcap.nonblocking=true
+  pcap.setfilter filter if filter
+
+  fd = pcap.fileno
+  io=IO.new(fd)
+  while Kernel.select([io],nil,nil)
+    p :meep
+    pcap.dispatch() do |this,pkt| 
+      puts pkt.time
+      puts pkt.body.bytes.map{|x| "%0.2x" % x}.join(' ')
+    end
+  end
+}
+

data/ffi-pcap.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'ffi/pcap/version'
+                  FFI::PCap::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end