redhound 1.0.1 → 2.0.0.rc2

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

@@ -0,0 +1,155 @@
+# 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)
+          polled = false
+          until @stopped || @closed
+            return nil if polled && deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            polled = true
+            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/bsd/ifreq.rb

@@ -0,0 +1,41 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  module Capture
+    module Bsd
+      # macOS interface metadata can be queried without opening a BPF device.
+      module Ifreq
+        SIOCGIFMTU = 0xc0206933 # Verified against sys/sockio.h; sizeof(ifreq) is 32.
+
+        # @rbs (String name, index: Integer, flags: Integer, link_address: String?) -> Interface
+        def self.interface(name, index:, flags:, link_address:)
+          raise ArgumentError, 'invalid interface name' if name.bytesize >= 16 || name.include?("\0")
+
+          socket = ::Socket.new(::Socket::AF_INET, ::Socket::SOCK_DGRAM, 0)
+          bytes = [name].pack('a16') + "\0" * 16
+          begin
+            socket.ioctl(SIOCGIFMTU, bytes)
+          ensure
+            socket.close
+          end
+          mtu = bytes.unpack1('i', offset: 16) #: Integer
+          mac = nil # @rbs String?
+          if link_address && link_address.bytesize >= 8
+            name_length = link_address.getbyte(5) #: Integer
+            address_length = link_address.getbyte(6) #: Integer
+            if address_length == 6 && link_address.bytesize >= 8 + name_length + address_length
+              mac_bytes = link_address.byteslice(8 + name_length, address_length) #: String
+              mac_values = mac_bytes.unpack('C6') #: Array[Integer]
+              mac = mac_values.map { |value| format('%02x', value) }.join(':')
+            end
+          end
+          linktype = (flags & 8).positive? || name.start_with?('utun') ? 0 : 1
+          Interface.new(name:, index:, flags:, mtu:, mac:, linktype:)
+        rescue Errno::ENXIO, Errno::ENODEV
+          raise InterfaceNotFound, "interface #{name.inspect} not found"
+        end
+      end
+    end
+  end
+end

data/lib/redhound/capture/file_source.rb

