redhound 1.0.0 → 2.0.0.rc1

data/lib/redhound/analysis/tcp_stream.rb

@@ -0,0 +1,151 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class TcpStream
+      attr_reader :base_seq, :expected, :diagnostics, :deliveries, :gap_lengths, :fin
+      # @rbs (?max_bytes: Integer) -> void
+      def initialize(max_bytes: 1 << 20)
+        raise ArgumentError, 'max_bytes must be positive' unless max_bytes.positive?
+        @max_bytes, @expected, @history_start = max_bytes, 0, 0
+        @highest = 0
+        @base_seq = nil # @rbs Integer?
+        @history = ''.b
+        @queue = [] #: Array[untyped]
+        @diagnostics, @deliveries, @gap_lengths = [], [], [] # @rbs untyped
+        @fin, @fin_offset = false, nil # @rbs untyped
+      end
+      # @rbs (Integer sequence, String data, ?syn: bool, ?fin: bool, ?frame: Integer) -> Array[String]
+      def push(sequence, data, syn: false, fin: false, frame: 0)
+        @diagnostics, @deliveries, @gap_lengths = [], [], []
+        unless @base_seq
+          @base_seq = sequence
+          @expected = syn ? 1 : 0
+          @history_start = @expected
+          @highest = @expected
+        end
+        base = @base_seq #: Integer
+        start = @expected + Util::Seq.signed_diff(sequence, (base + @expected) % Util::Seq::MOD) + (syn ? 1 : 0)
+        @fin_offset = start + data.bytesize if fin
+        @diagnostics << :out_of_order if !data.empty? && start >= @expected && start < @highest
+        @diagnostics << :lost_segment if (!data.empty? || fin) && start > @highest
+        @diagnostics << :retransmission if !data.empty? && start < @expected
+        @highest = [@highest, start + data.bytesize + (fin ? 1 : 0)].max
+        pieces = [[start, data, frame]]
+        if start < @expected
+          length = [data.bytesize, @expected - start].min
+          compare_overlap(start, data, @history_start, @history)
+          pieces = length >= data.bytesize ? Array.new : [[start + length, data.byteslice(length..), frame]] #: Array[untyped]
+        end
+        @queue.each do |old_start, old_data, _old_frame|
+          replacement = [] #: Array[untyped]
+          pieces.each do |pos, bytes, origin|
+            compare_overlap(pos, bytes, old_start, old_data)
+            ending, old_end = pos + bytes.bytesize, old_start + old_data.bytesize
+            if pos < old_end && ending > old_start
+              replacement << [pos, bytes.byteslice(0, old_start - pos), origin] if pos < old_start
+              replacement << [old_end, bytes.byteslice(old_end - pos..), origin] if ending > old_end
+            else
+              replacement << [pos, bytes, origin]
+            end
+          end
+          pieces = replacement
+        end
+        if !data.empty? && pieces.empty?
+          @diagnostics.delete(:out_of_order)
+          @diagnostics.delete(:lost_segment)
+          @diagnostics << :retransmission unless @diagnostics.include?(:retransmission)
+        end
+        pieces.each do |piece|
+          next if piece[1].empty?
+          index = @queue.bsearch_index { |entry| entry[0] >= piece[0] } || @queue.length
+          @queue.insert(index, piece)
+        end
+        drain
+        while bytesize > @max_bytes || (@queue.first && @queue.first[0] - @expected > @max_bytes)
+          break if @queue.empty?
+          flush_gap(false)
+        end
+        trim_history
+        consume_fin
+        @deliveries.filter_map(&:first)
+      end
+
+      # @rbs (Integer start, String data, Integer old_start, String old_data) -> void
+      def compare_overlap(start, data, old_start, old_data)
+        from = [start, old_start].max
+        to = [start + data.bytesize, old_start + old_data.bytesize].min
+        return unless from < to
+        if data.byteslice(from - start, to - from) != old_data.byteslice(from - old_start, to - from) && !@diagnostics.include?(:overlap_mismatch)
+          @diagnostics << :overlap_mismatch
+        end
+      end
+      # @rbs () -> void
+      def drain
+        while @queue.first && @queue.first[0] == @expected
+          pos, data, frame = @queue.shift
+          @deliveries << [data, frame]
+          @history_start = pos if @history.empty?
+          @history << data
+          @expected += data.bytesize
+        end
+      end
+      # @rbs (?bool clear) -> Array[String]
+      def flush_gap(clear = true)
+        @deliveries, @gap_lengths = [], [] if clear
+        target = @queue.empty? ? @fin_offset : @queue.first[0]
+        return [] unless target
+        gap = target - @expected
+        if gap.positive?
+          @diagnostics << :reassembly_gap
+          @gap_lengths << gap
+          @deliveries << [nil, gap]
+          @expected += gap
+          @history.clear
+          @history_start = @expected
+        end
+        drain
+        consume_fin
+        trim_history
+        @deliveries.filter_map(&:first)
+      end
+      # @rbs () -> void
+      def trim_history
+        # Previously delivered bytes share the stream's bounded budget with holes.
+        limit = [@max_bytes - @queue.sum { |item| item[1].bytesize + 128 }, 0].max
+        excess = @history.bytesize - limit
+        if excess.positive?
+          @history = @history.byteslice(excess..) #: String
+          @history_start += excess
+        end
+      end
+      # @rbs () -> Integer
+      def bytesize = @history.bytesize + @queue.sum { |item| item[1].bytesize + 128 }
+      # @rbs () -> bool
+      def pending? = !@queue.empty? || (!@fin && !@fin_offset.nil?)
+      # @rbs () -> bool
+      def fin_seen? = !@fin_offset.nil?
+      # @rbs () -> void
+      def consume_fin
+        if !@fin && @fin_offset && @expected >= @fin_offset
+          @fin = true
+          @expected += 1
+        end
+      end
+      # @rbs () -> Integer
+      def next_sequence = ((@base_seq || 0) + @expected) % Util::Seq::MOD
+      # @rbs () -> void
+      def clear_deliveries = @deliveries.clear
+      # @rbs () -> void
+      def release
+        @history.clear
+        @queue.clear
+        @deliveries.clear
+        @gap_lengths.clear
+      end
+    end
+  end
+end

