packetgen 3.3.3 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8316e4a27cffbad65cbfabe1eb42746afda43b137eeca97352201f72b1a785cf
-  data.tar.gz: 621a076c2b6159d9a60e0842d318298cbcb5c983b358983bc9e21b2e1ec50b96
+  metadata.gz: ed11e05d37fb82187dbf1dc0a7dffd1e6c1931ebda0dea904da77f2731a523f8
+  data.tar.gz: e36705786a664ac257d1939a9c67d267a15c52f51e76b02069c923095c0d8852
 SHA512:
-  metadata.gz: 447552efc82789c71b1f2de48059a387318471366866794b70e9318f04d53ca78e16b63ec2f8984f162b02bca2c3cbe6c0f96ccd083f86d99a5dfaddbe1daa2d
-  data.tar.gz: 01426b4136c2084607621087fd856677c27842de93b6b266cb15056a59ba6e2f126b87a268c5369a012819a0d37e5c79866b57c8821fa80f4b7dfcbcde10f785
+  metadata.gz: 151754f39d113f9dbeb65cda8f62f4e378440aa567c3e528b2d8e93920e70069a55bd26e737c03818a808463a9b3406805dcb8ed92e8b5582fbbfaae7f5d8fd4
+  data.tar.gz: 4f61a79f28f1fe8e5f4cac45b9b8fdc06eeca4ae4a07a567334535b3e8ac7ea5cb85cb6644215656e6c0e7e2d1ba0a58bae1fe66131805af7093742dc5098bdd

data/README.md

