redhound 1.0.1 → 2.0.0.rc2

data/lib/redhound/writer.rb

@@ -2,52 +2,34 @@
 # frozen_string_literal: true
 
 module Redhound
+  # Open pcap/pcapng outputs, optionally with bounded rotation.
   class Writer
-    # @rbs (filename: String) -> void
-    def initialize(filename:)
-      @filename = filename
-    end
-
-    # @rbs () -> void
-    def start
-      @file = File.open(@filename, 'wb')
-      @file.write(file_header)
-    end
-
-    # @rbs (msg: String) -> void
-    def write(msg:)
-      @file.write(packet_record(Time.now, msg.bytesize, msg.bytesize))
-      @file.write(msg)
-    end
+    # @rbs (untyped output, ?linktype: Integer | Symbol | String, ?format: Symbol | String | nil, ?snaplen: Integer, ?precision: Symbol, ?packet_buffered: bool, ?forbidden_input: String?, **untyped options) -> untyped
+    # @rbs [T] (untyped output, ?linktype: Integer | Symbol | String, ?format: Symbol | String | nil, ?snaplen: Integer, ?precision: Symbol, ?packet_buffered: bool, ?forbidden_input: String?, **untyped options) { (untyped) -> T } -> T
+    # Open a path or binary IO; close automatically with a block. See docs/API.md for options.
+    def self.open(output, linktype: :ethernet, format: nil, snaplen: 262_144, precision: :nano, packet_buffered: false, forbidden_input: nil, **options)
+      if forbidden_input && forbidden_input != '-' && output.is_a?(String) && output != '-'
+        same_path = ::File.expand_path(forbidden_input) == ::File.expand_path(output)
+        same_file = ::File.exist?(forbidden_input) && ::File.exist?(output) && ::File.identical?(forbidden_input, output)
+        raise ConfigurationError, 'input and output must be different files' if same_path || same_file
+      end
+      format ||= output.is_a?(String) && ::File.extname(output) == '.pcapng' ? :pcapng : :pcap
+      raise ArgumentError, "unknown capture file format: #{format}" unless %i[pcap pcapng].include?(format.to_sym)
 
-    # @rbs () -> void
-    def stop
-      @file.close
-    end
-
-    private
-
-    # @rbs () -> String
-    def file_header
-      [
-        0xa1b2c3d4, # Magic Number (little-endian)
-        2,          # Version Major
-        4,          # Version Minor
-        0,          # Timezone offset (GMT)
-        0,          # Timestamp accuracy
-        65535,      # Snapshot length
-        1           # Link-layer header type (Ethernet)
-      ].pack('VvvVVVV')
-    end
+      options = options.merge(linktype:, format:, snaplen:, precision:, packet_buffered:, forbidden_input:)
+      writer = if options[:max_bytes] || options[:interval]
+                 File::RotatingWriter.new(output, **options)
+               else
+                 klass = format.to_sym == :pcapng ? File::PcapngWriter : File::PcapWriter
+                 klass.new(output, **options)
+               end
+      return writer unless block_given?
 
-    # @rbs (Time timestamp, Integer captured_length, Integer original_length) -> String
-    def packet_record(timestamp, captured_length, original_length)
-      [
-        timestamp.to_i,           # Timestamp seconds
-        timestamp.usec || 0,      # Timestamp microseconds
-        captured_length,          # Captured packet length
-        original_length           # Original packet length
-      ].pack('VVVV')
+      begin
+        yield writer
+      ensure
+        writer.close
+      end
     end
   end
 end

data/lib/redhound.rb

@@ -1,13 +1,85 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
-require_relative 'redhound/analyzer'
-require_relative 'redhound/builder'
-require_relative 'redhound/command'
-require_relative 'redhound/l2'
-require_relative 'redhound/l3'
-require_relative 'redhound/l4'
-require_relative 'redhound/receiver'
-require_relative 'redhound/resolver'
-require_relative 'redhound/source'
 require_relative 'redhound/version'