data/lib/redhound/analysis.rb

@@ -0,0 +1,129 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative 'util/seq'
+require_relative 'stream_dissector'
+require_relative 'analysis/flow_key'
+require_relative 'analysis/tcp_stream'
+require_relative 'analysis/flow_table'
+require_relative 'analysis/ip_reassembler'
+require_relative 'analysis/tcp_analysis'
+require_relative 'analysis/tcp_reassembler'
+require_relative 'analysis/stats'
+require_relative 'output/follow'
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class Session
+      attr_reader :flows, :ip_reassembler, :tcp_reassembler, :statistics
+      # @rbs (?stats: Array[String], ?follow: String?, ?registry: Registry, ?max_state_bytes: Integer, ?max_flows: Integer, ?ip_bytes: Integer, ?tcp_bytes: Integer, ?stream_bytes: Integer, ?protocol_streams: bool) -> void
+      def initialize(stats: [], follow: nil, registry: Registry.default, max_state_bytes: 256 << 20, max_flows: 100_000,
+                     ip_bytes: 16 << 20, tcp_bytes: 64 << 20, stream_bytes: 1 << 20, protocol_streams: true)
+        raise ArgumentError, 'state limit must be positive' unless max_state_bytes.positive?
+        @max_state_bytes, @finished = max_state_bytes, false
+        @flows = FlowTable.new(max_flows: max_flows)
+        @ip_reassembler = IpReassembler.new(max_bytes: [ip_bytes, max_state_bytes].min)
+        @follow = follow ? Output::Follow.new(follow) : nil
+        @tcp_reassembler = TcpReassembler.new(registry: registry, max_bytes: [tcp_bytes, max_state_bytes].min,
+                                             stream_bytes: stream_bytes, protocol_streams: protocol_streams, follow: @follow)
+        @flows.on_remove = ->(flow) { @tcp_reassembler.finish_flow(flow) }
+        specs = stats.uniq
+        raise ConfigurationError, 'too many statistics specifications (maximum 64)' if specs.size > 64
+        row_limit = [100_000, [((128 << 20) / [specs.size, 1].max) / 1024, 1].max].min
+        @statistics = specs.map { |spec| statistic(spec, row_limit) }
+      end
+      # @rbs (String specification, Integer max_rows) -> untyped
+      def statistic(specification, max_rows)
+        kind, argument = specification.split(',', 2)
+        case kind
+        when 'io'
+          raise ConfigurationError, 'io statistics requires an interval of at least one nanosecond' unless argument && argument.match?(/\A(?:\d+(?:\.\d*)?|\.\d+)\z/) && argument.to_f.finite? && argument.to_f >= 0.000_000_001
+          Stats::Io.new(argument.to_f, max_rows: max_rows)
+        when 'conv', 'endpoints'
+          raise ConfigurationError, 'statistics type must be eth, ip, ipv6, tcp or udp' unless argument && %w[eth ip ipv6 tcp udp].include?(argument)
+          klass = kind == 'conv' ? Stats::Conversations : Stats::Endpoints
+          klass.new(argument.to_sym, max_rows: max_rows)
+        when 'phs'
+          raise ConfigurationError, 'phs does not accept an argument' if argument
+          Stats::Hierarchy.new(max_rows: max_rows)
+        else raise ConfigurationError, "unknown statistics: #{specification}"
+        end
+      end
+      # @rbs (Packet packet) -> void
+      def update(packet)
+        return if @finished
+        @flows.advance(packet.timestamp_ns)
+        @ip_reassembler.advance(packet.timestamp_ns)
+        fragment = @ip_reassembler.descriptor(packet)
+        analyzed = packet
+        if fragment
+          boundary = packet.layers.index(fragment[1]) #: Integer
+          packet.layers.slice!(boundary + 1, packet.layers.length)
+          virtual = @ip_reassembler.update(packet)
+          if virtual
+            packet.meta[:reassembled_from] = virtual.meta[:reassembled_from]
+            packet.meta[:reassembled_packet] = virtual
+            analyzed = virtual
+          else
+            @statistics.each { |stat| stat.update(packet) }
+            enforce_limit(packet)
+            return
+          end
+        end
+        result = @flows.update(analyzed)
+        if result
+          flow, direction = result
+          @tcp_reassembler.update(analyzed, flow, direction) if flow.key[0] == :tcp
+          @flows.account(flow)
+        end
+        if analyzed != packet
+          packet.layers.concat(analyzed.layers.reject { |layer| %i[ipv4 ipv6 ipv6_ext].include?(layer.protocol) })
+          packet.layers.last.add(:ip_reassembled_from, 'ip.reassembled_from', packet.meta[:reassembled_from])
+        end
+        @statistics.each { |stat| stat.update(packet) }
+        @tcp_reassembler.enforce_limit(@flows, packet)
+        enforce_limit(packet)
+      end
+      # @rbs (Packet packet) -> void
+      def enforce_limit(packet)
+        while bytesize > @max_state_bytes
+          flow = @flows.evict
+          unless flow
+            statistic = @statistics.max_by(&:bytesize)
+            break unless statistic && statistic.bytesize.positive?
+            statistic.evict
+          end
+          packet.layers.last.diagnose(:warning, :state_evicted, 'analysis state memory limit exceeded')
+        end
+      end
+      # @rbs () -> Integer
+      def bytesize = @flows.bytesize + @ip_reassembler.bytesize + @statistics.sum(&:bytesize)
+      # @rbs (untyped err) -> void
+      def snapshot(err)
+        @statistics.each { |stat| stat.format(err) }
+        err.puts("#{@flows.evicted} flows evicted; #{@flows.expired} flows expired") if @flows.evicted.positive? || @flows.expired.positive?
+        err.puts("#{@ip_reassembler.evicted} fragmented datagrams evicted; #{@ip_reassembler.expired} expired") if @ip_reassembler.evicted.positive? || @ip_reassembler.expired.positive?
+      end
+      # @rbs (untyped out, untyped err) -> void
+      def finish(out, err)
+        return if @finished
+        @flows.values.each do |flow|
+          @tcp_reassembler.finish_flow(flow).each do |layer|
+            layer.diagnostics.each do |diagnostic|
+              message = diagnostic.message.b.gsub(/[^\x20-\x7e]/n) { |byte| format('\\x%02x', byte.getbyte(0)) }
+              err.puts("stream #{flow.id} #{layer.protocol}: #{diagnostic.code}: #{message}")
+            end
+          end
+          @flows.account(flow)
+        end
+        @follow&.format(out)
+        snapshot(err)
+      ensure
+        @finished = true
+        @follow&.close
+      end
+    end
+  end
+end

