capp 1.0

data/ext/capp/extconf.rb

@@ -0,0 +1,34 @@
+require 'mkmf'
+
+$CFLAGS << " #{ENV['CFLAGS']}" if ENV['CFLAGS']
+$LIBS   << " #{ENV['LIBS']}"   if ENV['LIBS']
+
+have_library 'pcap' or abort 'missing pcap library'
+
+def require_header header
+  have_header header or abort "missing #{header}"
+end
+
+require_header 'pcap/pcap.h'
+
+require_header 'sys/socket.h'
+require_header 'net/ethernet.h'
+require_header 'net/if_arp.h'
+require_header 'netinet/ip.h'
+require_header 'netinet/ip6.h'
+require_header 'netinet/ip_icmp.h'
+require_header 'arpa/inet.h'
+
+have_header 'net/if_dl.h'
+have_header 'netinet/ether.h'
+
+have_header 'ruby/thread.h'
+
+have_macro 'RETURN_ENUMERATOR' or abort 'missing C enumerator support'
+
+have_macro 'PCAP_WARNING_TSTAMP_TYPE_NOTSUP'
+have_macro 'PCAP_ERROR_PROMISC_PERM_DENIED'
+
+create_header
+create_makefile 'capp/capp'
+

data/ext/capp/structs.h

@@ -0,0 +1,86 @@
+/*
+ * The following items are copied from tcpdump.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ *   1. Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *   2. Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in
+ *      the documentation and/or other materials provided with the
+ *      distribution.
+ *   3. The names of the authors may not be used to endorse or promote
+ *      products derived from this software without specific prior
+ *      written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+ */
+
+typedef u_int32_t tcp_seq;
+
+/*
+ * TCP header.
+ * Per RFC 793, September, 1981.
+ */
+struct tcphdr {
+    u_int16_t       th_sport;               /* source port */
+    u_int16_t       th_dport;               /* destination port */
+    tcp_seq         th_seq;                 /* sequence number */
+    tcp_seq         th_ack;                 /* acknowledgement number */
+    u_int8_t        th_offx2;               /* data offset, rsvd */
+    u_int8_t        th_flags;
+    u_int16_t       th_win;                 /* window */
+    u_int16_t       th_sum;                 /* checksum */
+    u_int16_t       th_urp;                 /* urgent pointer */
+};
+
+#define TH_OFF(th)      (((th)->th_offx2 & 0xf0) >> 4)
+
+#define TH_FIN  0x01
+#define TH_SYN  0x02
+#define TH_RST  0x04
+#define TH_PUSH 0x08
+#define TH_ACK  0x10
+#define TH_URG  0x20
+#define TH_ECE  0x40
+#define TH_CWR  0x80
+
+/*
+ * Udp protocol header.
+ * Per RFC 768, September, 1981.
+ */
+struct udphdr {
+    u_int16_t       uh_sport;               /* source port */
+    u_int16_t       uh_dport;               /* destination port */
+    u_int16_t       uh_ulen;                /* udp length */
+    u_int16_t       uh_sum;                 /* udp checksum */
+};
+
+/*
+ * Byte-swap a 32-bit number.
+ * ("htonl()" or "ntohl()" won't work - we want to byte-swap even on
+ * big-endian platforms.)
+ */
+#define	SWAPLONG(y) \
+((((y)&0xff)<<24) | (((y)&0xff00)<<8) | (((y)&0xff0000)>>8) | (((y)>>24)&0xff))
+
+/*
+ * BSD AF_ values.
+ *
+ * Unfortunately, the BSDs don't all use the same value for AF_INET6,
+ * so, because we want to be able to read captures from all of the BSDs,
+ * we check for all of them.
+ */
+#define BSD_AFNUM_INET          2
+#define BSD_AFNUM_NS            6  /* XEROX NS protocols */
+#define BSD_AFNUM_ISO           7
+#define BSD_AFNUM_APPLETALK     16
+#define BSD_AFNUM_IPX           23
+#define BSD_AFNUM_INET6_BSD     24 /* OpenBSD (and probably NetBSD), BSD/OS */
+#define BSD_AFNUM_INET6_FREEBSD 28
+#define BSD_AFNUM_INET6_DARWIN  30
+