@@ -1,20 +1,27 @@
 
 [![Gem Version](https://badge.fury.io/rb/packetgen.svg)](https://badge.fury.io/rb/packetgen)
-[![Action status](https://github.com/lemontree55/packetgen/workflows/ci/badge.svg?branch=master)](https://github.com/lemontree55/packetgen/actions?query=workflow%3Aci)
+[![Action status](https://github.com/lemontree55/packetgen/actions/workflows/ci.yml/badge.svg)](https://github.com/lemontree55/packetgen/actions/workflows/ci.yml)
+
 # PacketGen
 
 PacketGen provides simple ways to generate, send and capture network packets.
 
 ## Installation
+
 PacketGen depends on PcapRub, which needs pcap development files to install. On Debian, you have to do:
 
-    $ sudo apt install libpcap-dev
+```bash
+sudo apt install libpcap-dev
+```
 
 Installation using RubyGems is then easy:
 
-    $ gem install packetgen
+```bash
+gem install packetgen
+```
 
 Or add it to a Gemfile:
+
 ```ruby
 gem 'packetgen'
 ```
@@ -22,6 +29,7 @@ gem 'packetgen'
 ## Usage
 
 ### Easily create packets
+
 ```ruby
 PacketGen.gen('IP')             # generate a IP packet object
 PacketGen.gen('TCP')            # generate a TCP over IP packet object
@@ -37,6 +45,7 @@ PacketGen.gen('IP').to_s
 ```
 
 ### Send packets on wire
+
 ```ruby
 # send Ethernet packet
 PacketGen.gen('Eth', src: '00:00:00:00:00:01', dst: '00:00:00:00:00:02').to_w
@@ -52,11 +61,13 @@ PacketGen.gen('RadioTap').
 ```
 
 ### Parse packets from binary data
+
 ```ruby
 packet = PacketGen.parse(binary_data)
 ```
 
 ### Capture packets from wire
+
 ```ruby
 # Capture packets from first network interface, action from a block
 PacketGen.capture do |packet|
@@ -71,6 +82,7 @@ packets = PacketGen.capture(iface: 'eth0', filter: 'ip src 1.1.1.2', max: 1)
 ```
 
 ### Easily manipulate packets
+
 ```ruby
 # access header fields
 pkt = PacketGen.gen('IP').add('TCP')
@@ -96,6 +108,7 @@ pkt2.decapsulate(pkt2.ip)              # pkt2 is now inner IP/TCP packet
 ```
 
 ### Read/write PcapNG files
+
 ```ruby
 # read a PcapNG file, containing multiple packets
 packets = PacketGen.read('file.pcapng')
@@ -107,14 +120,16 @@ PacketGen.write('more_packets.pcapng', packets)
 ```
 
 ### Add custom header/protocol
-Since v1.1.0, PacketGen permits adding your own header classes.
+
+PacketGen permits adding your own header classes.
+
 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_attr :field1, BinStruct::Int32
+   define_attr :field2, BinStruct::Int32
  end
 end
 ```
@@ -135,24 +150,27 @@ PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
 And use it:
 
 ```ruby
-pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
-pkt.myheader.field2.read 0x01
+pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678, field2: 0x87654321)
+pkt.to_w # Send it on wire
 ```
 
 ## Interactive console
+
 PacketGen provides an interactive console: `pgconsole`.
 
 In this console, context includes PacketGen module to give direct access to PacketGen
 classes. A special `config` object gives local network configuration:
 
-    $ pgconsole
-    pg(main)> config
-    => #<PacketGen::Config:0x00559f27d2afe8
-     @hwaddr="75:74:73:72:71:70",
-     @iface="eth0",
-     @ipaddr="192.168.0.2">
-    pg(main)> packets = capture(max: 5)
-    pg(main)> exit
+```text
+$ pgconsole
+pg(main)> config
+=> #<PacketGen::Config:0x00559f27d2afe8
+ @hwaddr="75:74:73:72:71:70",
+ @iface="eth0",
+ @ipaddr="192.168.0.2">
+pg(main)> packets = capture(max: 5)
+pg(main)> exit
+```
 
 If `pry` gem is installed, it is used as backend for `pgconsole`, else IRB is used.
 
@@ -167,20 +185,18 @@ Available plugins (available as gem) are:
 
 ## See also
 
-Wiki: https://github.com/lemontree55/packetgen/wiki
+Wiki: <https://github.com/lemontree55/packetgen/wiki>
 
-API documentation: http://www.rubydoc.info/gems/packetgen
+API documentation: <http://www.rubydoc.info/gems/packetgen>
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/lemontree55/packetgen.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/lemontree55/packetgen>.
 
 ## License
 
 MIT License (see [LICENSE](https://github.com/lemontree55/packetgen/blob/master/LICENSE))
 
 ### Other sources
-All original code maintains its copyright from its original authors and licensing.
 
-This is mainly for PcapNG (originally copied from [PacketFu](https://github.com/packetfu/packetfu),
-but i am the original author.
+All original code maintains its copyright from its original authors and licensing.

data/lib/packetgen/capture.rb

@@ -61,7 +61,7 @@ module PacketGen
       @packets     = []
       @raw_packets = []
       @timestamps = []
-      set_options iface, max, timeout, filter, promisc, parse, snaplen, monitor
+      set_options(iface, max, timeout, filter, promisc, parse, snaplen, monitor)
     end
 
     # Start capture
@@ -75,7 +75,7 @@ module PacketGen
     # @author Sylvain Daubert
     # @author optix2000 - add monitor argument
     def start(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil, &block)
-      set_options iface, max, timeout, filter, promisc, parse, snaplen, monitor
+      set_options(iface, max, timeout, filter, promisc, parse, snaplen, monitor)
 
       @cap_thread = Thread.new do
         PCAPRUBWrapper.capture(**capture_args) do |packet|

data/lib/packetgen/config.rb

@@ -12,7 +12,6 @@ require 'singleton'
 module PacketGen
   # Config class to provide +config+ object to pgconsole
   # @author Sylvain Daubert
-  # @author Kent 'picat' Gruber
   # @since 1.4.1
   # @since 2.1.3 Config is singleton
   class Config

data/lib/packetgen/deprecation.rb

@@ -8,7 +8,7 @@ module PacketGen
   module Deprecation
     # Default remove version for deprecated classes/methods
     # @since 3.1.0
-    REMOVE_VERSION = '4.0.0'
+    REMOVE_VERSION = '5.0.0'
 
     # @private
     # @param [String] remove_version
@@ -29,13 +29,19 @@ module PacketGen
     def self.deprecated(klass, deprecated_method, new_method=nil, klass_method: false, remove_version: REMOVE_VERSION)
       base_name = "#{klass}#{klass_method ? '.' : '#'}"
       complete_deprecated_method_name = "#{base_name}#{deprecated_method}"
-      complete_new_method_name = "#{base_name}#{new_method}" unless new_method.nil?
+      unless new_method.nil?
+        complete_new_method_name = if %w[# .].any? { |punct| new_method.include?(punct) }
+                                     new_method
+                                   else
+                                     "#{base_name}#{new_method}"
+                                   end
+      end
 
       file, line = caller(2..2).first.split(':')[0, 2]
-      message = +"#{file}:#{line}: #{complete_deprecated_method_name} is deprecated"
+      message = "#{file}:#{line}: #{complete_deprecated_method_name} is deprecated"
       message << " in favor of #{complete_new_method_name}" unless new_method.nil?
       message << '. ' << self.removed(remove_version)
-      warn message
+      warn(message)
     end
 
     # Warn when using a deprecated method
@@ -46,10 +52,10 @@ module PacketGen
     # @since 3.1.0
     def self.deprecated_class(klass, new_klass=nil, remove_version: REMOVE_VERSION)
       file, line = caller(2..2).first.split(':')[0, 2]
-      message = +"#{file}:#{line}: #{klass} is deprecated"
+      message = "#{file}:#{line}: #{klass} is deprecated"
       message << " in favor of #{new_klass}" unless new_klass.nil?
       message << '. ' << self.removed(remove_version)
-      warn message
+      warn(message)
     end
 
     # Warn when using a deprecated method's option
@@ -64,9 +70,9 @@ module PacketGen
     def self.deprecated_option(klass, method, option, klass_method: false, remove_version: REMOVE_VERSION)
       base_name = "#{klass}#{klass_method ? '.' : '#'}"
       method_name = "#{base_name}#{method}"
-      message = +"option #{option} is deprecated for method #{method_name}. "
+      message = "option #{option} is deprecated for method #{method_name}. "
       message << self.removed(remove_version)
-      warn message
+      warn(message)
     end
   end
 end

data/lib/packetgen/header/arp.rb

@@ -9,9 +9,9 @@
 module PacketGen
   module Header
     # An ARP header consists of:
-    # * a hardware type ({#hrd} or {#htype}) field ({Types::Int16}),
+    # * a hardware type ({#hrd} or {#htype}) field (+BinStruct::Int16+),
     # * a protocol type ({#pro} or {#ptype}) field (+Int16+),
-    # * a hardware address length ({#hln} or {#hlen}) field ({Types::Int8}),
+    # * a hardware address length ({#hln} or {#hlen}) field (+BinStruct::Int8+),
     # * a protocol address length ({#pln} or {#plen}) field (+Int8+),
     # * a {#opcode} (or {#op}) field (+Int16+),
     # * a source hardware address ({#sha} or {#src_mac}) field ({Eth::MacAddr}),
@@ -20,55 +20,55 @@ module PacketGen
     # * a target protocol address ({#tpa} or {#dst_ip}) field (+IP::Addr+),
     # * and a {#body}.
     #
-    # == Create a ARP header
+    # @example Create a ARP header
     #  # standalone
     #  arp = PacketGen::Header::ARP.new
     #  # in a packet
     #  pkt = PacketGen.gen('Eth').add('ARP')
     #  # access to ARP header
-    #  pkt.arp   # => PacketGen::Header::ARP
+    #  pkt.arp.protocol_name   # => "ARP"
     #
     # @author Sylvain Daubert
     class ARP < Base
       # @!attribute hrd
       #  16-bit hardware protocol type
       #  # @return [Integer]
-      define_field :hrd, Types::Int16, default: 1
+      define_attr :hrd, BinStruct::Int16, default: 1
       # @!attribute pro
       #  16-bit internet protocol type
       #  # @return [Integer]
-      define_field :pro, Types::Int16, default: 0x800
+      define_attr :pro, BinStruct::Int16, default: 0x800
       # @!attribute hln
       #  8-bit hardware address length
       #  # @return [Integer]
-      define_field :hln, Types::Int8, default: 6
+      define_attr :hln, BinStruct::Int8, default: 6
       # @!attribute pln
       #  8-bit internet address length
       #  # @return [Integer]
-      define_field :pln, Types::Int8, default: 4
+      define_attr :pln, BinStruct::Int8, default: 4
       # @!attribute op
       #  16-bit operation code
       #  # @return [Integer]
-      define_field :op, Types::Int16Enum, enum: { 'request' => 1, 'reply' => 2 }
+      define_attr :op, BinStruct::Int16Enum, enum: { 'request' => 1, 'reply' => 2 }
       # @!attribute sha
       #  source hardware address
       #  @return [Eth::MacAddr]
-      define_field :sha, Eth::MacAddr
+      define_attr :sha, Eth::MacAddr
       # @!attribute spa
       #  source protocol address
       #  @return [IP::Addr]
-      define_field :spa, IP::Addr
+      define_attr :spa, IP::Addr
       # @!attribute tha
       #  target hardware address
       #  @return [Eth::MacAddr]
-      define_field :tha, Eth::MacAddr
+      define_attr :tha, Eth::MacAddr
       # @!attribute tpa
       #  target protocol address
       #  @return [IP::Addr]
-      define_field :tpa, IP::Addr
+      define_attr :tpa, IP::Addr
       # @!attribute body
-      #  @return [Types::String,Header::Base]
-      define_field :body, Types::String
+      #  @return [BinStruct::String,Header::Base]
+      define_attr :body, BinStruct::String
 
       # @param [Hash] options
       # @option options [Integer] :hrd network protocol type (default: 1)
@@ -122,8 +122,7 @@ module PacketGen
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-      def handle_options(options)
+            def handle_options(options)
         options[:hrd] ||= options[:htype]
         options[:pro] ||= options[:ptype]
         options[:hln] ||= options[:hlen]
@@ -134,7 +133,7 @@ module PacketGen
         options[:tha] ||= options[:dst_mac]
         options[:tpa] ||= options[:dst_ip]
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # rubocop:enable Metrics
 
       def invert_addresses
         self.spa, self.tpa = self.tpa, self.spa

data/lib/packetgen/header/asn1_base.rb

@@ -21,7 +21,7 @@ module PacketGen
       include Headerable
 
       class << self
-        # Define some methods from given ASN.1 fields to mimic {Base} attributes
+        # Define some methods from given ASN.1 attributes to mimic {Base} attributes
         # @param [Array<Symbol>] attributes
         # @return [void]
         def define_attributes(*attributes)
@@ -32,6 +32,7 @@ module PacketGen
           end
         end
 
+        # @return [Hash]
         def known_headers
           @known_headers ||= {}.freeze
         end

data/lib/packetgen/header/base.rb

@@ -13,28 +13,30 @@ module PacketGen
     #    * +#calc_checksum+, which computes header checksum,
     #    * +#calc_length+, which computes header length,
     #    * {#parse?},
-    #    * +#reply!+, which inverts needed fields to forge a response.
+    #    * +#reply!+, which inverts needed attributes to forge a response.
+    # {Base} class defines {.bind} method, to bind headers to outer ones.
     # @author Sylvain Daubert
-    class Base < Types::Fields
+    # @author LemonTree55
+    class Base < BinStruct::Struct
       include Headerable
 
       # @api private
       # Simple class to handle a header association
-      class Binding < Struct.new(:key, :value)
+      class Binding < ::Struct.new(:key, :value)
         # Check +fields+ responds to binding
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [Boolean]
         def check?(fields)
           case self[:value]
           when Proc
-            self[:value].call fields.send(self[:key])
+            self[:value].call(fields.send(self[:key]))
           else
             fields.send(self[:key]) == self[:value]
           end
         end
 
         # Set +fields+ field to binding value
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [void]
         def set(fields)
           case self[:value]
@@ -54,7 +56,7 @@ module PacketGen
       # @api private
       # Class to handle a header association from procs
       class ProcBinding
-        # @param [Array<Proc>] procs first proc is used to set fields, second proc is
+        # @param [Array(Proc,Proc)] procs first proc is used to set fields, second proc is
         #  used to check binding
         def initialize(procs)
           @set = procs.shift
@@ -62,14 +64,14 @@ module PacketGen
         end
 
         # Check +fields+ responds to binding
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [Boolean]
         def check?(fields)
           @check.call(fields)
         end
 
         # Set +fields+ field to binding value
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [void]
         def set(fields)
           @set.call(fields)
@@ -77,11 +79,11 @@ module PacketGen
       end
 
       # @api private
-      # Class to handle header associations
+      # Class to handle a set of header associations ({Binding} or/and {ProcBinding})
       class Bindings
         include Enumerable
 
-        # @return [Array<Binding>]
+        # @return [Array<Binding,ProcBinding>]
         attr_accessor :bindings
 
         def initialize
@@ -92,7 +94,7 @@ module PacketGen
           @bindings << []
         end
 
-        # @param [Object] arg
+        # @param [Binding,ProcBinding] arg
         # @return [Bindings] self
         def <<(arg)
           @bindings.last << arg
@@ -100,6 +102,7 @@ module PacketGen
 
         # each iterator
         # @return [void]
+        # @yieldparam [Binding,ProcBinding] binding
         def each(&block)
           @bindings.each(&block)
         end
@@ -109,7 +112,7 @@ module PacketGen
           @bindings.empty?
         end
 
-        # Return binding as a hash.
+        # Return bindings as a hash.
         # @return [Hash]
         def to_h
           hsh = {}
@@ -120,22 +123,22 @@ module PacketGen
         end
 
         # Check +fields+ responds to set of bindings
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [Boolean]
         def check?(fields)
           @bindings.any? { |group| group.all? { |binding| binding.check?(fields) } }
         end
 
         # Set +fields+ to bindings value
-        # @param [Types::Fields] fields
+        # @param [BinStruct::Struct] fields
         # @return [void]
         def set(fields)
-          @bindings.first.each { |b| b.set fields }
+          @bindings.first.each { |b| b.set(fields) }
         end
       end
 
       # @private
-      # On inheritage, create +@known_header+ class variable
+      # On inheritance, create +@known_header+ class variable
       # @param [Class] klass
       # @return [void]
       def self.inherited(klass)
@@ -146,12 +149,12 @@ module PacketGen
       class << self
         # @api private
         # Get known headers
-        # @return [Hash] keys: header classes, values: hashes
+        # @return [Hash{Headerable => Bindings}]
         attr_reader :known_headers
 
         # 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+
+        # @param [Hash] args current class attributes and their value when +header_klass+
         #   is embedded in current class.
         #
         #   Given value may be a lambda, whose alone argument is the value extracted
@@ -163,30 +166,29 @@ module PacketGen
         #   non-trivial checks should be made.
         # @return [void]
         # @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
+        #   # Bind TCP to IP when protocol attribute from IP has a value of 66
+        #   PacketGen::Header::IP.bind PacketGen::Header::TCP, protocol: 66
+        #   # Bind UDP to IP when protocol from IP has a value of 177
+        #   # and tos has value 43 or 44
+        #   PacketGen::Header::IP .bind PacketGen::Header::UDP, protocol: 177, tos: 43
+        #   PacketGen::Header::IP .bind PacketGen::Header::UDP, protocol: 177, tos: 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
+        #   # Bind DHCP to Eth when ethertype from Eth has a value
+        #   # greater or equal to 44. When adding a DHCP to a Eth
         #   # with Packet#add, force value to 44.
-        #   Header1.bind Header4, field1: ->(v) { v.nil? ? 44 : v >= 44 }
+        #   PacketGen::Header::Eth.bind PacketGen::Header::DHCP, ethertype: ->(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" }]
+        #   # Bind IPv6 to IP when protocol from IP has a value of 255
+        #   # and first two bytes of IP's body are 0x6000.
+        #   # When adding a IPv6 to a IP with Packet#add, force value to 255.
+        #   PacketGen::Header::IP.bind PacketGen::Header::IPv6, procs: [->(hdr) { hdr.protocol = 255 },
+        #                                                               ->(hdr) { hdr.protocol == 255 && hdr.body[0..1] == "\x60\x00" }]
         # @since 2.7.0
         def bind(header_klass, args={})
-          if @known_headers[header_klass].nil?
+          bindings = @known_headers[header_klass]
+          if bindings.nil?
             bindings = Bindings.new
             @known_headers[header_klass] = bindings
-          else
-            bindings = @known_headers[header_klass]
           end
           bindings.new_set
           args.each do |key, value|
@@ -213,7 +215,7 @@ module PacketGen
         end
       end
 
-      # @see Types::Fields#initialize
+      # @see BinStruct::Struct#initialize
       def initialize(options={})
         @packet = options.delete(:packet) if options.key?(:packet)
         super
@@ -222,7 +224,7 @@ module PacketGen
       # @api private
       # Get +header+ id in {Packet#headers} array
       # @param [Header] header
-      # @return [Integer]
+      # @return [Integer] header id
       # @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?
@@ -242,13 +244,13 @@ module PacketGen
       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?
+        raise FormatError, 'no IP nor IPv6 header in packet' if iph.nil?
 
         iph
       end
 
       # @api private
-      # Get link layer header from given header
+      # Get link layer ({Eth} or {Dot11}) header from given header
       # @param [Header] header
       # @return [Header]
       # @raise [FormatError] no link layer header in packet