redhound 1.0.0 → 2.0.0.rc1

data/lib/redhound/cli/options.rb

@@ -0,0 +1,133 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Redhound
+  # @api private
+  module CLI
+    # @api private
+    class Options
+      attr_reader :values, :parser
+      # @rbs (Array[String] argv) -> void
+      def initialize(argv)
+        @values = { interface: nil, read: nil, write: nil, count: nil, snaplen: 262144, promiscuous: true,
+                    buffer_size: nil, direction: :inout, backend: :auto, filter: nil, format: nil,
+                    packet_buffered: false, output: :summary, output_explicit: false, fields: Array.new, verbosity: 0,
+                    link_layer: false, quick: false, timestamp: :clock, precision: :micro, resolve_names: false,
+                    stats: Array.new, follow: nil, decode_as: Array.new, plugins: Array.new, dump: 0, debug: false, no_yjit: false }
+        args = normalize(argv.dup)
+        @parser = build_parser
+        @parser.order!(args)
+        filter = args.join(' ')
+        if @values[:filter_file]
+          raise ConfigurationError, 'cannot combine filter file and expression' unless filter.empty?
+          filter = ::File.read(@values[:filter_file])
+        end
+        @values[:filter] = filter unless filter.strip.empty?
+        validate
+      rescue OptionParser::ParseError, ArgumentError => e
+        raise ConfigurationError, e.message
+      end
+
+      # @rbs (Array[String] args) -> Array[String]
+      def normalize(args)
+        fields = args.each_cons(2).any? { |flag, value| %w[-T --output-format].include?(flag) && value == 'fields' } || args.include?('--output-format=fields')
+        result = [] #: Array[String]
+        while (arg = args.shift)
+          if /\A-v{1,3}\z/.match?(arg)
+            @values[:verbosity] += arg.length - 1
+          elsif /\A-t{1,5}\z/.match?(arg)
+            @values[:timestamp] = %i[none epoch delta date elapsed][arg.length - 2]
+          elsif %w[-x -xx -X -XX].include?(arg)
+            @values[:hex] = { ascii: arg.include?('X'), link_layer: arg.length == 3 }
+          elsif arg == '-e'
+            if fields
+              field = args.shift
+              raise ConfigurationError, '-e needs a field with -T fields' if !field || field.start_with?('-')
+              @values[:fields] << field
+            else
+              @values[:link_layer] = true
+            end
+          else
+            result << arg
+          end
+        end
+        result
+      end
+
+      # @rbs () -> OptionParser
+      def build_parser
+        OptionParser.new do |o|
+          o.banner = 'Usage: redhound [options] [filter expression]'
+          o.on('-i', '--interface IF', 'interface name, index or any') { |v| @values[:interface] = v }
+          o.on('-D', '--list-interfaces', 'list interfaces and exit') { @values[:list_interfaces] = true }
+          o.on('-r', '--read FILE', 'read pcap or pcapng (- for stdin)') { |v| @values[:read] = v }
+          o.on('-c', '--count N', Integer, 'stop after N packets') { |v| @values[:count] = v }
+          o.on('-s', '--snaplen N', Integer, 'capture length (default 262144)') { |v| @values[:snaplen] = v.zero? ? 262144 : v }
+          o.on('-p', '--no-promiscuous', 'disable promiscuous capture') { @values[:promiscuous] = false }
+          o.on('-B', '--buffer-size KiB', Integer, 'kernel buffer size') { |v| @values[:buffer_size] = v * 1024 }
+          o.on('-Q', '--direction DIR', %w[in out inout], 'capture direction') { |v| @values[:direction] = v.to_sym }
+          o.on('-F', '--filter-file FILE', 'read a capture filter') { |v| @values[:filter_file] = v }
+          o.on('--capture-backend BACKEND', %w[auto ring socket bpf], 'capture backend') { |v| @values[:backend] = v.to_sym }
+          o.on('-w', '--write FILE', 'write capture (- for stdout)') { |v| @values[:write] = v }
+          o.on('--format FORMAT', %w[pcap pcapng], 'capture file format') { |v| @values[:format] = v.to_sym }
+          o.on('-C MB', Float, 'rotate after MB (decimal)') { |v| @values[:max_bytes] = (v * 1_000_000).to_i }
+          o.on('-G SECONDS', Float, 'rotate at this interval') { |v| @values[:interval] = v }
+          o.on('-W N', Integer, 'maximum rotation file count') { |v| @values[:file_count] = v }
+          o.on('--post-rotate-command CMD', 'command to run after closing each file') { |v| @values[:post_rotate_command] = v }
+          o.on('-U', '--packet-buffered', 'flush each packet') { @values[:packet_buffered] = true }
+          o.on('-T', '--output-format FORMAT', %w[summary tree json ndjson fields], 'packet output format') do |v|
+            @values[:output], @values[:output_explicit] = v.to_sym, true
+          end
+          o.on('-V', 'show packet details') { @values[:output], @values[:output_explicit] = :tree, true }
+          o.on('-q', 'quick output and no capture statistics') { @values[:quick] = true }
+          o.on('--time-stamp-precision PRECISION', %w[micro nano], 'timestamp digits') { |v| @values[:precision] = v.to_sym }
+          o.on('-N', '--resolve-names', 'resolve addresses') { @values[:resolve_names] = true }
+          o.on('-n', 'disable address resolution (default)') { @values[:resolve_names] = false }
+          o.on('--stats SPEC', 'io,N / conv,TYPE / endpoints,TYPE / phs') { |v| @values[:stats] << v }
+          o.on('--follow SPEC', 'tcp,ascii|hex|raw,N') { |v| @values[:follow] = v }
+          o.on('--decode-as RULE', 'e.g. udp.port==8443,dns') { |v| @values[:decode_as] << v }
+          o.on('-I', '--require FILE', 'load a custom dissector') { |v| @values[:plugins] << v }
+          o.on('-d', 'dump cBPF instructions') { @values[:dump] += 1 }
+          o.on('-Z', '--relinquish-privileges USER', 'drop capture privileges') { |v| @values[:user] = v }
+          o.on('--list-protocols', 'list protocols and fields') { @values[:list_protocols] = true }
+          o.on('--debug', 'print error backtraces') { @values[:debug] = true }
+          o.on('--no-yjit', 'disable automatic YJIT activation') { @values[:no_yjit] = true }
+          o.on('-h', '--help', 'print help') { @values[:help] = true }
+          o.on('--version', 'print version') { @values[:version] = true }
+          o.separator '  -e [-T fields: FIELD]   link header or selected field (repeatable)'
+          o.separator '  -v / -vv / -vvv         verbosity and checksum verification'
+          o.separator '  -t / -tt / -ttt / -tttt / -ttttt   timestamp style'
+          o.separator '  -x / -xx / -X / -XX     hex dump, with link header / ASCII'
+        end
+      end
+
+      # @rbs () -> void
+      def validate
+        %i[count snaplen buffer_size max_bytes interval file_count].each do |key|
+          value = @values[key]
+          raise ConfigurationError, "#{key} must be positive" if value && (!value.positive? || (value.respond_to?(:finite?) && !value.finite?))
+        end
+        raise ConfigurationError, 'snaplen exceeds 16 MiB' if @values[:snaplen] > 16 * 1024 * 1024
+        raise ConfigurationError, 'choose either -r or -i' if @values[:read] && @values[:interface]
+        raise ConfigurationError, 'rotation requires -w' if !@values[:write] && %i[max_bytes interval file_count post_rotate_command].any? { |k| @values[k] }
+        raise ConfigurationError, '-W and post-rotate-command require -C or -G' if (@values[:file_count] || @values[:post_rotate_command]) && !@values[:max_bytes] && !@values[:interval]
+        raise ConfigurationError, '-T fields requires at least one -e' if @values[:output] == :fields && @values[:fields].empty?
+        raise ConfigurationError, 'cannot combine JSON/fields output and hex dump' if @values[:hex] && !%i[summary tree].include?(@values[:output])
+        raise ConfigurationError, 'cannot display packets while writing capture to stdout' if @values[:write] == '-' && (@values[:output_explicit] || @values[:hex])
+        if @values[:read] && @values[:write] && @values[:read] != '-' && @values[:write] != '-'
+          input, output = @values[:read], @values[:write]
+          if ::File.expand_path(input) == ::File.expand_path(output) || (::File.exist?(input) && ::File.exist?(output) && ::File.identical?(input, output))
+            raise ConfigurationError, 'input and output must be different files'
+          end
+        end
+        @values[:stats].each do |spec|
+          valid = spec == 'phs' || /\A(?:conv|endpoints),(?:eth|ip|ipv6|tcp|udp)\z/.match?(spec) || /\Aio,(?:\d+(?:\.\d+)?)\z/.match?(spec) && spec.split(',').last.to_f.positive?
+          raise ConfigurationError, "invalid statistics: #{spec}" unless valid
+        end
+        raise ConfigurationError, 'invalid TCP follow specification' if @values[:follow] && !/\Atcp,(?:ascii|hex|raw),\d+\z/.match?(@values[:follow])
+      end
+    end
+  end
+end