+
+require_relative 'redhound/errors'
+require_relative 'redhound/cursor'
+require_relative 'redhound/diagnostic'
+require_relative 'redhound/field'
+require_relative 'redhound/layer'
+require_relative 'redhound/registry'
+require_relative 'redhound/dissector'
+require_relative 'redhound/stream_dissector'
+require_relative 'redhound/context'
+require_relative 'redhound/engine'
+require_relative 'redhound/capture/linktype'
+require_relative 'redhound/packet'
+require_relative 'redhound/protocols/checksum'
+require_relative 'redhound/protocols/data'
+require_relative 'redhound/protocols/ethernet'
+require_relative 'redhound/protocols/vlan'
+require_relative 'redhound/protocols/llc'
+require_relative 'redhound/protocols/link'
+require_relative 'redhound/protocols/arp'
+require_relative 'redhound/protocols/ipv4'
+require_relative 'redhound/protocols/ipv6'
+require_relative 'redhound/protocols/udp'
+require_relative 'redhound/protocols/tcp'
+require_relative 'redhound/protocols/icmp'
+require_relative 'redhound/protocols/tunnel'
+require_relative 'redhound/protocols/dns'
+require_relative 'redhound/protocols/dhcp'
+require_relative 'redhound/protocols/ntp'
+require_relative 'redhound/protocols/http'
+require_relative 'redhound/protocols/tls'
+require_relative 'redhound/output/timestamp'
+require_relative 'redhound/output/summary'
+require_relative 'redhound/output/tree'
+require_relative 'redhound/output/hexdump'
+require_relative 'redhound/output/json'
+require_relative 'redhound/output/fields'
+require_relative 'redhound/filter'
+require_relative 'redhound/capture'
 require_relative 'redhound/writer'
+require_relative 'redhound/analysis'
+require_relative 'redhound/cli/options'
+require_relative 'redhound/cli/privileges'
+require_relative 'redhound/cli/runner'
+require_relative 'redhound/cli/command'
+
+# Capture, inspect and save network packets using Ruby standard libraries.
+module Redhound
+  # @rbs (String bytes, ?linktype: (Integer | Symbol), **untyped metadata) -> Packet
+  # Create a packet with lazy, bounded protocol dissection. See docs/API.md.
+  def self.dissect(bytes, linktype: :ethernet, **metadata)
+    Packet.new(bytes, linktype: linktype, **metadata)
+  end
+
+  # @rbs (untyped input, ?filter: String?) -> Reader
+  # @rbs [T] (untyped input, ?filter: String?) { (Reader) -> T } -> T
+  # Read a pcap/pcapng path or binary IO; a block closes the reader automatically.
+  def self.open(input, filter: nil)
+    reader = Reader.new(input, filter: filter)
+    return reader unless block_given?
+    begin
+      yield reader
+    ensure
+      reader.close
+    end
+  end
+
+  # @rbs (interface: String | Integer, ?count: Integer?, **untyped options) { (Packet) -> void } -> void
+  # Yield live packets until count is reached or capture stops; always close the source.
+  def self.capture(interface:, count: nil, **options)
+    raise ConfigurationError, 'count must be positive' if count && count <= 0
+    Capture.open(interface: interface, **options) do |source|
+      captured = 0
+      source.each_packet do |packet|
+        yield packet
+        captured += 1
+        break if count && captured >= count
+      end
+    end
+  end
+end

data/sig/generated/redhound/analysis/flow_key.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/redhound/analysis/flow_key.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module FlowKey
+      # @rbs (Packet packet, ?Symbol? type) -> untyped
+      def self.from: (Packet packet, ?Symbol? type) -> untyped
+
+      # @rbs (Symbol proto, untyped src, untyped dst) -> untyped
+      def self.normalize: (Symbol proto, untyped src, untyped dst) -> untyped
+    end
+  end
+end

data/sig/generated/redhound/analysis/flow_table.rbs