data/lib/capp.rb

@@ -0,0 +1,168 @@
+require 'socket'
+
+##
+# Capp is a GVL-friendly libpcap wrapper library.
+#
+# To create a packet capture device:
+#
+#   capp = Capp.live
+#
+# This listens on the default device.  You can list devices with Capp.devices.
+#
+# To start capture use #loop:
+#
+#   capp.loop do |packet|
+#     # ...
+#   end
+#
+# #loop yields a Capp::Packet object for each captured packet.
+#
+# To stop capturing packets return (or break) from the loop, or call #stop on
+# the Capp instance.  You can resume capturing packets by calling #loop again
+# after #stop.
+#
+# To set a filter for only udp port 7647 (Rinda::RingFinger packets):
+#
+#   capp.filter = 'udp port 7647'
+#
+# The format for a filter rule is the same as for tcpdump.  See the
+# pcap-filter(7) man page for the filter syntax.
+#
+# You can use a Queue to capture packets in one thread and process them in
+# another:
+#
+#   require 'capp'
+#   require 'thread'
+#
+#   q = Queue.new
+#
+#   Thread.new do
+#     while packet = q.deq do
+#       # ...
+#     end
+#   end
+#
+#   capp = Capp.live.loop do |packet|
+#     q.enq packet
+#   end
+
+class Capp
+
+  ##
+  # The version of Capp you are using
+
+  VERSION = '1.0'
+
+  ##
+  # Error class for Capp errors
+
+  class Error < RuntimeError
+  end
+
+  ##
+  # An address for a Device which is returned by Capp::devices
+
+  Address = Struct.new :address, :netmask, :broadcast, :destination
+
+  ##
+  # A device which Capp can listen on, returned by Capp::devices
+
+  Device = Struct.new :name, :description, :addresses, :flags do
+
+    ##
+    # Creates a new packet capture device for this device sending the given
+    # +args+ to Capp.open.
+
+    def open *args
+      Capp.open name, *args
+    end
+
+  end
+
+  ##
+  # Device name packets are being captured from.  Only set for live packet
+  # captures.
+
+  attr_reader :device
+
+  ##
+  # Drops root privileges to the given +run_as_user+ and optionally chroots to
+  # +run_as_directory+.  Use this method after creating a packet capture
+  # instance to improve security.
+  #
+  # Returns true if privileges are dropped, raises a Capp::Error if privileges
+  # could not be dropped and returns a false value if there was no need to
+  # drop privileges.
+  #
+  # You will be able to start and stop packet capture but not create new
+  # packet capture instances after dropping privileges.
+
+  def self.drop_privileges run_as_user, run_as_directory = nil
+    return unless Process.uid.zero? and Process.euid.zero?
+    return unless run_as_user or run_as_directory
+
+    raise Capp::Error, 'chroot without dropping root is insecure' if
+      run_as_directory and not run_as_user
+
+    require 'etc'
+
+    begin
+      pw = if Integer === run_as_user then
+             Etc.getpwuid run_as_user
+           else
+             Etc.getpwnam run_as_user
+           end
+    rescue ArgumentError => e
+      raise Capp::Error, "could not find user #{run_as_user}"
+    end
+
+    if run_as_directory then
+      begin
+        Dir.chroot run_as_directory
+        Dir.chdir '/'
+      rescue Errno::ENOENT => e
+        raise Capp::Error, "could not chroot to #{run_as_directory} " +
+                           "or change to chroot directory"
+      end
+    end
+
+    begin
+      Process.gid = pw.gid
+      Process.uid = pw.uid
+    rescue Errno::EPERM => e
+      raise Capp::Error, "unable to drop privileges to #{run_as_user} " +
+                         "(#{e.message})"
+    end
+
+    true
+  end
+
+  ##
+  # Opens +device_or_file+ as an offline device if it is an IO or an existing
+  # file.  +args+ are ignored (as ::offline does not support any).
+  #
+  # Opens +device_or_file+ as a live device otherwise, along with +args+.  See
+  # ::live for documentation on the additional arguments.
+
+  def self.open device_or_file, *args
+    if IO === device_or_file or File.exist? device_or_file then
+      offline device_or_file, *args
+    else
+      live device_or_file, *args
+    end
+  end
+
+  ##
+  # When called on a capture instance created from a savefile, returns the
+  # version of the savefile.  When called on a live capture instance it
+  # returns a meaningless value.
+
+  def savefile_version
+    "#{savefile_major_version}.#{savefile_minor_version}"
+  end
+
+end
+
+require 'capp/packet'
+require 'capp/capp'
+