data/lib/redhound/capture/bsd/bpf_device.rb

@@ -0,0 +1,152 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Bsd
+      # @api private
+      class BpfDevice < Source
+        attr_reader :linktype, :interfaces
+
+        # @rbs (interface: String | Integer | Interface, ?snaplen: Integer, ?promiscuous: bool, ?buffer_size: Integer?, ?direction: Symbol, ?filter: String?) -> void
+        def initialize(interface:, snaplen: 262_144, promiscuous: true, buffer_size: nil, direction: :inout, filter: nil)
+          super()
+          raise ArgumentError, 'snaplen must be between 1 and 16 MiB' unless snaplen.between?(1, File::Format::MAX_RECORD)
+          raise ArgumentError, 'direction must be in, out or inout' unless %i[in out inout].include?(direction)
+
+          @interface = interface.is_a?(Interface) ? interface : Interface.find(interface)
+          raise UnsupportedPlatform, 'any capture is only available on Linux' if @interface.name == 'any'
+
+          @snaplen, @direction = snaplen, direction
+          @device = open_device
+          if buffer_size
+            raise ArgumentError, 'buffer size must be positive' unless buffer_size.positive?
+            @device.ioctl(Constants::BIOCSBLEN, [buffer_size].pack('I'))
+          end
+          @device.ioctl(Constants::BIOCSETIF, [@interface.name].pack('a16') + "\0" * 16)
+          buffer = "\0" * 4
+          @device.ioctl(Constants::BIOCGBLEN, buffer)
+          @buffer_size = buffer.unpack1('I')
+          @device.ioctl(Constants::BIOCGDLT, buffer)
+          dlt = buffer.unpack1('I')
+          @linktype = dlt == 12 ? 101 : dlt
+          @interfaces = [Interface.new(name: @interface.name, index: @interface.index, flags: @interface.flags,
+                                       linktype: @linktype, snaplen:)]
+          attach_filter(filter ? Filter.compile(filter, linktype: @linktype, snaplen:) : nil)
+          @device.ioctl(Constants::BIOCPROMISC, 0) if promiscuous && !@interface.loopback?
+          @device.ioctl(Constants::BIOCIMMEDIATE, [1].pack('I'))
+          configure_direction
+          @device.ioctl(Constants::BIOCFLUSH, 0)
+          @records, @offset = ''.b, 0
+        rescue Errno::EPERM, Errno::EACCES => error
+          @device&.close
+          raise PermissionDenied, "capture requires access to /dev/bpf*: #{error.message}"
+        rescue StandardError
+          @device&.close
+          raise
+        end
+
+        # @rbs (?timeout: Numeric?) -> Packet?
+        def next_packet(timeout: nil)
+          deadline = deadline_for(timeout)
+          until @stopped || @closed
+            if @offset >= @records.bytesize
+              return nil unless wait_readable(@device, deadline)
+              result = @device.read_nonblock(@buffer_size, exception: false)
+              next if result == :wait_readable
+              return nil unless result
+
+              @records, @offset = result, 0
+              next if @records.empty?
+            end
+            raise CaptureError, 'truncated BPF record header' if @offset + 18 > @records.bytesize
+
+            seconds, micros, caplen, original_length, header_length = @records.unpack('I4S', offset: @offset)
+            unless header_length >= 18 && caplen <= original_length && @offset + header_length + caplen <= @records.bytesize
+              raise CaptureError, 'invalid BPF record length'
+            end
+            direction = if @extended_header && header_length >= 20
+                          (@records.getbyte(@offset + 19) & 1).positive? ? :out : :in
+                        elsif @direction != :inout
+                          @direction
+                        end
+            data = @records.byteslice(@offset + header_length, [caplen, @snaplen].min)
+            @offset += (header_length + caplen + 3) & ~3
+            @number += 1
+            @capture_stats.captured += 1
+            return Packet.new(data, timestamp_ns: seconds * 1_000_000_000 + micros * 1_000,
+                              original_length:, linktype: @linktype, interface: @interfaces.first, direction:, number: @number,
+                              meta: { csum_not_ready: direction == :out })
+          end
+          nil
+        end
+
+        # @rbs (untyped program) -> void
+        def attach_filter(program)
+          instructions = program ? program.instructions : [[0x06, 0, 0, @snaplen]] #: Array[[Integer, Integer, Integer, Integer]]
+          Filter::BPF::Validator.validate!(instructions)
+          raise FilterTooLarge, 'macOS BPF programs are limited to 512 instructions' if instructions.size > 512
+          packed = instructions.map { |instruction| instruction.pack('S C C L') }.join
+          @device.ioctl(Constants::BIOCSETF, [instructions.size, packed].pack('L x4 P'))
+        end
+
+        # @rbs () -> Stats
+        def stats
+          unless @closed
+            buffer = "\0" * 8
+            @device.ioctl(Constants::BIOCGSTATS, buffer)
+            @capture_stats.received, @capture_stats.dropped = buffer.unpack('I2')
+          end
+          @capture_stats
+        end
+
+        # @rbs () -> void
+        def close
+          return if @closed
+
+          begin
+            stats
+          ensure
+            super
+            @device.close
+          end
+        end
+
+        private
+
+        # @rbs () -> ::File
+        def open_device
+          256.times do |index|
+            begin
+              return ::File.open("/dev/bpf#{index}", ::File::RDWR)
+            rescue Errno::EBUSY
+              next
+            rescue Errno::ENOENT
+              break
+            end
+          end
+          raise CaptureError, 'no available BPF device'
+        end
+
+        # @rbs () -> void
+        def configure_direction
+          begin
+            @device.ioctl(Constants::BIOCSDIRECTION, [{ in: 1, out: 2, inout: 3 }.fetch(@direction)].pack('I'))
+          rescue Errno::EINVAL, Errno::ENOTTY
+            raise UnsupportedPlatform, 'outgoing-only capture is unavailable on this macOS version' if @direction == :out
+
+            @device.ioctl(Constants::BIOCSSEESENT, [@direction == :in ? 0 : 1].pack('I'))
+          end
+          begin
+            @device.ioctl(Constants::BIOCSEXTHDR, [1].pack('I'))
+            @extended_header = true
+          rescue Errno::EINVAL, Errno::ENOTTY
+            @extended_header = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redhound/capture/bsd/constants.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Bsd
+      # @api private
+      module Constants
+        # Verified against the macOS SDK's net/bpf.h on arm64 and 64-bit ioctl layout.
+        BIOCSBLEN = 0xc0044266
+        BIOCGBLEN = 0x40044266
+        BIOCSETF = 0x80104267
+        BIOCFLUSH = 0x20004268
+        BIOCPROMISC = 0x20004269
+        BIOCGDLT = 0x4004426a
+        BIOCSETIF = 0x8020426c
+        BIOCGSTATS = 0x4008426f
+        BIOCIMMEDIATE = 0x80044270
+        BIOCSSEESENT = 0x80044277
+        # Apple XNU bsd/net/bpf_private.h: extended headers expose direction at byte 19.
+        BIOCSEXTHDR = 0x8004427c
+        BIOCSDIRECTION = 0x8004428b
+        BPF_ALIGNMENT = 4
+      end
+    end
+  end
+end