data/lib/redhound/cli/privileges.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'etc'
+
+module Redhound
+  # @api private
+  module CLI
+    # @api private
+    module Privileges
+      # @rbs (String user) -> void
+      def self.drop(user)
+        account = Etc.getpwnam(user)
+        raise ConfigurationError, 'privilege target must not be root' if account.uid.zero?
+        Process.initgroups(account.name, account.gid)
+        Process::Sys.setgid(account.gid)
+        Process::Sys.setuid(account.uid)
+        begin
+          Process::Sys.setuid(0)
+        rescue Errno::EPERM
+          return
+        end
+        raise CaptureError, 'failed to drop root privileges permanently'
+      rescue ArgumentError => e
+        raise ConfigurationError, e.message
+      end
+    end
+  end
+end

data/lib/redhound/cli/runner.rb

@@ -0,0 +1,129 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module CLI
+    # @api private
+    class Runner
+      # @rbs (Hash[Symbol, untyped] options, ?out: untyped, ?err: untyped) -> void
+      def initialize(options, out: $stdout, err: $stderr)
+        @options, @out, @err, @count = options, out, err, 0
+        @source, @writer, @formatter, @analysis = nil, nil, nil, nil
+        @handlers = {} #: Hash[String, untyped]
+      end
+      # @rbs () -> void
+      def run
+        opts = @options
+        install_signals
+        if opts[:dump].positive?
+          if opts[:read]
+            @source = read_capture { Redhound.open(opts[:read]) }
+            linktype = read_capture { @source.next_packet }&.linktype || @source.linktype
+          else
+            linktype = opts[:interface] ? Capture::Interface.find(opts[:interface]).linktype : 1
+          end
+          program = Filter.compile(opts[:filter] || '', linktype: linktype, live: !opts[:read])
+          @out.puts(program.disassemble(format: %i[text ruby decimal][[opts[:dump], 3].min - 1]))
+          return
+        end
+        @source = if opts[:read]
+                    read_capture { Redhound.open(opts[:read], filter: opts[:filter]) }
+                  else
+                    raise ConfigurationError, 'specify an interface with -i or capture file with -r' unless opts[:interface]
+                    Capture.open(interface: opts[:interface], backend: opts[:backend], snaplen: opts[:snaplen],
+                                 promiscuous: opts[:promiscuous], buffer_size: opts[:buffer_size], direction: opts[:direction], filter: opts[:filter])
+                  end
+        if opts[:write]
+          @writer = Writer.open(opts[:write], linktype: @source.linktype, format: opts[:format], snaplen: opts[:snaplen],
+                                precision: opts[:precision], packet_buffered: opts[:packet_buffered],
+                                max_bytes: opts[:max_bytes], interval: opts[:interval], file_count: opts[:file_count],
+                                post_rotate_command: opts[:post_rotate_command], forbidden_input: opts[:read], filter: opts[:filter])
+        end
+        display = !opts[:write] || opts[:output_explicit] || opts[:hex]
+        @formatter = formatter if display && !opts[:follow]
+        hex = opts[:hex] && Output::Hexdump.new(**opts[:hex])
+        registry = Registry.default.copy
+        opts[:decode_as].each { |rule| registry.decode_as(rule) }
+        engine = Engine.new(registry: registry, verify_checksums: opts[:verbosity].positive?)
+        if display || !opts[:stats].empty? || opts[:follow]
+          @analysis = Analysis::Session.new(stats: opts[:stats], follow: opts[:follow], registry: registry)
+        end
+        Privileges.drop(opts[:user]) if opts[:user]
+        until @stopping || @source.stopped?
+          if @report_requested
+            statistics
+            @analysis&.snapshot(@err)
+            @report_requested = false
+          end
+          packet = read_capture { @source.next_packet(timeout: 0.1) }
+          next unless packet
+          @writer&.write(packet)
+          packet.engine = engine
+          @analysis&.update(packet)
+          @formatter&.format(packet, @out)
+          hex&.format(packet, @out) if display
+          @out.flush if opts[:packet_buffered] || @out.tty?
+          @count += 1
+          break if @stopping || (opts[:count] && @count >= opts[:count])
+        end
+      rescue RotationComplete, Interrupt
+        nil
+      ensure
+        begin
+          begin
+            @formatter.finish(@out) if @formatter.respond_to?(:finish)
+            @analysis&.finish(@out, @err)
+            statistics if @source && !@options[:quick] && @options[:dump].zero?
+            @writer.write_stats(@source.stats) if @writer && @source && @writer.respond_to?(:write_stats)
+          ensure
+            @writer&.close
+          end
+        ensure
+          begin
+            @source&.close
+          ensure
+            @handlers.each { |signal, handler| Signal.trap(signal, handler) }
+          end
+        end
+      end
+      # @rbs () -> untyped
+      def formatter
+        opts = @options
+        case opts[:output]
+        when :tree then Output::Tree.new
+        when :json then Output::Json.new
+        when :ndjson then Output::Json.new(ndjson: true)
+        when :fields then Output::Fields.new(opts[:fields])
+        else Output::Summary.new(timestamp: opts[:timestamp], precision: opts[:precision], link_layer: opts[:link_layer],
+                                 quick: opts[:quick], verbosity: opts[:verbosity], resolve_names: opts[:resolve_names])
+        end
+      end
+      # @rbs () -> void
+      def install_signals
+        %w[INT TERM].each do |signal|
+          @handlers[signal] = Signal.trap(signal) do
+            @stopping = true
+            @source&.stop
+            raise Interrupt if @options[:read] && @reading_capture
+          end
+        end
+        %w[USR1 INFO].select { |s| Signal.list.key?(s) }.each do |signal|
+          @handlers[signal] = Signal.trap(signal) { @report_requested = true }
+        end
+      end
+      # @rbs [T] () { () -> T } -> T
+      def read_capture
+        @reading_capture = true
+        yield
+      ensure
+        @reading_capture = false
+      end
+      # @rbs () -> void
+      def statistics
+        stats = @source.stats
+        @err.puts("#{@count} packets captured", "#{stats.received} packets received by filter", "#{stats.dropped} packets dropped by kernel")
+      end
+    end
+  end
+end