@@ -0,0 +1,102 @@
+# Generated from lib/redhound/analysis/flow_table.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class Flow
+      BASE_BYTES: ::Integer
+
+      attr_reader key: untyped
+
+      attr_reader id: untyped
+
+      attr_reader first_ns: untyped
+
+      attr_reader packets: untyped
+
+      attr_reader bytes: untyped
+
+      attr_reader streams: untyped
+
+      attr_reader applications: untyped
+
+      attr_reader acks: untyped
+
+      attr_reader keep_alives: untyped
+
+      attr_reader http_methods: untyped
+
+      attr_reader probes: untyped
+
+      attr_reader probe_disabled: untyped
+
+      attr_accessor last_ns: untyped
+
+      attr_accessor closed_ns: untyped
+
+      attr_accessor syn_ns: untyped
+
+      attr_accessor syn_direction: untyped
+
+      attr_accessor synack_ns: untyped
+
+      attr_accessor synack_seq: untyped
+
+      attr_accessor initial_rtt: untyped
+
+      attr_accessor accounted_bytes: untyped
+
+      # @rbs (untyped key, Integer id, Integer timestamp_ns) -> void
+      def initialize: (untyped key, Integer id, Integer timestamp_ns) -> void
+
+      # @rbs () -> bool
+      def closed?: () -> bool
+
+      # @rbs () -> Integer
+      def bytesize: () -> Integer
+    end
+
+    # @api private
+    class FlowTable
+      attr_reader evicted: untyped
+
+      attr_reader expired: untyped
+
+      attr_accessor on_remove: untyped
+
+      # @rbs (?max_flows: Integer) -> void
+      def initialize: (?max_flows: Integer) -> void
+
+      # @rbs (Packet packet) -> untyped
+      def update: (Packet packet) -> untyped
+
+      # @rbs (Integer now_ns) -> void
+      def advance: (Integer now_ns) -> void
+
+      # @rbs (Integer now_ns) -> void
+      def expire: (Integer now_ns) -> void
+
+      # @rbs (?Symbol? type) -> Flow?
+      def evict: (?Symbol? type) -> Flow?
+
+      # @rbs (Flow flow) -> void
+      def discard: (Flow flow) -> void
+
+      # @rbs (Flow flow) -> void
+      def account: (Flow flow) -> void
+
+      # @rbs () -> Integer
+      def size: () -> Integer
+
+      # @rbs () -> Array[Flow]
+      def values: () -> Array[Flow]
+
+      # @rbs () -> Integer
+      def bytesize: () -> Integer
+
+      # @rbs () -> Integer
+      def tcp_bytesize: () -> Integer
+    end
+  end
+end

data/sig/generated/redhound/analysis/ip_reassembler.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/redhound/analysis/ip_reassembler.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class IpReassembler
+      attr_reader evicted: untyped
+
+      attr_reader expired: untyped
+
+      # @rbs (?max_bytes: Integer, ?timeout_ns: Integer) -> void
+      def initialize: (?max_bytes: Integer, ?timeout_ns: Integer) -> void
+
+      # @rbs (Packet packet) -> untyped
+      def descriptor: (Packet packet) -> untyped
+
+      # @rbs (Packet packet) -> Packet?
+      def update: (Packet packet) -> Packet?
+
+      # @rbs (untyped state) -> bool
+      def complete?: (untyped state) -> bool
+
+      # @rbs (Packet packet, untyped state, Integer version) -> Packet?
+      def virtual_packet: (Packet packet, untyped state, Integer version) -> Packet?
+
+      # @rbs (Integer now_ns) -> void
+      def advance: (Integer now_ns) -> void
+
+      # @rbs (Integer now_ns) -> void
+      def expire: (Integer now_ns) -> void
+
+      # @rbs () -> Integer
+      def bytesize: () -> Integer
+
+      # @rbs (untyped state) -> Integer
+      def state_bytesize: (untyped state) -> Integer
+
+      # @rbs (untyped key) -> untyped
+      def remove: (untyped key) -> untyped
+
+      # @rbs () -> untyped
+      def remove_oldest: () -> untyped
+
+      # @rbs () -> Integer
+      def finish: () -> Integer
+
+      # @rbs () -> Integer
+      def size: () -> Integer
+    end
+  end
+end

data/sig/generated/redhound/analysis/stats.rbs

@@ -0,0 +1,80 @@
+# Generated from lib/redhound/analysis/stats.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module Stats
+      # @api private
+      class Table
+        attr_reader evicted: untyped
+
+        # @rbs (?max_rows: Integer) -> void
+        def initialize: (?max_rows: Integer) -> void
+
+        # @rbs (untyped key) { () -> untyped } -> untyped
+        def row: (untyped key) { () -> untyped } -> untyped
+
+        # @rbs () -> Integer
+        def bytesize: () -> Integer
+
+        # @rbs () -> void
+        def evict: () -> void
+
+        # @rbs (untyped io) -> void
+        def format: (untyped io) -> void
+
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+
+      # @api private
+      class Io < Table
+        # @rbs ((Integer | Float) seconds, ?max_rows: Integer) -> void
+        def initialize: (Integer | Float seconds, ?max_rows: Integer) -> void
+
+        # @rbs (Packet packet) -> void
+        def update: (Packet packet) -> void
+
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+
+        # @rbs (Integer interval) -> Hash[Symbol, Integer]
+        def interval_row: (Integer interval) -> Hash[Symbol, Integer]
+      end
+
+      # @api private
+      class Conversations < Table
+        # @rbs (Symbol type, ?max_rows: Integer) -> void
+        def initialize: (Symbol type, ?max_rows: Integer) -> void
+
+        # @rbs (Packet packet) -> void
+        def update: (Packet packet) -> void
+
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+
+      # @api private
+      class Endpoints < Table
+        # @rbs (Symbol type, ?max_rows: Integer) -> void
+        def initialize: (Symbol type, ?max_rows: Integer) -> void
+
+        # @rbs (Packet packet) -> void
+        def update: (Packet packet) -> void
+
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+
+      # @api private
+      class Hierarchy < Table
+        # @rbs (Packet packet) -> void
+        def update: (Packet packet) -> void
+
+        # @rbs () -> Hash[Symbol, untyped]
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+    end
+  end
+end