data/lib/capp/packet.rb

@@ -0,0 +1,402 @@
+# coding: BINARY
+
+##
+# Capp::Packet provides convenient extraction of data from packets.
+#
+# Packet objects are automatically created when a packet is read from the
+# opened interface.  Unfortunately Capp does not understand every type of
+# packet.  If Capp doesn't understand your packet the layer 3 payload can be
+# retrieved from unknown_layer3_header.
+#
+# If Capp doesn't understand your packets you can extract the data by editing
+# capp.c and submitting a patch.  See README for the source code location.
+#
+# To look up IP source and destination names Resolv (from the ruby standard
+# library, require 'resolv') to avoid blocking on name lookups in a
+# cross-platform manner.
+
+class Capp::Packet
+
+  ADDRESS_CACHE = {} # :nodoc:
+
+  ##
+  # ARP header.  See RFC 826
+
+  ARPHeader = Struct.new :hardware, :protocol, :operation,
+                         :sender_hardware_address, :sender_protocol_address,
+                         :target_hardware_address, :target_protocol_address do
+    alias sha sender_hardware_address
+    alias spa sender_protocol_address
+    alias tha target_hardware_address
+    alias tpa target_protocol_address
+  end
+
+  ##
+  # 802.3 Ethernet header
+
+  EthernetHeader = Struct.new :destination, :source, :type
+
+  ##
+  # ICMP header.  See RFC 792
+
+  ICMPHeader = Struct.new :type, :code, :checksum, :data
+
+  ##
+  # IPv4 header.  See RFC 791
+
+  IPv4Header = Struct.new :version, :ihl, :tos, :length,
+                          :id, :offset,
+                          :ttl, :protocol, :checksum,
+                          :source, :destination
+
+  ##
+  # IPv6 header.  See RFC 2460
+
+  IPv6Header = Struct.new :version, :traffic_class, :flow_label,
+                          :payload_length, :next_header, :hop_limit,
+                          :source, :destination
+
+  ##
+  # TCP header.  See RFC 793
+
+  TCPHeader = Struct.new :source_port, :destination_port,
+                         :seq_number, :ack_number,
+                         :offset, :flags, :window, :checksum, :urgent do
+
+    alias source      source_port
+    alias destination destination_port
+
+    ##
+    # Is the acknowledgment flag set?
+
+    def ack?
+      Capp::TCP_ACK == flags & Capp::TCP_ACK
+    end
+
+    ##
+    # Is the congestion window reduced flag set?
+
+    def cwr?
+      Capp::TCP_CWR == flags & Capp::TCP_CWR
+    end
+
+    ##
+    # Is the explicit congestion notification echo flag set?
+
+    def ece?
+      Capp::TCP_ECE == flags & Capp::TCP_ECE
+    end
+
+    ##
+    # Is the no-more-data flag set?
+
+    def fin?
+      Capp::TCP_FIN == flags & Capp::TCP_FIN
+    end
+
+    ##
+    # Is the push flag set?
+
+    def push?
+      Capp::TCP_PUSH == flags & Capp::TCP_PUSH
+    end
+
+    ##
+    # Is the reset flag set?
+
+    def rst?
+      Capp::TCP_RST == flags & Capp::TCP_RST
+    end
+
+    ##
+    # Is the synchronize flag set?
+
+    def syn?
+      Capp::TCP_SYN == flags & Capp::TCP_SYN
+    end
+
+    ##
+    # Is the urgent flag set?
+
+    def urg?
+      Capp::TCP_URG == flags & Capp::TCP_URG
+    end
+
+  end
+
+  ##
+  # UDP header.  See RFC 768
+
+  UDPHeader = Struct.new :source_port, :destination_port, :length, :checksum do
+    alias source      source_port
+    alias destination destination_port
+  end
+
+  ##
+  # Fake header for an unknown layer 3 protocol.  See also
+  # Capp::Packet#unknown_layer3_header
+
+  UnknownLayer3Header = Struct.new :payload_offset
+
+  ##
+  # Length of packet that was captured
+
+  attr_reader :capture_length
+
+  ##
+  # Captured portion of the entire packet including datalink layer.
+
+  attr_reader :captured
+
+  ##
+  # The ARP header if this is an ARP packet.
+
+  attr_reader :arp_header
+
+  ##
+  # The Ethernet header if this is an Ethernet packet.
+
+  attr_reader :ethernet_header
+
+  ##
+  # Array of protocol names in this packet.  This list is ordered from lowest
+  # to highest level.
+
+  attr_reader :protocols
+
+  ##
+  # ICMP header if this is an ICMP (v4) packet.
+
+  attr_reader :icmp_header
+
+  ##
+  # IPv4 header if this is an IPv4 packet.
+
+  attr_reader :ipv4_header
+
+  ##
+  # IPv6 header if this is an IPv6 packet.
+
+  attr_reader :ipv6_header
+
+  ##
+  # Total length of packet including the portion not captured.
+
+  attr_reader :length
+
+  ##
+  # TCP header if this is a TCP packet.
+
+  attr_reader :tcp_header
+
+  ##
+  # Packet capture timestamp
+
+  attr_reader :timestamp
+
+  ##
+  # UDP header if this is a UDP packet.
+
+  attr_reader :udp_header
+
+  ##
+  # Fake header for unknown layer 3 protocols.  The datalink type will
+  # indicate the layer 3 protocol.  For an Ethernet packet see the
+  # ethernet_header for the type, etc.  This method only provides the payload
+  # offset of the packet content.
+
+  attr_reader :unknown_layer3_header
+
+  ##
+  # Creates a new packet.  Ordinarily this is performed from Capp#loop.  The
+  # +timestamp+ is the packet capture timestamp, +length+ is the total length
+  # of the packet, +capture_length+ is the number of captured bytes from the
+  # packet.  The +datalink+ is the type of link the packet was captured on.
+  # +headers+ is a Hash of parsed headers.
+
+  def initialize timestamp, length, capture_length, captured, datalink, headers
+    @capture_length = capture_length
+    @captured       = captured
+    @datalink       = datalink
+    @length         = length
+    @protocols      = headers.keys
+    @timestamp      = timestamp
+
+    @arp_header            = headers[:arp]
+    @ethernet_header       = headers[:ethernet]
+    @icmp_header           = headers[:icmp]
+    @ipv4_header           = headers[:ipv4]
+    @ipv6_header           = headers[:ipv6]
+    @tcp_header            = headers[:tcp]
+    @udp_header            = headers[:udp]
+    @unknown_layer3_header = headers[:unknown_layer3]
+  end
+
+  ##
+  # Returns the destination of the packet regardless of protocol
+  #
+  # If a Resolv-compatible +resolver+ is given the name will be looked up.
+
+  def destination resolver = nil
+    destination =
+      if ipv4? then
+        @ipv4_header
+      elsif ipv6? then
+        @ipv6_header
+      else
+        raise NotImplementedError
+      end.destination
+
+    destination = resolve destination, resolver
+
+    if tcp? then
+      destination << ".#{@tcp_header.destination_port}"
+    elsif udp? then
+      destination << ".#{@udp_header.destination_port}"
+    end
+
+    destination
+  end
+
+  ##
+  # Returns the captured bytes with non-printing characters replaced by "."
+
+  def dump
+    @captured.tr "\000-\037\177-\377", "."
+  end
+
+  ##
+  # Dumps the captured packet from +offset+ with offsets, hexadecimal output
+  # for the bytes and the ASCII content with non-printing characters replaced
+  # by "."
+
+  def hexdump offset = 0
+    data = @captured[offset, @capture_length]
+
+    data.scan(/.{,16}/m).map.with_index do |chunk, index|
+      next nil if chunk.empty?
+      hex  = chunk.unpack('C*').map { |byte| '%02x' % byte }
+      dump = chunk.tr "\000-\037\177-\377", "."
+
+      length = hex.length
+      hex.fill '  ', length, 16 - length if length < 16
+
+      "\t0x%04x:  %s%s %s%s %s%s %s%s %s%s %s%s %s%s %s%s  %s" % [
+        index * 16, *hex, dump
+      ]
+    end.join "\n"
+  end
+
+  ##
+  # The payload of the packet.
+  #
+  # For example, for a UDP packet captured from an Ethernet interface this is
+  # payload after the Ethernet, IP and UDP headers
+
+  def payload
+    @captured[payload_offset, @capture_length]
+  end
+
+  ##
+  # The offset into the captured data where the payload starts.
+  #
+  # Note that this method does not work properly for IPv6 packets with options
+  # set, but I have yet to encounter such an example in the wild.
+
+  def payload_offset
+    offset =
+      case @datalink
+      when Capp::DLT_NULL then
+        4
+      when Capp::DLT_EN10MB then
+        14
+      end
+
+    case
+    when ipv4? then offset += @ipv4_header.ihl * 4
+    when ipv6? then offset += 40
+    else            raise NotImplementedError
+    end
+
+    case
+    when tcp? then offset += @tcp_header.offset * 4
+    when udp? then offset += 8
+    else           raise NotImplementedError
+    end
+
+    offset
+  end
+
+  def resolve address, resolver # :nodoc:
+    return address.dup unless resolver
+
+    if name = ADDRESS_CACHE[address] then
+      return name.dup
+    end
+
+    name = resolver.getname address
+
+    ADDRESS_CACHE[address] = name
+
+    name.dup
+  rescue Resolv::ResolvError
+    ADDRESS_CACHE[address] = address
+    address.dup
+  end
+
+  ##
+  # Returns the source of the packet regardless of protocol.
+  #
+  # If a Resolv-compatible +resolver+ is given the name will be looked up.
+
+  def source resolver = nil
+    source =
+      if ipv4? then
+        @ipv4_header
+      elsif ipv6? then
+        @ipv6_header
+      else
+        raise NotImplementedError
+      end.source.dup
+
+    source = resolve source, resolver
+
+    if tcp? then
+      source << ".#{@tcp_header.source_port}"
+    elsif udp? then
+      source << ".#{@udp_header.source_port}"
+    end
+
+    source
+  end
+
+  ##
+  # Is this an IPv4 packet?
+
+  def ipv4?
+    @ipv4_header
+  end
+
+  ##
+  # Is this an IPv6 packet?
+
+  def ipv6?
+    @ipv6_header
+  end
+
+  ##
+  # Is this a TCP packet?
+
+  def tcp?
+    @tcp_header
+  end
+
+  ##
+  # Is this a UDP packet?
+
+  def udp?
+    @udp_header
+  end
+
+end
+