packetgen 4.0.0 → 4.1.0

data/lib/packetgen/pcapng/file.rb

@@ -8,9 +8,24 @@
 
 module PacketGen
   module PcapNG
-    # PcapNG::File is a complete Pcap-NG file handler.
+    # PcapNG::File is a complete Pcap-NG file handler. It provides methods to:
+    # * read and write PcapNG files,
+    # * process packets from such files.
+    #
+    # @example Writing a file
+    #   pkt1 = PacketGen.gen('IP', id: 1).add('TCP')
+    #   pkt2 = PacketGen.gen('IP', id: 2).add('UDP')
+    #   file = PacketGen::PcapNG::File.new
+    #   file.read_array([pkt1, pkt2])
+    #   file.write('/tmp/file.pcapng')
+    #
+    # @example Reading a file
+    #   file = PacketGen::PcapNG::File.new
+    #   pkts = file.read_packets('/tmp/file.pcapng')
+    #
     # @author Sylvain Daubert
-    class File # rubocop:disable Metrics/ClassLength
+    # @author LemonTree55
+    class File
       # Known link types
       KNOWN_LINK_TYPES = {
         LINKTYPE_ETHERNET => 'Eth',
@@ -29,19 +44,19 @@ module PacketGen
       end.freeze
 
       # Get file sections
-      # @return [Array]
+      # @return [Array<SHB>]
       attr_accessor :sections
 
       def initialize
         @sections = []
       end
 
-      # Read a string to populate the object. Note that this appends new blocks to
+      # Read a binary string to populate the object. Note that this appends new blocks to
       # the Pcapng::File object.
       # @param [String] str
       # @return [self]
       def read(str)
-        PacketGen.force_binary(str)
+        str = str.b unless str.encoding == Encoding::BINARY
         io = StringIO.new(str)
         parse_section(io)
         self
@@ -59,11 +74,19 @@ module PacketGen
 
       # Read a given file and analyze it.
       # If given a block, it will yield PcapNG::EPB or PcapNG::SPB objects.
-      # This is the only way to get packet timestamps.
+      # This is the only way to get packet timestamps (via {EPB#timestamp}).
       # @param [String] fname pcapng file name
       # @yieldparam [EPB,SPB] block
       # @return [Integer] return number of yielded blocks (only if a block is given)
       # @raise [ArgumentError] cannot read +fname+
+      # @example Parse packets and get their timestamp
+      #   hsh = {}
+      #   file = PacketGen::PcapNG::File.new
+      #   file.readfile('/tmp/file.pcapng') do |xpb|
+      #     ts = xpb.is_a?(PacketGen::PcapNG::EPB) ? xpb.timestamp : nil
+      #     pkt = PacketGen.parse(xpb.data)
+      #     hsh[pkt] = ts
+      #   end
       def readfile(fname, &blk)
         raise ArgumentError, "cannot read file #{fname}" unless ::File.readable?(fname)
 
@@ -168,13 +191,15 @@ module PacketGen
       end
 
       # Writes the {File} to a file.
-      # @param [Hash] options
-      # @option options [Boolean] :append (default: +false+) if set to +true+,
+      # @param [String] filename file name to write
+      # @param [Boolean] append if set to +true+,
       #   the packets are appended to the file, rather than overwriting it
-      # @return [Array] array of 2 elements: filename and size written
-      # @todo for 4.0, replace +options+ by +append+ kwarg
-      def to_file(filename, options={})
-        mode = options[:append] && ::File.exist?(filename) ? 'ab' : 'wb'
+      # @return [Array(String, Integer)] array of 2 elements: filename and size written
+      # @since 4.1.0 Options hash with single +:append+ option is replaced by +append+ keyword argument.
+      # @see #append
+      # @see #write
+      def to_file(filename, append: false)
+        mode = append && ::File.exist?(filename) ? 'ab' : 'wb'
         ::File.open(filename, mode) { |f| f.write(self.to_s) }
         [filename, self.to_s.size]
       end
@@ -182,14 +207,16 @@ module PacketGen
 
       # Shorthand method for writing to a file.
       # @param [#to_s] filename
-      # @return [Array] see return value from {#to_file}
+      # @return [Array(String, Integer)]
+      # @see #to_file
       def write(filename='out.pcapng')
         self.to_file(filename.to_s, append: false)
       end
 
       # Shorthand method for appending to a file.
       # @param [#to_s] filename
-      # @return [Array] see return value from {#to_file}
+      # @return [Array(String, Integer)]
+      # @see #to_file
       def append(filename='out.pcapng')
         self.to_file(filename.to_s, append: true)
       end

data/lib/packetgen/pcapng/idb.rb

@@ -8,7 +8,8 @@
 
 module PacketGen
   module PcapNG
-    # {IDB} represents a Interface Description Block (IDB) of a pcapng file.
+    # {IDB} represents an Interface Description Block (IDB) of a pcapng file. It is associated to a network interfaces.
+    # It contains packet data as {EPB} and/or {SPB}.
     #
     # == IDB Definition
     #   Int32   :type           Default: 0x00000001

data/lib/packetgen/pcapng/shb.rb

@@ -8,7 +8,8 @@
 
 module PacketGen
   module PcapNG
-    # {SHB} represents a Section Header Block (SHB) of a pcapng file.
+    # {SHB} represents a Section Header Block (SHB) of a pcapng file. A SHB contains {IDB}, which contain
+    # {EPB} and/or {SPB}.
     #
     # == SHB Definition
     #   Int32   :type           Default: 0x0A0D0D0A

data/lib/packetgen/pcapng/spb.rb

@@ -8,7 +8,7 @@
 
 module PacketGen
   module PcapNG
-    # {SPB} represents a Section Simple Packet Block (SPB) of a pcapng file.
+    # {SPB} represents a Simple Packet Block (SPB) of a pcapng file.
     #
     # == Pcapng::SPB Definition
     #   Int32   :type           Default: 0x00000003

data/lib/packetgen/pcapng.rb

@@ -11,6 +11,8 @@ require 'stringio'
 module PacketGen
   # Module to handle PCAP-NG file format.
   # See http://xml2rfc.tools.ietf.org/cgi-bin/xml2rfc.cgi?url=https://raw.githubusercontent.com/pcapng/pcapng/master/draft-tuexen-opsawg-pcapng.xml&modeAsFormat=html/ascii&type=ascii
+  #
+  # See {PcapNG::File} to handle Pcap-NG files.
   # @author Sylvain Daubert
   module PcapNG
     # Section Header Block type number

data/lib/packetgen/proto.rb

@@ -30,6 +30,8 @@ module PacketGen
     # Get protocol number from its name
     # @param [String] name
     # @return [Integer,nil] return nil for unknown protocol names
+    # @example
+    #   PacketGen::Proto.getprotobyname('tcp') #=> 6
     def self.getprotobyname(name)
       @cache[name]
     end
@@ -37,6 +39,8 @@ module PacketGen
     # Get protocol name from its number
     # @param [Integer] num
     # @return [String,nil] return nil for unknown protocol numbers
+    # @example
+    #   PacketGen::Proto.getprotobynumber(6) #=> 'tcp'
     def self.getprotobynumber(num)
       @cache.key(num)
     end

data/lib/packetgen/unknown_packet.rb

@@ -20,7 +20,7 @@ module PacketGen
 
     def initialize
       @headers = [].freeze
-      @binary_str = PacketGen.force_binary('')
+      @binary_str = ::String.new # Return empty string with encoding ASCII-8BIT, so BINARY
     end
 
     # Unknown packet, so unknown protocol.
@@ -40,7 +40,7 @@ module PacketGen
     # @param [String] str
     # @return [void]
     def body=(str)
-      @binary_str = PacketGen.force_binary(str)
+      @binary_str = str.b
     end
 
     # Write packet to a PCapNG file on disk.
@@ -56,7 +56,7 @@ module PacketGen
     # @param [String] binary_str
     # @return [self]
     def parse(binary_str, _first_header: nil)
-      @binary_str = PacketGen.force_binary(binary_str)
+      @binary_str = binary_str.b
       self
     end
 

data/lib/packetgen/utils.rb

@@ -168,7 +168,8 @@ module PacketGen
     def self.mitm(target1, target2, options={}, &block)
       options = { iface: PacketGen.default_iface }.merge(options)
 
-      spoofer = Utils::ARPSpoofer.new(options)
+      spoofer_options = options.slice(:timeout, :interval, :iface)
+      spoofer = Utils::ARPSpoofer.new(**spoofer_options.compact)
       spoofer.add target1, target2, options
       spoofer.add target2, target1, options
 

data/lib/packetgen/version.rb

@@ -11,5 +11,5 @@
 # @author Sylvain Daubert
 module PacketGen
   # PacketGen version
-  VERSION = '4.0.0'
+  VERSION = '4.1.0'
 end

data/lib/packetgen.rb

@@ -13,6 +13,7 @@ require 'interfacez'
 
 # PacketGen is a network packet generator and analyzor.
 # @author Sylvain Daubert
+# @author LemonTree
 module PacketGen
   # Base exception class for PacketGen exceptions
   class Error < StandardError; end
@@ -33,12 +34,15 @@ module PacketGen
     # @return [Headerable]
     attr_reader :hdr
 
+    # @param [Headerable] prev_hdr
+    # @param [Headerable] hdr
     def initialize(prev_hdr, hdr)
       super()
       @prev_hdr = prev_hdr
       @hdr = hdr
     end
 
+    # @return [String]
     def message
       "#{prev_hdr.class} knowns no layer association with #{hdr.protocol_name}. " \
         "Try #{prev_hdr.class}.bind_layer(#{hdr.class}, " \
@@ -92,8 +96,10 @@ module PacketGen
   # Force binary encoding for +str+
   # @param [String] str
   # @return [String] binary encoded string
+  # @deprecated Use +String#b+ instead.
   def self.force_binary(str)
-    str.dup.force_encoding(Encoding::BINARY)
+    Deprecation.deprecated(self, :force_binary, 'String#b')
+    str.b
   end
 
   # Get default network interface (ie. first non-loopback declared interface)
@@ -120,7 +126,7 @@ module PacketGen
   # Shortcut to get a header class
   # @example builtin class
   #   # same as PacketGen::Header::Dot11:Data.new(id: 0xfedc)
-  #   dot11 = PacketGen.header('Dot11::Data', id: 0xfedc)  #=> PacketGen::Header::Dot11:Data
+  #   dot11 = PacketGen.header('Dot11::Data', id: 0xfedc)
   # @example plugin class
   #   require 'packet-plugin-smb'
   #   # same as PacketGen::Plugin::SMB::CloseRequest.new(fid: 0x1234)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: packetgen
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - LemonTree55
 bindir: bin
 cert_chain: []
-date: 2024-12-28 00:00:00.000000000 Z
+date: 2025-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bin_struct
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: digest-crc
   requirement: !ruby/object:Gem::Requirement