@@ -0,0 +1,214 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    class FileSource < Source
+      class ReadStopped < StandardError; end
+
+      # @api private
+      class FileInput
+        # @rbs (::File io) -> void
+        def initialize(io)
+          @io, @buffer, @offset = io, ''.b, 0
+        end
+
+        # @rbs (Integer length) -> String?
+        def read(length)
+          ending = @offset + length
+          if ending <= @buffer.bytesize
+            result = @buffer.byteslice(@offset, length)
+            @offset = ending
+            return result
+          end
+          result = @buffer.byteslice(@offset..) || ''.b
+          while result.bytesize < length
+            begin
+              @buffer = @io.readpartial(65_536)
+            rescue EOFError
+              @buffer, @offset = ''.b, 0
+              return result.empty? ? nil : result
+            end
+            amount = [length - result.bytesize, @buffer.bytesize].min #: Integer
+            result << @buffer.byteslice(0, amount)
+            @offset = amount
+          end
+          result
+        end
+      end
+      private_constant :FileInput
+
+      # Nonregular inputs need bounded polling so Source#stop can interrupt an idle pipe.
+      class StreamInput
+        # @rbs (IO io, Source source) -> void
+        def initialize(io, source)
+          @io, @source = io, source
+        end
+
+        # @rbs (Integer length) -> String?
+        def read(length)
+          loop do
+            raise ReadStopped if @source.stopped?
+            next unless IO.select([@io], nil, nil, 0.1)
+
+            part = @io.read_nonblock(length, exception: false)
+            next if part == :wait_readable
+
+            return part
+          end
+        end
+      end
+
+      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)
+        regular = @io.is_a?(IO) && @io.stat.file?
+        reader_io = if @owned && regular
+                      FileInput.new(@io)
+                    elsif @io.is_a?(IO) && !regular
+                      StreamInput.new(@io, self)
+                    else
+                      @io
+                    end
+        @stream = reader_io.is_a?(StreamInput)
+        @packets = nil # @rbs Thread::SizedQueue[Packet | StandardError]?
+        @reader_thread = nil # @rbs Thread?
+        magic = File::Format.read_exact(reader_io, 4)
+        @reader = if magic == File::Format::PCAPNG_MAGIC
+                    File::PcapngReader.new(reader_io, magic)
+                  elsif File::Format::PCAP_MAGICS.key?(magic)
+                    File::PcapReader.new(reader_io, magic)
+                  else
+                    raise FileFormatError, 'unrecognized capture file magic'
+                  end
+        @filter_expression = filter
+        @filter_program = nil # @rbs Filter::Program?
+        @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
+
+        deadline = deadline_for(timeout)
+        polled = false
+        until @stopped || @closed
+          return nil if polled && deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          polled = true
+          remaining = deadline && [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
+          packet = read_packet(remaining)
+          return nil if packet == :wait_readable
+          break unless packet
+
+          @capture_stats.received += 1
+          next if @filter_program && !@filter_program.match?(packet)
+          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
+      rescue ReadStopped
+        nil
+      end
+
+      # @rbs (Filter::Program? program) -> void
+      def attach_filter(program)
+        @filter_expression = nil
+        @filters.clear
+        @filter_program = program
+      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 stop
+        super
+        @packets&.close
+      end
+
+      # @rbs () -> void
+      def close
+        return if @closed
+
+        super
+        @reader_thread&.join(0.2)
+        @io.close if @owned
+      end
+
+      private
+
+      # A single bounded worker preserves partial records across caller timeouts.
+      # @rbs (Numeric? timeout) -> (Packet | nil | :wait_readable)
+      def read_packet(timeout)
+        return @reader.next_packet unless @stream
+
+        unless @packets
+          queue = Thread::SizedQueue.new(1) #: Thread::SizedQueue[Packet | StandardError]
+          @packets = queue
+          @reader_thread = Thread.new do
+            begin
+              while !stopped? && (packet = @reader.next_packet)
+                queue << packet
+              end
+            rescue ReadStopped, ClosedQueueError
+              nil
+            rescue StandardError => error
+              begin
+                queue << error
+              rescue ClosedQueueError
+                nil
+              end
+            ensure
+              queue.close
+            end
+          end
+        end
+        queue = @packets #: Thread::SizedQueue[Packet | StandardError]
+        result = queue.pop(timeout: timeout && Float(timeout))
+        raise result if result.is_a?(StandardError)
+
+        return result if result
+        return nil if queue.closed?
+
+        :wait_readable
+      end
+    end
+  end
+end

data/lib/redhound/capture/interface.rb

@@ -0,0 +1,70 @@
+# 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
+        addresses = Socket.getifaddrs
+        addresses.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:)
+          elsif RUBY_PLATFORM.include?('darwin')
+            link = addresses.find { |entry| entry.name == address.name && entry.addr&.afamily == 18 }
+            Bsd::Ifreq.interface(address.name, index:, flags: address.flags, link_address: link&.addr&.to_sockaddr)
+          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

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

@@ -0,0 +1,18 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Linux
+      # @api private
+      module Cooked
+        # @rbs (SockaddrLL address) -> String
+        def self.header(address)
+          [address.protocol, 0, address.index, address.hatype, address.pkttype, address.address.bytesize, address.address].pack('n n N n C C a8')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Linux
+      # @api private
+      module Ifreq
+        # @rbs (String name, Integer command) -> String
+        def self.query(name, command)
+          raise ArgumentError, 'invalid interface name' if name.bytesize >= 16 || name.include?("\0")
+
+          socket = ::Socket.new(::Socket::AF_INET, ::Socket::SOCK_DGRAM, 0)
+          bytes = [name].pack('a16') + "\0" * 24
+          begin
+            socket.ioctl(command, bytes)
+            bytes
+          ensure
+            socket.close
+          end
+        end
+
+        # @rbs (String name, ?index: Integer) -> Interface
+        def self.interface(name, index: 0)
+          hardware = query(name, Constants::SIOCGIFHWADDR)
+          hatype = hardware.unpack1('S', offset: 16) #: Integer
+          mac_bytes = hardware.byteslice(18, 6) #: String
+          mac_values = mac_bytes.unpack('C6') #: Array[Integer]
+          mac = mac_values.map { |value| format('%02x', value) }.join(':')
+          flags = query(name, Constants::SIOCGIFFLAGS).unpack1('S', offset: 16) #: Integer
+          mtu = query(name, Constants::SIOCGIFMTU).unpack1('i', offset: 16) #: Integer
+          Interface.new(name:, index:, linktype: Linktype.for_hardware(hatype), flags:, mtu:, mac:,
+                        meta: { hardware_type: hatype })
+        rescue Errno::ENODEV, Errno::ENXIO
+          raise InterfaceNotFound, "interface #{name.inspect} not found"
+        end
+      end
+    end
+  end
+end