data/lib/redhound/capture/file_source.rb

@@ -0,0 +1,83 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    class FileSource < Source
+      attr_reader :reader
+
+      # @rbs (untyped input, ?filter: String?) -> void
+      def initialize(input, filter: nil)
+        super()
+        @owned = input.is_a?(String) && input != '-'
+        @io = input.is_a?(String) ? (input == '-' ? $stdin : ::File.open(input, 'rb')) : input
+        @io.binmode if @io.respond_to?(:binmode)
+        magic = File::Format.read_exact(@io, 4)
+        @reader = if magic == File::Format::PCAPNG_MAGIC
+                    File::PcapngReader.new(@io, magic)
+                  elsif File::Format::PCAP_MAGICS.key?(magic)
+                    File::PcapReader.new(@io, magic)
+                  else
+                    raise FileFormatError, 'unrecognized capture file magic'
+                  end
+        @filter_expression = filter
+        @filters = {} #: Hash[Integer, untyped]
+        @filters[@reader.linktype] = Filter.compile(filter, linktype: @reader.linktype) if filter
+      rescue StandardError, Interrupt
+        @io.close if @owned && @io && !@io.closed?
+        raise
+      end
+
+      # @rbs (untyped input, ?filter: String?) -> FileSource
+      # @rbs [T] (untyped input, ?filter: String?) { (FileSource) -> T } -> T
+      def self.open(input, filter: nil)
+        source = new(input, filter:)
+        return source unless block_given?
+
+        begin
+          yield source
+        ensure
+          source.close
+        end
+      end
+
+      # @rbs (?timeout: Numeric?) -> Packet?
+      def next_packet(timeout: nil)
+        return nil if @stopped || @closed
+
+        while (packet = @reader.next_packet)
+          @capture_stats.received += 1
+          if @filter_expression
+            program = (@filters[packet.linktype] ||= Filter.compile(@filter_expression, linktype: packet.linktype))
+            next unless program.match?(packet)
+          end
+          @capture_stats.captured += 1
+          return packet
+        end
+        stop
+        nil
+      end
+
+      # @rbs () -> Integer
+      def linktype = @reader.linktype
+
+      # @rbs () -> Array[Interface]
+      def interfaces = @reader.interfaces
+
+      # @rbs () -> Stats
+      def stats
+        @reader.respond_to?(:statistics?) && @reader.statistics? ? @reader.stats : super
+      end
+
+      # @rbs () -> void
+      def close
+        return if @closed
+
+        super
+        @io.close if @owned
+      end
+    end
+  end
+end