data/lib/redhound/context.rb

@@ -0,0 +1,20 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  class Context
+    attr_reader :packet, :registry, :layers
+    attr_accessor :cursor, :embedded, :extension_count
+    # @rbs (Packet packet, registry: Registry, ?verify_checksums: bool) -> void
+    def initialize(packet, registry:, verify_checksums: false)
+      @packet, @registry, @verify_checksums = packet, registry, verify_checksums
+      @cursor = Cursor.new(packet.data)
+      @embedded, @extension_count, @layers = false, 0, []
+    end
+    # @rbs () -> bool
+    def verify_checksums? = @verify_checksums
+    # @rbs () -> Layer?
+    def network = @layers.reverse.find { |l| %i[ipv4 ipv6].include?(l.protocol) && l.embedded == @embedded }
+  end
+end

data/lib/redhound/cursor.rb

@@ -0,0 +1,69 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # Checked binary reads within an absolute packet slice.
+  class Cursor
+    # Internal exception for a checked read beyond the captured slice.
+    class Truncated < StandardError; end
+    # Underlying data and absolute start/end bounds.
+    attr_reader :data, :start, :limit
+
+    # @rbs (String data, ?Integer start, ?Integer? limit) -> void
+    # Create a bounded view; reject invalid ranges.
+    def initialize(data, start = 0, limit = nil)
+      @data, @start, @limit = data, start, limit || data.bytesize
+      raise ArgumentError, 'invalid cursor bounds' if start.negative? || @limit < start || @limit > data.bytesize
+    end
+
+    # @rbs () -> Integer
+    # Remaining slice length in bytes.
+    def remaining = @limit - @start
+    # @rbs (Integer off) -> Integer
+    # Read an unsigned byte.
+    def u8(off)
+      check(off, 1)
+      @data.getbyte(@start + off) #: Integer
+    end
+    # @rbs (Integer off) -> Integer
+    # Read an unsigned network-order 16-bit integer.
+    def u16(off)
+      check(off, 2)
+      @data.unpack1('n', offset: @start + off) #: Integer
+    end
+    # @rbs (Integer off) -> Integer
+    # Read an unsigned network-order 32-bit integer.
+    def u32(off)
+      check(off, 4)
+      @data.unpack1('N', offset: @start + off) #: Integer
+    end
+    # @rbs (Integer off) -> Integer
+    # Read an unsigned network-order 64-bit integer.
+    def u64(off)
+      check(off, 8)
+      @data.unpack1('Q>', offset: @start + off) #: Integer
+    end
+    # @rbs (String template, Integer size, ?Integer off) -> Array[untyped]
+    # Unpack a checked fixed-width header.
+    def unpack(template, size, off = 0) = (check(off, size); @data.unpack(template, offset: @start + off))
+    # @rbs (Integer off, Integer len) -> String
+    # Read a checked binary substring.
+    def bytes(off, len)
+      check(off, len)
+      @data.byteslice(@start + off, len) #: String
+    end
+
+    # @rbs (Integer from, Integer to) -> Cursor
+    # Create a child slice that cannot escape the parent bounds.
+    def sub(from, to)
+      raise ArgumentError, 'child cursor escapes parent' if from < @start || from > @limit || to < from
+      Cursor.new(@data, from, [to, @limit].min)
+    end
+
+    # @rbs (Integer off, Integer len) -> void
+    # Validate a relative offset and read length.
+    def check(off, len)
+      raise Truncated, "need #{len} bytes at #{@start + off}, limit #{@limit}" if off.negative? || len.negative? || off + len > remaining
+    end
+  end
+end

