packetgen 2.8.7 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9619d169e7a064e415e479dd208f15339f59700baf805bbc7a79437967c1cd5
-  data.tar.gz: 4d1ceeeee51b56dab91331e43672b7fe15ddeb87971bb36bc5670399f2e55080
+  metadata.gz: 072c0bb14448db25532a552f9b8a5c83b2363d7ccb3692d478f3224a8cc34807
+  data.tar.gz: b2b857e9793aa1dabf0a89562958187087afabb10318cf947d9c2ce12696c39d
 SHA512:
-  metadata.gz: a0a27dd879ec6c9362bade001b6f6701686f80a589d2dd75478f5894dbaf8bd5b766f00f692437dca4ecbf96ceb830d4fcfeaef2e2354bccec7addd76f4b7ab8
-  data.tar.gz: bfb2b7de3b541c85cd1d367b4d8976d78d47c9872cabafd46cba12751926128f6a664c687520b28b7224af8439829219f9f6ad5a950de5878c9ee6f1d9b14243
+  metadata.gz: d5bb7c964881ae0f2df1845d82b449cf1a80c25432c740dc1e7ce6436b4323e03586d40760939d554daba0080a15d776cbe8b7fed04c07983a77aaad9c2e0e3d
+  data.tar.gz: 9a2d0bd3355ec82bb40c0ed3a4377852314e74bb6f3479142810d637ca5f189279c7d8f3ae0bc59eea6ffc8f91d19264a2d0ced8d39c49cfc91a9d004d9bbe47

data/.rubocop.yml

@@ -1,4 +1,3 @@
-TargetRubyVersion: 2.3
 Layout/SpaceAroundEqualsInParameterDefault:
   EnforcedStyle: no_space
 Lint/EmptyWhen:

data/README.md

@@ -114,8 +114,8 @@ First, define the new header class. For example:
 ```ruby
 module MyModule
  class MyHeader < PacketGen::Header::Base
-   define_field :field1, PacketGen::Types::Int32   
-   define_field :field2, PacketGen::Types::Int32   
+   define_field :field1, PacketGen::Types::Int32
+   define_field :field2, PacketGen::Types::Int32
  end
 end
 ```
