packetgen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b95374a3ba00773c1a45e0464a797b1173aa4285
+  data.tar.gz: 4a6e2f8b12b6552de7afdca695e99221453439c1
+SHA512:
+  metadata.gz: 95ddd04f2758a1ef9f17d0b343ea9b00f718ad926adbf13bdd3bc9444e3d8a3cf980a8a8c7e3f5ebebf27a775da676f1754f86cf1dd15756c03fa76a1901184c
+  data.tar.gz: 145591b54094dcac9690e483138f123597029b12659c95d5ee1d7c14865f654003b17c24fd75a46647fe6c0864bccdff69bfd6e7e28623e2b3024628c447d073

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/vendor/
+*~
+

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+sudo: required
+rvm:
+  - 2.1
+  - 2.2
+  - 2.3.3
+
+install:
+  - sudo apt-get update -qq
+  - sudo apt-get install libpcap-dev -qq
+  - bundler install --path vendor/bundle --jobs=3 --retry=3
+script:
+  - bundler exec rake
+  - rvmsudo bundle exec rake spec:sudo

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in packetgen.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Sylvain Daubert
+
+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.md

@@ -0,0 +1,116 @@
+
+[![Build Status](https://travis-ci.org/sdaubert/packetgen.svg?branch=master)](https://travis-ci.org/sdaubert/packetgen)
+
+# PacketGen
+
+PacketGen aims at generate and capture network packets easily.
+
+## Why PacketGen
+Why create PacketGen ? There is already PacketFu!
+
+Yes. But PacketFu is limited:
+* upper protocols use fixed layers: TCP always uses IPv4, IP and IPv6 always uses Ethernet as MAC,...
+* cannot handle tunneled packets (IP-in-IP, or deciphered ESP packets,...)
+* cannot easily encapsulate or decapsulate packets
+* parse packets top-down, and sometimes bad parse down layers
+* cannot send packet on wire at IP/IPv6 level (Ethernet header is mandatory)
+
+## use cases
+
+For now, PacketGen is only a concept...
+
+### Easily create packets
+```
+PacketGen.gen('IP')             # generate a IP packet object
+PacketGen.gen('TCP')            # generate a TCP over IP packet object
+PacketGen.gen('IP').add('TCP')  # the same
+PacketGen.gen('Eth')            # generate a Ethernet packet object
+PacketGen.gen('IP').add('IP')   # generate a IP-in-IP tunnel packet object
+
+# Generate a IP packet object, specifying addresses
+PacketGen.gen('IP', src: '192.168.1.1', dst: '192.168.1.2')
+
+# get binary packet
+PacketGen.gen('IP').to_s
+```
+
+### Send packets on wire
+need PcapRub for Ethernet packets. Need a C extension (use of C socket API) for IP packets.
+
+```
+# send Ethernet packet
+PacketGen.gen('Eth', src: '00:00:00:00:01', dst: '00:00:00:00:02').to_w
+# send IP packet
+PacketGen.gen('IP', src: '192.168.1.1', dst: '192.168.1.2').to_w
+# send forged IP packet over Ethernet
+PacketGen.gen('Eth', src: '00:00:00:00:01', dst: '00:00:00:00:02').add('IP').to_w('eth1')
+```
+
+### Parse packets from binary data
+```
+packet = PacketGen.parse(binary_data)
+```
+
+### Capture packets from wire
+need PCapRub.
+
+```
+# Capture packets, action from a block
+PacketGen.capture('eth0') do |packet|
+  do_stuffs_with_packet
+end
+
+# Capture some packets, and act on them afterward
+packets = PacketGen.capture('eth0', max: 10)   # return when 10 packets were captured
+
+# Use filters
+packets = PacketGen.capture('eth0', filter: 'ip src 1.1.1.2', max: 1)
+```
+
+### Easily manipulate packets
+```
+# access header fields
+pkt = PacketGen.gen('IP').add('TCP')
+pkt.ip.src = '192.168.1.1'
+pkt.ip(src: '192.168.1.1', ttl: 4)
+pkt.tcp.dport = 80
+
+# access header fields when multiple header of one kind exist
+pkt = PacketGen.gen('IP').add('IP')
+pkt.ip.src = '192.168.1.1'  # set outer src field
+pkt.ip(2).src = '10.0.0.1'  # set inner src field
+
+# test packet types
+pkt = PacketGen.gen('IP').add('TCP')
+pkt.is? 'TCP'   # => true
+pkt.is? 'IP'    # => true
+pkt.is? 'UDP'   # => false
+
+# encapulsate/decapsulate packets
+pkt2 = PacketGen.gen('IP').add('ESP', spi: 1234)
+pkt.encap pkt2                         # pkt is now a IP/ESP/IP/TCP packet
+                                       # eq. to pkt.encap('IP', 'ESP', esp_spi: 1234)
+pkt.decap('IP', 'ESP')                 # pkt is now inner IP/TCP packet
+```
+
+### Read/write PcapNG files
+```
+# read a PcapNG file, containing multiple packets
+packets = PacketGen.read('file.pcapng')
+packets.first.udp.sport = 65535
+# write only one packet to a PcapNG file
+pkt.write('one_packet.pcapng')
+# write multiple packets to a PcapNG file
+PacketGen.write('more_packets.pcapng', packets)
+```
+
+## License
+MIT License (see [LICENSE](https://github.com/sdaubert/packetgen/LICENSE))
+
+Copyright © 2016 Sylvain Daubert
+
+### Other sources
+All original code maintains its copyright from its original authors and licensing.
+
+This is mainly for StrucFu (copied from [PacketFu](https://github.com/packetfu/packetfu))
+and PcapNG module (also copied from PacketFu, but I am the author).

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+task :default => :spec
+
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = '-t ~sudo'
+end
+RSpec::Core::RakeTask.new('spec:sudo') do |t|
+  t.rspec_opts = '-t sudo'
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ['--no-private']
+  t.files = ['lib/**/*.rb', '-', 'LICENSE']
+end
+

data/lib/packetgen.rb

@@ -0,0 +1,83 @@
+require 'packetgen/version'
+
+# @author Sylvain Daubert
+module PacketGen
+
+  # Base exception class for PacketGen exceptions
+  class Error < StandardError; end
+
+  # Packet badly formatted
+  class FormatError < Error; end
+
+  # Parsing error
+  class ParseError < Error; end
+
+  # Sending packet on wire error
+  class WireError < Error; end
+
+  # Shortcut for {Packet.gen}
+  # @param [String] protocol base protocol for packet
+  # @param [Hash] options specific options for +protocol+
+  # @return [Packet]
+  def self.gen(protocol, options={})
+    Packet.gen protocol, options
+  end
+
+  # Shortcut for {Packet.parse}
+  # @param [String] binary_str
+  # @param [String] first_header First protocol header
+  # @return [Packet]
+  def self.parse(binary_str, first_header: nil)
+    Packet.parse binary_str, first_header
+  end
+
+  # Shortcut for {Packet.capture}
+  # @param [String] iface interface name
+  # @param [Hash] options capture options. See {Packet.capture}.
+  # @yieldparam [Packet] packet
+  # @return [Array<Packet>]
+  def self.capture(iface, options={})
+    Packet.capture(iface, options) { |packet| yield packet }
+  end
+
+  # Shortcut for {Packet.read}
+  # @param [String] filename PcapNG file
+  # @return [Array<Packet>]
+  def self.read(filename)
+    Packet.read filename
+  end
+
+  # Shortcut for {Packet.write}
+  # @param [String] filename
+  # @param [Array<Packet>] packets packets to write
+  # @return [void]
+  def self.write(filename, packets)
+    Packet.write filename, packets
+  end
+
+  # Force binary encoding for +str+
+  # @param [String] str
+  # @return [String] binary encoded string
+  def self.force_binary(str)
+    str.force_encoding Encoding::BINARY
+  end
+
+  # Get default network interface (ie. first non-loopback declared interface)
+  # @return [String]
+  def self.default_iface
+    return @default_iface if @default_iface
+
+    ipaddr = `ip addr`.split("\n")
+    @default_iface = ipaddr.each_with_index do |line, i|
+      m = line.match(/^\d+: (\w+\d+):/)
+      next if m.nil?
+      next if m[1] == 'lo'
+      break m[1]
+    end
+  end
+end
+
+require 'packetgen/structfu'
+require 'packetgen/packet'
+require 'packetgen/capture'
+require 'packetgen/pcapng'

data/lib/packetgen/capture.rb

@@ -0,0 +1,105 @@
+module PacketGen
+
+  # Capture packets from wire
+  # @author Sylvain Daubert
+  class Capture
+
+    # Default snaplen to use if :snaplen option not defined
+    DEFAULT_SNAPLEN = 0xffff
+
+    # Get captured packets
+    # @return [Array<Packets>]
+    attr_reader :packets
+
+    # Get captured packet raw data
+    # @return [Array<String>]
+    attr_reader :raw_packets
+
+    # @param [String] iface interface on which capture packets
+    # @param [Hash] options
+    # @option options [Integer] :max maximum number of packets to capture
+    # @option options [Integer] :timeout maximum number of seconds before end
+    #    of capture. Default: +nil+ (no timeout)
+    # @option options [String] :filter bpf filter
+    # @option options [Boolean] :promiscuous (default: +false+)
+    # @option options [Boolean] :parse parse raw data to generate packets before
+    #    yielding.  Default: +true+
+    # @option options [Integer] :snaplen maximum number of bytes to capture for
+    #    each packet
+    def initialize(iface, options={})
+      @packets = []
+      @raw_packets = []
+      @iface = iface
+      set_options options
+    end
+
+    # Start capture
+    # @param [Hash] options complete see {#initialize}.
+    # @yieldparam [Packet,String] packet if a block is given, yield each
+    #    captured packet (Packet or raw data String, depending on +:parse+)
+    def start(options={})
+      set_options options
+      @pcap = PCAPRUB::Pcap.open_live(@iface, @snaplen, @promisc, 1)
+      set_filter
+
+      @cap_thread = Thread.new do
+        @pcap.each do |packet_data|
+          @raw_packets << packet_data
+          if @parse
+            packet = Packet.parse(packet_data)
+            @packets << packet
+            yield packet if block_given?
+          else
+            yield packet_data if block_given?
+          end
+          if @max
+            break if @raw_packets.size >= @max
+          end
+        end
+      end
+      @cap_thread.join(@timeout)
+    end
+
+    # Stop capture. Should be used from another thread, as {#start} blocs.
+    #
+    # BEWARE: multiple capture should not be started in different threads. No effort
+    # has been made to make Capture nor PacketGen thread-safe.
+    # @return [void]
+    def stop
+      @cap_thread.kill
+    end
+
+    private
+
+    def set_options(options)
+      @max = options[:max] if options[:max]
+      @filter = options[:filter] if options[:filter]
+      if options[:timeout]
+        @timeout = options[:timeout]
+      else
+        @timeout ||= 0
+      end
+      if options[:promisc]
+        @promisc = options[:promisc]
+      else
+        @promisc ||= false
+      end
+      if options[:snaplen]
+        @snaplen = options[:snaplen]
+      else
+        @snaplen ||= DEFAULT_SNAPLEN
+      end
+      if options[:parse].nil?
+        @parse = true if @parse.nil?
+      else
+        @parse = options[:parse]
+      end
+    end
+
+    def set_filter
+      return if @filter.nil?
+      return if @filter.empty?
+      @pcap.setfilter @filter
+    end
+  end
+end

data/lib/packetgen/header.rb

@@ -0,0 +1,21 @@
+module PacketGen
+  # Namespace for protocol header classes
+  # @author Sylvain Daubert
+  module Header
+
+    # Get known header classes
+    # @return [Array<Class>]
+    def self.all
+      constants.map { |sym| const_get sym }.
+        select { |klass| klass < Struct && klass < HeaderMethods }
+    end
+  end
+end
+
+require_relative 'header/header_class_methods'
+require_relative 'header/header_methods'
+require_relative 'header/eth'
+require_relative 'header/ip'
+require_relative 'header/arp'
+require_relative 'header/ipv6'
+require_relative 'header/udp'

data/lib/packetgen/header/arp.rb

@@ -0,0 +1,148 @@
+module PacketGen
+  module Header
+
+    # ARP header class
+    # @author Sylvain Daubert
+    class ARP < Struct.new(:hw_type, :proto, :hw_len, :proto_len, :opcode,
+                          :src_mac, :src_ip, :dst_mac, :dst_ip, :body)
+      include StructFu
+      include HeaderMethods
+      extend HeaderClassMethods
+
+      # @param [Hash] options
+      # @option options [Integer] :hw_type network protocol type (default: 1)
+      # @option options [Integer] :proto internet protocol type (default: 0x800)
+      # @option options [Integer] :hw_len length of hardware addresses (default: 6)
+      # @option options [Integer] :proto_len length of internet addresses (default: 4)
+      # @option options [Integer] :opcode operation performing by sender (default: 1).
+      #   known values are +request+ (1) and +reply+ (2)
+      # @option options [String] :src_mac sender hardware address
+      # @option options [String] :src_ip sender internet address
+      # @option options [String] :dst_mac target hardware address
+      # @option options [String] :dst_ip targetr internet address
+       def initialize(options={})
+        super Int16.new(options[:hw_type] || 1),
+              Int16.new(options[:proto] || 0x800),
+              Int8.new(options[:hw_len] || 6),
+              Int8.new(options[:proto_len] || 4),
+              Int16.new(options[:opcode] || 1),
+              Eth::MacAddr.new.parse(options[:src_mac]),
+              IP::Addr.new.parse(options[:src_ip]),
+              Eth::MacAddr.new.parse(options[:dst_mac]),
+              IP::Addr.new.parse(options[:dst_ip]),
+              StructFu::String.new.read(options[:body])
+      end
+
+      # Read a ARP header from a string
+      # @param [String] str binary string
+      # @return [self]
+      def read(str)
+        force_binary str
+        raise ParseError, 'string too short for ARP' if str.size < self.sz
+        self[:hw_type].read str[0, 2]
+        self[:proto].read str[2, 2]
+        self[:hw_len].read str[4, 1]
+        self[:proto_len].read str[5, 1]
+        self[:opcode].read str[6, 2]
+        self[:src_mac].read str[8, 6]
+        self[:src_ip].read str[14, 4]
+        self[:dst_mac].read str[18, 6]
+        self[:dst_ip].read str[24, 4]
+        self[:body].read str[28..-1]
+      end
+
+      # @!attribute [rw] hw_type
+      # @return [Integer]
+      def hw_type
+        self[:hw_type].to_i
+      end
+      
+      def hw_type=(i)
+        self[:hw_type].read i
+      end
+
+      # @!attribute [rw] proto
+      # @return [Integer]
+      def proto
+        self[:proto].to_i
+      end
+      
+      def proto=(i)
+        self[:proto].read i
+      end
+
+      # @!attribute [rw] hw_len
+      # @return [Integer]
+      def hw_len
+        self[:hw_len].to_i
+      end
+      
+      def hw_len=(i)
+        self[:hw_len].read i
+      end
+
+      # @!attribute [rw] proto_len
+      # @return [Integer]
+      def proto_len
+        self[:proto_len].to_i
+      end
+      
+      def proto_len=(i)
+        self[:proto_len].read i
+      end
+
+      # @!attribute [rw] opcode
+      # @return [Integer]
+      def opcode
+        self[:opcode].to_i
+      end
+      
+      def opcode=(i)
+        self[:opcode].read i
+      end
+
+      # @!attribute [rw] src_mac
+      # @return [String]
+      def src_mac
+        self[:src_mac].to_x
+      end
+      
+      def src_mac=(addr)
+        self[:src_mac].parse addr
+      end
+
+      # @!attribute [rw] src_ip
+      # @return [String]
+      def src_ip
+        self[:src_ip].to_x
+      end
+      
+      def src_ip=(addr)
+        self[:src_ip].parse addr
+      end
+
+      # @!attribute [rw] dst_mac
+      # @return [String]
+      def dst_mac
+        self[:dst_mac].to_x
+      end
+      
+      def dst_mac=(addr)
+        self[:dst_mac].parse addr
+      end
+
+      # @!attribute [rw] dst_ip
+      # @return [String]
+      def dst_ip
+        self[:dst_ip].to_x
+      end
+      
+      def dst_ip=(addr)
+        self[:dst_ip].parse addr
+      end
+    end
+
+    Eth.bind_header ARP, proto: 0x806
+  end
+end
+