data/sig/generated/redhound/analysis/tcp_analysis.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/redhound/analysis/tcp_analysis.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    module TcpAnalysis
+      # @rbs (Flow flow, Integer direction, TcpStream stream, Layer layer, Integer timestamp_ns) -> void
+      def self.update: (Flow flow, Integer direction, TcpStream stream, Layer layer, Integer timestamp_ns) -> void
+
+      # @rbs (Layer layer, Symbol name) -> void
+      def self.flag: (Layer layer, Symbol name) -> void
+    end
+  end
+end

data/sig/generated/redhound/analysis/tcp_reassembler.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/redhound/analysis/tcp_reassembler.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class TcpReassembler
+      # @rbs (?registry: Registry, ?max_bytes: Integer, ?stream_bytes: Integer, ?protocol_streams: bool, ?follow: untyped) -> void
+      def initialize: (?registry: Registry, ?max_bytes: Integer, ?stream_bytes: Integer, ?protocol_streams: bool, ?follow: untyped) -> void
+
+      # @rbs (Packet packet, Flow flow, Integer direction) -> void
+      def update: (Packet packet, Flow flow, Integer direction) -> void
+
+      # @rbs (Flow flow, Integer direction, TcpStream stream, untyped application, Packet? packet) -> Array[Layer]
+      def deliver: (Flow flow, Integer direction, TcpStream stream, untyped application, Packet? packet) -> Array[Layer]
+
+      # @rbs (Flow flow, Integer direction, String data, Integer origin, Packet? packet) -> Array[Layer]
+      def application_data: (Flow flow, Integer direction, String data, Integer origin, Packet? packet) -> Array[Layer]
+
+      # @rbs (untyped klass, Flow flow, Integer direction, Layer layer) -> untyped
+      def create_application: (untyped klass, Flow flow, Integer direction, Layer layer) -> untyped
+
+      # @rbs (Flow flow, Integer direction, untyped application, Symbol method, *untyped arguments) -> Array[Layer]
+      def invoke: (Flow flow, Integer direction, untyped application, Symbol method, *untyped arguments) -> Array[Layer]
+
+      # @rbs (Flow flow, Integer direction, Symbol protocol, StandardError error) -> Layer
+      def application_error: (Flow flow, Integer direction, Symbol protocol, StandardError error) -> Layer
+
+      # @rbs (Packet packet, Array[Layer] layers) -> void
+      def attach: (Packet packet, Array[Layer] layers) -> void
+
+      # @rbs (Flow flow, ?Packet? packet) -> Array[Layer]
+      def finish_flow: (Flow flow, ?Packet? packet) -> Array[Layer]
+
+      # @rbs (FlowTable flows, Packet packet) -> void
+      def enforce_limit: (FlowTable flows, Packet packet) -> void
+    end
+  end
+end

data/sig/generated/redhound/analysis/tcp_stream.rbs

@@ -0,0 +1,60 @@
+# Generated from lib/redhound/analysis/tcp_stream.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class TcpStream
+      attr_reader base_seq: untyped
+
+      attr_reader expected: untyped
+
+      attr_reader diagnostics: untyped
+
+      attr_reader deliveries: untyped
+
+      attr_reader gap_lengths: untyped
+
+      attr_reader fin: untyped
+
+      # @rbs (?max_bytes: Integer) -> void
+      def initialize: (?max_bytes: Integer) -> void
+
+      # @rbs (Integer sequence, String data, ?syn: bool, ?fin: bool, ?frame: Integer) -> Array[String]
+      def push: (Integer sequence, String data, ?syn: bool, ?fin: bool, ?frame: Integer) -> Array[String]
+
+      # @rbs (Integer start, String data, Integer old_start, String old_data) -> void
+      def compare_overlap: (Integer start, String data, Integer old_start, String old_data) -> void
+
+      # @rbs () -> void
+      def drain: () -> void
+
+      # @rbs (?bool clear) -> Array[String]
+      def flush_gap: (?bool clear) -> Array[String]
+
+      # @rbs () -> void
+      def trim_history: () -> void
+
+      # @rbs () -> Integer
+      def bytesize: () -> Integer
+
+      # @rbs () -> bool
+      def pending?: () -> bool
+
+      # @rbs () -> bool
+      def fin_seen?: () -> bool
+
+      # @rbs () -> void
+      def consume_fin: () -> void
+
+      # @rbs () -> Integer
+      def next_sequence: () -> Integer
+
+      # @rbs () -> void
+      def clear_deliveries: () -> void
+
+      # @rbs () -> void
+      def release: () -> void
+    end
+  end
+end