@@ -161,8 +161,9 @@ If `pry` gem is installed, it is used as backend for `pgconsole`, else IRB is us
 
 PacketGen provides a plugin system (see [wiki](https://github.com/sdaubert/packetgen/wiki/Create-Custom-Protocol)).
 
-For now, there is only one plugin available as a gem:
+Available plugins (available as gem) are:
 
+* [packetgen-plugin-ipsec](https://github.com/sdaubert/packetgen-plugin-ipsec): add support for ESP and IKEv2 protocols. Before PacketGen3, these protocols were included in packetgen.
 * [packetgen-plugin-smb](https://github.com/sdaubert/packetgen-plugin-smb): add (limited) support for SMB protocol suite.
 
 ## See also
@@ -173,7 +174,7 @@ API documentation: http://www.rubydoc.info/gems/packetgen
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/sdaubert/packetgen-plugin-smb.
+Bug reports and pull requests are welcome on GitHub at https://github.com/sdaubert/packetgen.
 
 ## License
 

data/lib/packetgen.rb

@@ -7,6 +7,7 @@
 # frozen_string_literal: true
 
 require 'packetgen/version'
+require 'interfacez'
 
 # PacketGen is a network packet generator and analyzor.
 # @author Sylvain Daubert
@@ -40,11 +41,12 @@ module PacketGen
   end
 
   # Shortcut for {Packet.capture}
-  # @param [Hash] options capture options. See {Packet.capture}.
+  # Same arguments as {Capture#initialize}
+  # @see Capture#initialize
   # @yieldparam [Packet] packet
   # @return [Array<Packet>]
-  def self.capture(options={})
-    Packet.capture(options) { |packet| yield packet if block_given? }
+  def self.capture(**kwargs)
+    Packet.capture(kwargs) { |packet| yield packet if block_given? }
   end
 
   # Shortcut for {Packet.read}
@@ -72,15 +74,7 @@ module PacketGen
   # 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 do |line|
-      m = line.match(/^\d+: (\w+\d+):/)
-      next if m.nil?
-      next if m[1].start_with? 'lo'
-      break m[1]
-    end
+    Interfacez.default
   end
 
   # Shortcut to get a header class

data/lib/packetgen/capture.rb

@@ -5,8 +5,6 @@
 
 # frozen_string_literal: true
 
-require 'interfacez'
-
 module PacketGen
   # Capture packets from wire
   # @author Sylvain Daubert
@@ -15,6 +13,12 @@ module PacketGen
     # Default snaplen to use if :snaplen option not defined.
     DEFAULT_SNAPLEN = 0xffff
 
+    private
+
+    attr_reader :filter, :cap_thread
+
+    public
+
     # Get captured packets.
     # @return [Array<Packets>]
     attr_reader :packets
@@ -27,53 +31,53 @@ module PacketGen
     # @return [String]
     attr_reader :iface
 
-    # @param [Hash] options
-    # @option options [String]  :iface interface on which capture
+    # @param [String] iface interface on which capture
     #    packets on. Default: Use default interface lookup. If no interface found,
     #    use loopback one.
-    # @option options [Integer] :max maximum number of packets to capture.
-    # @option options [Integer] :timeout maximum number of seconds before end
+    # @param [Integer] max maximum number of packets to capture.
+    # @param [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
+    # @param [String] filter bpf filter
+    # @param [Boolean] promisc (default: +false+)
+    # @param [Boolean] parse parse raw data to generate packets before
     #    yielding.  Default: +true+
-    # @option options [Integer] :snaplen maximum number of bytes to capture for
+    # @param [Integer] snaplen maximum number of bytes to capture for
     #    each packet.
     # @since 2.0.0 remove old 1.x API
-    def initialize(options={})
-      @iface = Interfacez.default || Interfacez.loopback
+    # @since 3.0.0 arguments are kwargs and nor more a hash
+    def initialize(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: DEFAULT_SNAPLEN)
+      @iface = iface || Interfacez.default || Interfacez.loopback
 
       @packets     = []
       @raw_packets = []
-      @promisc = false
-      @snaplen = DEFAULT_SNAPLEN
-      @parse = true
-      set_options options
+      set_options iface, max, timeout, filter, promisc, parse, snaplen
     end
 
     # Start capture
-    # @param [Hash] options complete see {#initialize}.
+    # @see {#initialize} for parameters
     # @yieldparam [Packet,String] packet if a block is given, yield each
     #    captured packet (Packet or raw data String, depending on +:parse+ option)
-    def start(options={})
-      set_options options
-      @pcap = PCAPRUB::Pcap.open_live(@iface, @snaplen, @promisc, 1)
-      set_filter
+    # @since 3.0.0 arguments are kwargs and nor more a hash
+    def start(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: DEFAULT_SNAPLEN)
+      set_options iface, max, timeout, filter, promisc, parse, snaplen
+
+      pcap = PCAPRUB::Pcap.open_live(self.iface, @snaplen, @promisc, 1)
+      set_filter_on pcap
+
       @cap_thread = Thread.new do
-        @pcap.each do |packet_data|
-          @raw_packets << packet_data
+        pcap.each do |packet_data|
+          raw_packets << packet_data
           if @parse
             packet = Packet.parse(packet_data)
-            @packets << packet
+            packets << packet
             yield packet if block_given?
           elsif block_given?
             yield packet_data
           end
-          break if @max && @raw_packets.size >= @max
+          break if defined?(@max) && (raw_packets.size >= @max)
         end
       end
-      @cap_thread.join(@timeout)
+      cap_thread.join(@timeout)
     end
 
     # Stop capture. Should be used from another thread, as {#start} blocks.
@@ -82,25 +86,25 @@ module PacketGen
     # has been made to make Capture nor PacketGen thread-safe.
     # @return [void]
     def stop
-      @cap_thread.kill
+      cap_thread.kill
     end
 
     private
 
-    def set_options(options)
-      @max = options[:max] if options[:max]
-      @filter = options[:filter] if options[:filter]
-      @timeout = options[:timeout] if options[:timeout]
-      @promisc = options[:promisc] if options.key? :promisc
-      @snaplen = options[:snaplen] if options[:snaplen]
-      @parse = options[:parse] if options.key? :parse
-      @iface = options[:iface] if options[:iface]
+    def set_options(iface, max, timeout, filter, promisc, parse, snaplen)
+      @max = max if max
+      @filter = filter unless filter.nil?
+      @timeout = timeout unless timeout.nil?
+      @promisc = promisc unless promisc.nil?
+      @snaplen = snaplen unless snaplen.nil?
+      @parse = parse unless parse.nil?
+      @iface = iface unless iface.nil?
     end
 
-    def set_filter
-      return if @filter.nil?
-      return if @filter.empty?
-      @pcap.setfilter @filter
+    def set_filter_on(pcap)
+      return if filter.nil? || filter.empty?
+
+      pcap.setfilter filter
     end
   end
 end

data/lib/packetgen/config.rb

@@ -7,7 +7,6 @@
 
 require 'socket'
 require 'singleton'
-require 'interfacez'
 
 module PacketGen
   # Config class to provide +config+ object to pgconsole

data/lib/packetgen/deprecation.rb

@@ -4,7 +4,7 @@ module PacketGen
   # @author Sylvain Daubert
   # @api private
   module Deprecation
-    def self.deprecated(klass, deprecated_method, new_method=nil, klass_method: false, remove_version: '3.0.0')
+    def self.deprecated(klass, deprecated_method, new_method=nil, klass_method: false, remove_version: '4.0.0')
       separator = klass_method ? '.' : '#'
       base_name = klass.to_s + separator
       complete_deprecated_method_name = base_name + deprecated_method.to_s

data/lib/packetgen/header.rb

@@ -7,9 +7,12 @@
 # frozen_string_literal: true
 
 module PacketGen
-  # Namespace for protocol header classes
+  # Namespace for protocol header classes.
+  #
+  # This namespace handles all buitlin headers, such as {IP} or {TCP}.
+  #
   # == Add a foreign header class
-  # Since v1.1.0, PacketGen permits adding you own header classes.
+  # PacketGen permits adding you own header classes.
   # First, define the new header class. By example:
   #  module MyModule
   #    class MyHeader < PacketGen::Header::Base
@@ -40,7 +43,8 @@ module PacketGen
       # List all available headers.
       # @return [Array<Class>]
       def all
-        return @header_classes if @header_classes
+        return @header_classes if defined?(@header_classes) && @header_classes
+
         @header_classes = @added_header_classes.values
       end
       alias list all
@@ -51,7 +55,7 @@ module PacketGen
       # @return [void]
       # @since 1.1.0
       def add_class(klass)
-        protocol_name = klass.new.protocol_name
+        protocol_name = klass.protocol_name
         @added_header_classes[protocol_name] = klass
         @header_classes = nil
       end
@@ -62,7 +66,7 @@ module PacketGen
       # @return [void]
       # @since 1.1.0
       def remove_class(klass)
-        protocol_name = klass.new.protocol_name
+        protocol_name = klass.protocol_name
         @added_header_classes.delete protocol_name
         @header_classes = nil
       end
@@ -82,7 +86,6 @@ module PacketGen
   end
 end
 
-require_relative 'header/crypto'
 require_relative 'header/base'
 require_relative 'header/eth'
 require_relative 'header/dot11'
@@ -98,8 +101,6 @@ require_relative 'header/gre'
 require_relative 'header/udp'
 require_relative 'header/tcp'
 require_relative 'header/eap'
-require_relative 'header/esp'
-require_relative 'header/ike'
 require_relative 'header/dns'
 require_relative 'header/asn1_base'
 require_relative 'header/snmp'
@@ -114,5 +115,4 @@ require_relative 'header/mld'
 require_relative 'header/mldv2'
 require_relative 'header/ospfv2'
 require_relative 'header/ospfv3'
-require_relative 'header/netbios'
 require_relative 'header/mdns'

data/lib/packetgen/header/asn1_base.rb

@@ -25,7 +25,14 @@ module PacketGen
       # @return [String]
       # @since 2.0.0
       def self.protocol_name
-        self.new.protocol_name
+        return @protocol_name if defined? @protocol_name
+
+        classname = to_s
+        @protocol_name = if classname.start_with?('PacketGen::Header')
+                           classname.sub(/.*Header::/, '')
+                         else
+                           classname.sub(/.*::/, '')
+                         end
       end
 
       # Define some methods from given ASN.1 fields to mimic {Base} attributes
@@ -42,21 +49,14 @@ module PacketGen
       # Return header protocol name
       # @return [String]
       def protocol_name
-        return @protocol_name if @protocol_name
-
-        classname = self.class.to_s
-        @protocol_name = if classname.start_with?('PacketGen::Header')
-                           classname.sub(/.*Header::/, '')
-                         else
-                           classname.sub(/.*::/, '')
-                         end
+        self.class.protocol_name
       end
 
       # return header method name
       # @return [String]
       # @since 2.0.0
       def method_name
-        return @method_name if @method_name
+        return @method_name if defined? @method_name
 
         @method_name = protocol_name.downcase.sub(/::/, '_')
       end

data/lib/packetgen/header/base.rb

@@ -11,7 +11,7 @@ module PacketGen
     #    Subclasses may define magic methods:
     #    * +#calc_checksum+, which computes header checksum,
     #    * +#calc_length+, which computes header length,
-    #    * +#parse?+,
+    #    * {#parse?},
     #    * +#reply!+, which inverts needed fields to forge a response.
     # @author Sylvain Daubert
     class Base < Types::Fields
@@ -78,30 +78,21 @@ module PacketGen
       class Bindings
         include Enumerable
 
-        # op type
-        # @return [:or,:and]
-        attr_accessor :op
         # @return [Array<Binding>]
         attr_accessor :bindings
 
-        # @param [:or, :and, :newstyle] operator
-        def initialize(operator)
-          @op = operator
+        def initialize
           @bindings = []
         end
 
         def new_set
-          @bindings << [] if @op == :newstyle
+          @bindings << []
         end
 
         # @param [Object] arg
-        # @return [OldBindings] self
+        # @return [Bindings] self
         def <<(arg)
-          if op == :newstyle
-            @bindings.last << arg
-          else
-            @bindings << arg
-          end
+          @bindings.last << arg
         end
 
         # each iterator
@@ -117,15 +108,12 @@ module PacketGen
           @bindings.empty?
         end
 
+        # Return binding as a hash.
         # @return [Hash]
         def to_h
           hsh = {}
           each do |b|
-            if b.is_a? Array
-              b.each { |sb| hsh[sb.key] = sb.value }
-            else
-              hsh[b.key] = b.value
-            end
+            b.each { |sb| hsh[sb.key] = sb.value }
           end
           hsh
         end
@@ -134,26 +122,14 @@ module PacketGen
         # @param [Types::Fields] fields
         # @return [Boolean]
         def check?(fields)
-          case @op
-          when :or
-            empty? || @bindings.any? { |binding| binding.check?(fields) }
-          when :and
-            @bindings.all? { |binding| binding.check?(fields) }
-          when :newstyle
-            @bindings.any? { |group| group.all? { |binding| binding.check?(fields) } }
-          end
+          @bindings.any? { |group| group.all? { |binding| binding.check?(fields) } }
         end
 
         # Set +fields+ to bindings value
         # @param [Types::Fields] fields
         # @return [void]
         def set(fields)
-          case @bindings.first
-          when Array
-            @bindings.first.each { |b| b.set fields }
-          else
-            @bindings.each { |b| b.set fields }
-          end
+          @bindings.first.each { |b| b.set fields }
         end
       end
 
@@ -161,6 +137,7 @@ module PacketGen
       # @return [Packet,nil]
       attr_reader :packet
 
+      # @private
       # On inheritage, create +@known_header+ class variable
       # @param [Class] klass
       # @return [void]
@@ -169,79 +146,41 @@ module PacketGen
         klass.class_eval { @known_headers = {} }
       end
 
-      # Bind a upper header to current class
-      #   Header1.bind_header Header2, field1: 43
-      #   Header1.bind_header Header3, field1: 43, field2: 43
-      #   Header1.bind_header Header4, op: :and, field1: 43, field2: 43
-      #   Header1.bind_header Header5, field1: ->(v) { v.nil? ? 128 : v > 127 }
-      #   Header1.bind_header Header6, procs: [->(hdr) { hdr.field1 = 1 }
-      #                                        ->(hdr) { hdr.field1 == 1 && hdr.body[0..1] == "\x00\x00" }]
+      # Bind a upper header to current one.
       # @param [Class] header_klass header class to bind to current class
       # @param [Hash] args current class fields and their value when +header_klass+
-      #   is embedded in current class. Given value may be a lambda, whose alone argument
-      #   is the value extracted from header field (or +nil+ when lambda is used to set
-      #   field while adding a header).
+      #   is embedded in current class.
       #
-      #   If multiple fields are given, a special key +:op+ may be given to set parse
-      #   operation on this binding. By default, +:op+ is +:or+ (at least one binding
-      #   must match to parse it). It also may be set to +:and+ (all bindings must match
-      #   to parse it).
+      #   Given value may be a lambda, whose alone argument is the value extracted
+      #   from header field (or +nil+ when lambda is used to set  field while adding
+      #   a header).
       #
       #   Special key +procs+ may be used to set 2 lambdas, the former to set
       #   fields, the latter to check bindings. This may be used when multiple and
       #   non-trivial checks should be made.
       # @return [void]
-      # @deprecated Use {.bind} instead.
-      def self.bind_header(header_klass, args={})
-        Deprecation.deprecated(self, __method__, 'bind', klass_method: true)
-        op = args.delete(:op) || :or
-        if @known_headers[header_klass].nil? || @known_headers[header_klass].op != op
-          bindings = Bindings.new(op)
-          @known_headers[header_klass] = bindings
-        else
-          bindings = @known_headers[header_klass]
-        end
-        args.each do |key, value|
-          bindings << if key == :procs
-                        ProcBinding.new(value)
-                      else
-                        Binding.new(key, value)
-                      end
-        end
-      end
-
-      # Bind a upper header to current one.
+      # @example Basic examples
       #   # Bind Header2 to Header1 when field1 from Header1 has a value of 42
       #   Header1.bind Header2, field1: 42
       #   # Bind Header3 to Header1 when field1 from Header1 has a value of 43
       #   # and field2 has value 43 or 44
       #   Header1.bind Header3, field1: 43, field2: 43
       #   Header1.bind Header3, field1: 43, field2: 44
+      # @example Defining a binding on a field using a lambda.
       #   # Bind Header4 to Header1 when field1 from Header1 has a value
       #   # greater or equal to 44. When adding a Header2 to a Header1
       #   # with Packet#add, force value to 44.
       #   Header1.bind Header4, field1: ->(v) { v.nil? ? 44 : v >= 44 }
+      # @example Defining a binding using procs key
       #   # Bind Header5 to Header1 when field1 from Header1 has a value of 41
       #   # and first two bytes of header1's body are null.
       #   # When adding a Header2 to a Header1 with Packet#add, force value to 44.
       #   Header1.bind Header5, procs: [->(hdr) { hdr.field1 = 41 }
       #                                 ->(hdr) { hdr.field1 == 41 && hdr.body[0..1] == "\x00\x00" }]
-      # @param [Class] header_klass header class to bind to current class
-      # @param [Hash] args current class fields and their value when +header_klass+
-      #   is embedded in current class.
-      #
-      #   Given value may be a lambda, whose alone argument is the value extracted
-      #   from header field (or +nil+ when lambda is used to set  field while adding
-      #   a header).
-      #
-      #   Special key +procs+ may be used to set 2 lambdas, the former to set
-      #   fields, the latter to check bindings. This may be used when multiple and
-      #   non-trivial checks should be made.
-      # @return [void]
       # @since 2.7.0
       def self.bind(header_klass, args={})
         if @known_headers[header_klass].nil?
-          bindings = Bindings.new(:newstyle)
+          bindings = Bindings.new
           @known_headers[header_klass] = bindings
         else
           bindings = @known_headers[header_klass]
@@ -260,7 +199,14 @@ module PacketGen
       # @return [String]
       # @since 2.0.0
       def self.protocol_name
-        new.protocol_name
+        return @protocol_name if defined? @protocol_name
+
+        classname = to_s
+        @protocol_name = if classname.start_with?('PacketGen::Header')
+                           classname.sub(/.*Header::/, '')
+                         else
+                           classname.sub(/.*::/, '')
+                         end
       end
 
       # Helper method to calculate length of +hdr+ and set its +length+ field.
@@ -272,7 +218,7 @@ module PacketGen
         length = if header_in_size
                    hdr.sz
                  else
-                   hdr.body.sz
+                   hdr[:body].sz
                  end
         hdr.length = length
       end
@@ -293,14 +239,7 @@ module PacketGen
       # Return header protocol name
       # @return [String]
       def protocol_name
-        return @protocol_name if @protocol_name
-
-        classname = self.class.to_s
-        @protocol_name = if classname.start_with?('PacketGen::Header')
-                           classname.sub(/.*Header::/, '')
-                         else
-                           classname.sub(/.*::/, '')
-                         end
+        self.class.protocol_name
       end
 
       # return header method name
@@ -308,7 +247,7 @@ module PacketGen
       # @since 2.0.0
       # @since 2.8.6 permit multiple nesting levels
       def method_name
-        return @method_name if @method_name
+        return @method_name if defined? @method_name
 
         @method_name = protocol_name.downcase.gsub(/::/, '_')
       end
@@ -340,29 +279,30 @@ module PacketGen
       def added_to_packet(packet) end
 
       # @api private
-      # Get +header+ id in packet headers array
+      # Get +header+ id in {Packet#headers} array
       # @param [Header] header
       # @return [Integer]
-      # @raise FormatError +header+ not in a packet
+      # @raise [FormatError] +header+ not in a packet
       def header_id(header)
         raise FormatError, "header of type #{header.class} not in a packet" if packet.nil?
+
         id = packet.headers.index(header)
-        if id.nil?
-          raise FormatError, "header of type #{header.class} not in packet #{packet}"
-        end
+        raise FormatError, "header of type #{header.class} not in packet #{packet}" if id.nil?
+
         id
       end
 
       # @api private
-      # Get IP or IPv6 previous header from +header+
+      # Get {IP} or {IPv6} previous header from +header+
       # @param [Header] header
       # @return [Header]
-      # @raise FormatError no IP or IPv6 header previous +header+ in packet
-      # @raise FormatError +header+ not in a packet
+      # @raise [FormatError] no IP or IPv6 header previous +header+ in packet
+      # @raise [FormatError] +header+ not in a packet
       def ip_header(header)
         hid = header_id(header)
         iph = packet.headers[0...hid].reverse.find { |h| h.is_a?(IP) || h.is_a?(IPv6) }
         raise FormatError, 'no IP or IPv6 header in packet' if iph.nil?
+
         iph
       end
 
@@ -370,12 +310,13 @@ module PacketGen
       # Get link layer header from given header
       # @param [Header] header
       # @return [Header]
-      # @raise FormatError no link layer header in packet
-      # @raise FormatError +header+ not in a packet
+      # @raise [FormatError] no link layer header in packet
+      # @raise [FormatError] +header+ not in a packet
       def ll_header(header)
         hid = header_id(header)
         llh = packet.headers[0...hid].reverse.find { |h| h.is_a?(Eth) || h.is_a?(Dot11) }
         raise FormatError, 'no link layer header in packet' if llh.nil?
+
         llh
       end
     end