data/lib/redhound/capture/interface.rb

@@ -0,0 +1,66 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'socket'
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    class Interface
+      attr_reader :name, :index, :linktype, :snaplen, :flags, :mtu, :mac, :description, :filter, :meta
+
+      # @rbs (name: String, ?index: Integer, ?linktype: Integer, ?snaplen: Integer, ?flags: Integer, ?mtu: Integer?, ?mac: String?, ?description: String?, ?filter: String?, ?meta: Hash[Symbol, untyped]) -> void
+      def initialize(name:, index: 0, linktype: 1, snaplen: 262_144, flags: 0, mtu: nil, mac: nil,
+                     description: nil, filter: nil, meta: {})
+        @name, @index, @linktype, @snaplen, @flags = name, index, linktype, snaplen, flags
+        @mtu, @mac, @description, @filter, @meta = mtu, mac, description, filter, meta
+      end
+
+      # @rbs () -> Integer
+      def ifindex = @index
+
+      # @rbs () -> bool
+      def up? = (@flags & 1).positive?
+
+      # @rbs () -> bool
+      def loopback? = (@flags & 8).positive?
+
+      # @rbs () -> bool
+      def running? = (@flags & 0x40).positive?
+
+      # @rbs () -> String
+      def to_s
+        state = [up? ? 'Up' : 'Down', running? ? 'Running' : nil, loopback? ? 'Loopback' : nil].compact.join(', ')
+        "#{@index}.#{@name} [#{state}]#{@mac ? " #{@mac}" : ''}#{@mtu ? " mtu #{@mtu}" : ''}"
+      end
+
+      # @rbs () -> Array[Interface]
+      def self.all
+        Socket.getifaddrs.uniq(&:name).map do |address|
+          index = address.ifindex || 0
+          interface = new(name: address.name, index:, flags: address.flags)
+          if RUBY_PLATFORM.include?('linux')
+            Linux::Ifreq.interface(address.name, index:)
+          else
+            interface
+          end
+        end.sort_by(&:index)
+      end
+
+      # @rbs (String | Integer value) -> Interface
+      def self.find(value)
+        return new(name: 'any', linktype: 276) if value.to_s == 'any'
+
+        found = all.find { |item| item.name == value.to_s || item.index.to_s == value.to_s }
+        return found if found
+
+        names = all.map(&:name)
+        suggestions = names.select { |name| name.include?(value.to_s[0, 2]) }
+        message = "interface #{value.inspect} not found"
+        message += "; available: #{(suggestions.empty? ? names : suggestions).join(', ')}"
+        raise InterfaceNotFound, message
+      end
+    end
+  end
+end