data/lib/redhound/diagnostic.rb

@@ -0,0 +1,7 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # Structured protocol diagnostic with severity, stable code, message and optional field.
+  Diagnostic = Data.define(:severity, :code, :message, :field)
+end

data/lib/redhound/dissector.rb

@@ -0,0 +1,138 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # Base class and declarative fixed-header DSL for custom protocols.
+  class Dissector
+    # Unpack formats and byte lengths supported by the header DSL.
+    TYPES = { uint8: ['C', 1], uint16: ['n', 2], uint32: ['N', 4], uint64: ['Q>', 8],
+              mac: ['a6', 6], ipv4: ['N', 4], ipv6: ['a16', 16] }.freeze
+
+    # Build a single unpack template and its field descriptions.
+    class Header
+      # Compiled unpack template, header byte length and field definitions.
+      attr_reader :template, :length, :definitions
+      # @rbs () -> void
+      # Start an empty fixed-header definition.
+      def initialize
+        @template, @length, @index, @definitions = +'', 0, 0, []
+      end
+
+      # @rbs (Symbol type, Symbol key, String name, **untyped opts) -> void
+      # Append a typed fixed-width field with optional format/enum metadata.
+      def field(type, key, name, **opts)
+        fmt, size = TYPES.fetch(type)
+        @definitions << FieldDefinition.new(key, name, type, @length, size, @index, nil, nil, 1, opts[:format], opts[:enum])
+        @template << fmt
+        @length += size
+        @index += 1
+      end
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append an unsigned 8-bit field.
+      def uint8(key, name, **opts) = field(:uint8, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a network-order unsigned 16-bit field.
+      def uint16(key, name, **opts) = field(:uint16, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a network-order unsigned 32-bit field.
+      def uint32(key, name, **opts) = field(:uint32, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a network-order unsigned 64-bit field.
+      def uint64(key, name, **opts) = field(:uint64, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a six-byte MAC address.
+      def mac(key, name, **opts) = field(:mac, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a four-byte IPv4 address.
+      def ipv4(key, name, **opts) = field(:ipv4, key, name, **opts)
+      # @rbs (Symbol key, String name, **untyped opts) -> void
+      # Append a sixteen-byte IPv6 address.
+      def ipv6(key, name, **opts) = field(:ipv6, key, name, **opts)
+
+      # @rbs (Integer width) { (Header) [self: Header] -> void } -> void
+      # Define bit fields filling an 8/16/32/64-bit network-order word.
+      def bits(width, &block)
+        raise ArgumentError, 'bit width must be 8, 16, 32 or 64' unless [8, 16, 32, 64].include?(width)
+        @bit_width, @bit_left = width, width
+        instance_eval(&block)
+        raise ArgumentError, 'bit fields must fill the word' unless @bit_left.zero?
+        @template << TYPES.fetch("uint#{width}".to_sym).first
+        @length += width / 8
+        @index += 1
+      end
+
+      # @rbs (Symbol key, String name, Integer width, **untyped opts) -> void
+      # Append a bit field inside bits, optionally scaled/formatted.
+      def bit(key, name, width, **opts)
+        raise ArgumentError, 'invalid bit field width' unless width.positive? && width <= @bit_left
+        @bit_left -= width
+        @definitions << FieldDefinition.new(key, name, :bits, @length, @bit_width / 8, @index,
+                                            @bit_left, (1 << width) - 1, opts.fetch(:scale, 1), opts[:format], opts[:enum])
+      end
+    end
+
+    class << self
+      # @rbs () -> Symbol
+      # Registered protocol symbol.
+      def protocol_id = @protocol_id
+      # @rbs () -> String
+      # Human-readable protocol name.
+      def protocol_name = @protocol_name
+      # @rbs () -> String
+      # Short output label.
+      def short_name = @short_name
+      # @rbs () -> untyped
+      # Compiled header definition, if one was declared.
+      def compiled_header = @compiled_header
+      # @rbs (Symbol id, name: String, short: String) -> void
+      # Declare protocol identity and register the dissector.
+      def protocol(id, name:, short:)
+        @protocol_id, @protocol_name, @short_name = id, name, short
+        Registry.default.register_protocol(self)
+      end
+      # @rbs (String key, *Integer values) -> void
+      # Register this protocol under one or more dispatch values.
+      def dissects_on(key, *values)
+        values.each { |value| Registry.default.register(key, value, self) }
+      end
+      # @rbs () { (Header) [self: Header] -> void } -> void
+      # Compile a fixed header from the DSL block.
+      def header(&block)
+        @compiled_header = Header.new
+        @compiled_header.instance_eval(&block)
+        @compiled_header.template.freeze
+      end
+      # @rbs () -> String
+      # Compiled unpack template, or an empty template.
+      def header_template = @compiled_header&.template || ''
+    end
+
+    # @rbs (Context ctx, Cursor cursor) -> Layer
+    # Decode fixed fields then invoke the variable-header hook.
+    def parse(ctx, cursor)
+      header = self.class.compiled_header
+      length = header&.length || 0
+      raw = cursor.unpack(self.class.header_template, length)
+      defs = header ? header.definitions.dup : Array.new
+      values = {} #: Hash[Symbol, untyped]
+      defs.each do |d|
+        val = raw[d.index]
+        val = ((val >> d.shift) & d.mask) * d.scale if d.shift
+        values[d.key] = val
+      end
+      layer = Layer.new(self.class.protocol_id, cursor.start, length, cursor.limit,
+                        definitions: defs, values: values, embedded: ctx.embedded)
+      dissect(ctx, layer)
+      layer
+    end
+    # @rbs (Context ctx, Layer layer) -> void
+    # Override to parse variable fields using the bounded Context cursor.
+    def dissect(ctx, layer); end
+    # @rbs (Context ctx, Layer layer) -> untyped
+    # Override to return the next protocol class or nil.
+    def next_dissector(ctx, layer) = nil
+    # @rbs (Layer layer) -> String
+    # Override to format the layer summary.
+    def summary(layer) = self.class.short_name || layer.protocol.to_s.upcase
+  end
+end

data/lib/redhound/engine.rb

@@ -0,0 +1,66 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  class Engine
+    MAX_DEPTH = 32
+    # @rbs () -> Engine
+    def self.default = (@default ||= new)
+    # @rbs (?registry: Registry, ?verify_checksums: bool) -> void
+    def initialize(registry: Registry.default, verify_checksums: false)
+      @registry, @verify_checksums = registry, verify_checksums
+    end
+    # @rbs (Packet packet) -> Array[Layer]
+    def dissect(packet)
+      ctx = Context.new(packet, registry: @registry, verify_checksums: @verify_checksums)
+      klass = @registry.lookup('linktype', packet.linktype) || Protocols::Data
+      loop do
+        cursor = ctx.cursor
+        layer = safely(klass, ctx, cursor)
+        ctx.layers << layer
+        break if layer.error? || layer.payload_empty? || klass == Protocols::Data
+        if ctx.layers.length >= MAX_DEPTH
+          layer.diagnose(:error, :depth_exceeded)
+          break
+        end
+        ctx.cursor = cursor.sub(layer.payload_offset, layer.payload_end)
+        next_klass = next_dissector(klass, ctx, layer)
+        break if layer.error?
+        klass = next_klass || Protocols::Data
+      end
+      ctx.layers
+    end
+
+    # @rbs (untyped klass, Context ctx, Layer layer) -> untyped
+    def next_dissector(klass, ctx, layer)
+      klass.new.next_dissector(ctx, layer) || @registry.heuristic(layer.protocol, ctx, ctx.cursor)
+    rescue Cursor::Truncated => e
+      layer.diagnose(:note, :truncated, e.message)
+      nil
+    rescue StandardError => e
+      raise if ENV['REDHOUND_STRICT'] == '1'
+      layer.diagnose(:error, :dissector_bug, "#{e.class}: #{e.message}")
+      nil
+    end
+
+    # @rbs (untyped klass, Context ctx, Cursor cursor) -> Layer
+    def safely(klass, ctx, cursor)
+      layer = klass.new.parse(ctx, cursor)
+      if layer.payload_offset < cursor.start || layer.payload_end < layer.payload_offset
+        layer.diagnose(:error, :bad_length)
+      elsif layer.payload_offset > cursor.limit || layer.payload_end > cursor.limit
+        layer.diagnose(:note, :truncated)
+        layer.payload_end = cursor.limit
+      end
+      layer
+    rescue Cursor::Truncated => e
+      Layer.new(klass.protocol_id, cursor.start, cursor.remaining, cursor.limit, embedded: ctx.embedded)
+           .diagnose(:note, :truncated, e.message)
+    rescue StandardError => e
+      raise if ENV['REDHOUND_STRICT'] == '1'
+      Layer.new(klass.protocol_id, cursor.start, 0, cursor.limit, embedded: ctx.embedded)
+           .diagnose(:error, :dissector_bug, "#{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/redhound/errors.rb

@@ -0,0 +1,38 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # Base exception for Redhound operational and configuration errors.
+  class Error < StandardError; end
+  # Capture-device or live-operation failure.
+  class CaptureError < Error; end
+  # @api private
+  class RotationComplete < CaptureError; end
+  # Insufficient permission to access the capture device.
+  class PermissionDenied < CaptureError; end
+  # Requested capture interface does not exist.
+  class InterfaceNotFound < CaptureError; end
+  # Requested platform or capture capability is unavailable.
+  class UnsupportedPlatform < CaptureError; end
+  # Malformed or unsupported capture-file structure.
+  class FileFormatError < Error; end
+  # Invalid command-line or library configuration.
+  class ConfigurationError < Error; end
+  # Invalid cBPF program or unsupported filter operation.
+  class FilterError < Error; end
+  # Filter exceeds the target platform instruction limit.
+  class FilterTooLarge < FilterError; end
+  # Capture-filter syntax error with original expression and byte position.
+  class FilterSyntaxError < FilterError
+    # Original filter expression and zero-based error position.
+    attr_reader :expression, :position
+
+    # @rbs (String message, ?expression: String?, ?position: Integer?) -> void
+    # Create a syntax diagnostic suitable for a caret display.
+    def initialize(message, expression: nil, position: nil)
+      @expression = expression
+      @position = position
+      super(message)
+    end
+  end
+end