data/sig/generated/redhound/analysis.rbs

@@ -0,0 +1,38 @@
+# Generated from lib/redhound/analysis.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Analysis
+    # @api private
+    class Session
+      attr_reader flows: untyped
+
+      attr_reader ip_reassembler: untyped
+
+      attr_reader tcp_reassembler: untyped
+
+      attr_reader statistics: untyped
+
+      # @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: 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
+
+      # @rbs (String specification, Integer max_rows) -> untyped
+      def statistic: (String specification, Integer max_rows) -> untyped
+
+      # @rbs (Packet packet) -> void
+      def update: (Packet packet) -> void
+
+      # @rbs (Packet packet) -> void
+      def enforce_limit: (Packet packet) -> void
+
+      # @rbs () -> Integer
+      def bytesize: () -> Integer
+
+      # @rbs (untyped err) -> void
+      def snapshot: (untyped err) -> void
+
+      # @rbs (untyped out, untyped err) -> void
+      def finish: (untyped out, untyped err) -> void
+    end
+  end
+end

data/sig/generated/redhound/capture/bsd/bpf_device.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/redhound/capture/bsd/bpf_device.rb with RBS::Inline
+
+module Redhound
+  # @api private
+  module Capture
+    # @api private
+    module Bsd
+      # @api private
+      class BpfDevice < Source
+        attr_reader linktype: untyped
+
+        attr_reader interfaces: untyped
+
+        # @rbs (interface: String | Integer | Interface, ?snaplen: Integer, ?promiscuous: bool, ?buffer_size: Integer?, ?direction: Symbol, ?filter: String?) -> void
+        def initialize: (interface: String | Integer | Interface, ?snaplen: Integer, ?promiscuous: bool, ?buffer_size: Integer?, ?direction: Symbol, ?filter: String?) -> void
+
+        # @rbs (?timeout: Numeric?) -> Packet?
+        def next_packet: (?timeout: Numeric?) -> Packet?
+
+        # @rbs (untyped program) -> void
+        def attach_filter: (untyped program) -> void
+
+        # @rbs () -> Stats
+        def stats: () -> Stats
+
+        # @rbs () -> void
+        def close: () -> void
+
+        private
+
+        # @rbs () -> ::File
+        def open_device: () -> ::File
+
+        # @rbs () -> void
+        def configure_direction: () -> void
+      end
+    end
+  end
+end

data/sig/generated/redhound/capture/bsd/constants.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/redhound/capture/bsd/constants.rb with RBS::Inline
+
+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: ::Integer
+
+        BIOCGBLEN: ::Integer
+
+        BIOCSETF: ::Integer
+
+        BIOCFLUSH: ::Integer
+
+        BIOCPROMISC: ::Integer
+
+        BIOCGDLT: ::Integer
+
+        BIOCSETIF: ::Integer
+
+        BIOCGSTATS: ::Integer
+
+        BIOCIMMEDIATE: ::Integer
+
+        BIOCSSEESENT: ::Integer
+
+        # Apple XNU bsd/net/bpf_private.h: extended headers expose direction at byte 19.
+        BIOCSEXTHDR: ::Integer
+
+        BIOCSDIRECTION: ::Integer
+
+        BPF_ALIGNMENT: ::Integer
+      end
+    end
+  end
+end

data/sig/generated/redhound/capture/bsd/ifreq.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/redhound/capture/bsd/ifreq.rb with RBS::Inline
+
+module Redhound
+  module Capture
+    module Bsd
+      # macOS interface metadata can be queried without opening a BPF device.
+      module Ifreq
+        SIOCGIFMTU: ::Integer
+
+        # @rbs (String name, index: Integer, flags: Integer, link_address: String?) -> Interface
+        def self.interface: (String name, index: Integer, flags: Integer, link_address: String?) -> Interface
+      end
+    end
+  end
+end