data/lib/redhound/capture/linktype.rb

@@ -0,0 +1,30 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Linktype
+      VALUES = { null: 0, ethernet: 1, ether: 1, raw: 101, loop: 108, sll: 113,
+                 linux_sll: 113, radiotap: 127, ipv4: 228, ipv6: 229, sll2: 276, linux_sll2: 276 }.freeze
+
+      # @rbs (Integer | Symbol | String value) -> Integer
+      def self.resolve(value)
+        return value if value.is_a?(Integer) && value.between?(0, 65_535)
+
+        VALUES.fetch(value.to_s.downcase.to_sym) { raise ArgumentError, "unknown link type: #{value}" }
+      end
+
+      # @rbs (Integer value) -> String
+      def self.name(value)
+        VALUES.key(value)&.to_s || "LINKTYPE_#{value}"
+      end
+
+      # @rbs (Integer hardware_type) -> Integer
+      def self.for_hardware(hardware_type)
+        { 1 => 1, 772 => 1, 65_534 => 101, 803 => 127 }.fetch(hardware_type, 276)
+      end
+    end
+  end
+end

data/lib/redhound/capture/linux/constants.rb

@@ -0,0 +1,37 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Linux
+      # @api private
+      module Constants
+        AF_PACKET = 17
+        SOL_PACKET = 263
+        ETH_P_ALL = 3
+        PACKET_ADD_MEMBERSHIP = 1
+        PACKET_RX_RING = 5
+        PACKET_STATISTICS = 6
+        PACKET_VERSION = 10
+        PACKET_IGNORE_OUTGOING = 23
+        PACKET_MR_PROMISC = 1
+        PACKET_OUTGOING = 4
+        SO_ATTACH_FILTER = 26
+        SO_RCVBUFFORCE = 33
+        TPACKET_V3 = 2
+        SIOCGSTAMPNS = 0x8907
+        SIOCGIFHWADDR = 0x8927
+        SIOCGIFMTU = 0x8921
+        SIOCGIFFLAGS = 0x8913
+        TP_STATUS_USER = 0x01
+        TP_STATUS_CSUMNOTREADY = 0x08
+        TP_STATUS_VLAN_VALID = 0x10
+        TP_STATUS_VLAN_TPID_VALID = 0x40
+        TP_STATUS_CSUM_VALID = 0x80
+        RECEIVE_SIZE = 262_144
+      end
+    end
+  end
+end