tracepath 0.1.0

data/lib/tracepath/options.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Tracepath
+  class Options
+    DEFAULTS = {
+      protocol: :udp, family: :auto, first_ttl: 1, max_hops: 30, probes: 3,
+      max_inflight: 3, timeout: 3.0, max_duration: 120.0, dns_timeout: 3.0,
+      reverse_dns: false, ptr_timeout: 1.0, send_interval: 0.05, port: nil,
+      source: nil, interface: nil, traffic_class: 0, packet_size: nil, dont_fragment: false
+    }.freeze
+    attr_reader(*DEFAULTS.keys)
+
+    def initialize(**options)
+      unknown = options.keys - DEFAULTS.keys
+      raise ArgumentError, "unknown options: #{unknown.join(', ')}" unless unknown.empty?
+      values = DEFAULTS.merge(options)
+      DEFAULTS.each_key { |key| instance_variable_set("@#{key}", Values.copy(values[key])) }
+      validate!
+      @port ||= protocol == :tcp ? 443 : (protocol == :udp ? 33_434 : nil)
+      if protocol == :udp && @port + (max_hops - first_ttl + 1) * probes - 1 > 65_535
+        raise ArgumentError, "UDP probe ports would exceed 65535"
+      end
+      freeze
+    end
+
+    def to_h = DEFAULTS.keys.to_h { |key| [key, public_send(key)] }
+
+    private
+
+    def validate!
+      raise ArgumentError, "protocol must be udp, icmp, or tcp" unless %i[udp icmp tcp].include?(protocol)
+      raise ArgumentError, "family must be auto, ipv4, or ipv6" unless %i[auto ipv4 ipv6].include?(family)
+      { first_ttl: 1..255, max_hops: 1..255, probes: 1..255, max_inflight: 1..255,
+        traffic_class: 0..255 }.each do |key, range|
+        value = public_send(key)
+        raise ArgumentError, "#{key} must be an integer in #{range}" unless value.is_a?(Integer) && range.cover?(value)
+      end
+      raise ArgumentError, "first_ttl must not exceed max_hops" if first_ttl > max_hops
+      %i[timeout max_duration dns_timeout ptr_timeout send_interval].each do |key|
+        value = public_send(key)
+        valid = value.is_a?(Numeric) && value.real? && value.finite? && (key == :send_interval ? value >= 0 : value > 0)
+        raise ArgumentError, "#{key} must be a finite #{key == :send_interval ? 'nonnegative' : 'positive'} number" unless valid
+      end
+      %i[reverse_dns dont_fragment].each do |key|
+        raise ArgumentError, "#{key} must be true or false" unless [true, false].include?(public_send(key))
+      end
+      if !port.nil? && (!port.is_a?(Integer) || !(1..65_535).cover?(port))
+        raise ArgumentError, "port must be an integer in 1..65535"
+      end
+      raise ArgumentError, "port does not apply to ICMP" if protocol == :icmp && port
+      if !packet_size.nil? && (!packet_size.is_a?(Integer) || !(28..65_535).cover?(packet_size))
+        raise ArgumentError, "packet_size must be an integer in 28..65535"
+      end
+      minimum_size = (family == :ipv6 ? 40 : 20) + (protocol == :tcp ? 20 : 8)
+      if packet_size && packet_size < minimum_size
+        raise ArgumentError, "packet_size must be at least #{minimum_size} for the selected protocol and family"
+      end
+      raise ArgumentError, "dont_fragment only applies to IPv4" if family == :ipv6 && dont_fragment
+      if !interface.nil? && (!interface.is_a?(String) || interface.empty? || interface.include?("\0"))
+        raise ArgumentError, "interface must be a nonempty interface name"
+      end
+      return if source.nil?
+      raise ArgumentError, "source must be a numeric local address" unless source.is_a?(String)
+      address = IPAddr.new(source.split("%", 2).first)
+      if (family == :ipv4 && !address.ipv4?) || (family == :ipv6 && !address.ipv6?)
+        raise ArgumentError, "source and family disagree"
+      end
+    rescue IPAddr::InvalidAddressError
+      raise ArgumentError, "source must be a numeric local address"
+    end
+  end
+
+  class Request
+    attr_reader :target, :options
+
+    def initialize(target, **options)
+      unless target.is_a?(String) && !target.empty? && !target.match?(/[\s\x00]/)
+        raise ArgumentError, "target must be a nonempty hostname or numeric address without whitespace"
+      end
+      unknown = options.keys - Options::DEFAULTS.keys
+      raise ArgumentError, "unknown options: #{unknown.join(', ')}" unless unknown.empty?
+      @target = target.dup.freeze
+      @options = Values.copy(options)
+      freeze
+    end
+  end
+end

data/lib/tracepath/packet.rb

@@ -0,0 +1,433 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+
+module Tracepath
+  # Wire codecs and response correlation. All decoders treat received bytes as
+  # untrusted input and return nil for unsupported or incomplete packets.
+  module Packet
+    MAX_PACKET_SIZE = 65_575
+    MAX_EXTENSION_HEADERS = 16
+    VLAN_TYPES = [0x8100, 0x88a8, 0x9100].freeze
+    ICMP_ERROR_KINDS = %i[time_exceeded unreachable packet_too_big parameter_problem].freeze
+
+    class << self
+      # ICMPv6 raw sockets calculate the checksum using the selected source IP.
+      def icmp_echo(family:, identifier:, sequence:, payload: '')
+        validate_family!(family)
+        validate_uint!(identifier, 16, 'identifier')
+        validate_uint!(sequence, 16, 'sequence')
+        validate_payload!(payload, family == :ipv4 ? 65_507 : 65_527)
+
+        packet = [family == :ipv4 ? 8 : 128, 0, 0, identifier, sequence].pack('CCnnn') + payload.b
+        packet[2, 2] = [checksum(packet)].pack('n') if family == :ipv4
+        packet
+      end
+
+      # Returns a TCP segment; the socket supplies the IP header.
+      def tcp_syn(family:, source:, destination:, source_port:, destination_port:, sequence:, payload: '')
+        validate_family!(family)
+        validate_uint!(source_port, 16, 'source_port')
+        validate_uint!(destination_port, 16, 'destination_port')
+        validate_uint!(sequence, 32, 'sequence')
+        validate_payload!(payload, family == :ipv4 ? 65_495 : 65_515)
+
+        packet = [source_port, destination_port, sequence, 0, 0x50, 0x02, 65_535, 0, 0].pack('nnNNCCnnn') + payload.b
+        header = pseudoheader(family, source, destination, 6, packet.bytesize)
+        packet[16, 2] = [checksum(header + packet)].pack('n')
+        packet
+      end
+
+      # raw IPv6 sockets omit the IP header. In that case the caller supplies
+      # the recvmsg peer and local destination, and the socket's protocol.
+      # checksum_offloaded is exclusively for trusted receive metadata (for
+      # example Linux PACKET_AUXDATA), never inferred from packet contents.
+      # local_capture is a transport-verified loopback capture taken before
+      # checksum finalization; it cannot establish checksum validity.
+      def decode(data, family:, source: nil, destination: nil, ip_header: true, protocol: :icmp, checksum_offloaded: false, local_capture: false)
+        return unless data.is_a?(String) && data.bytesize <= MAX_PACKET_SIZE
+        return unless %i[ipv4 ipv6].include?(family)
+
+        data = data.b
+        if ip_header
+          envelope = decode_ip(data, family: family, local_capture: local_capture)
+          return unless envelope
+
+          source = envelope[:source]
+          destination = envelope[:destination]
+          number = envelope[:number]
+          payload = envelope[:payload]
+        else
+          return unless address_family?(source, family) && address_family?(destination, family)
+
+          source = address(source).to_s
+          destination = address(destination).to_s
+          number = protocol_number(protocol, family)
+          payload = data
+        end
+
+        reply = { family: family, source: source, destination: destination }
+        case number
+        when family == :ipv4 ? 1 : 58
+          decode_icmp(payload, reply)
+        when 6
+          decode_tcp(payload, reply, checksum_offloaded: checksum_offloaded, local_capture: local_capture)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # DLT values come from pcap_datalink, not the host's socket AF constants.
+      def decode_link(data, datalink:, local_capture: false)
+        return unless data.is_a?(String) && data.bytesize <= MAX_PACKET_SIZE + 64
+
+        case datalink
+        when 1 # DLT_EN10MB, including stacked 802.1Q / 802.1ad tags
+          return if data.bytesize < 14
+
+          offset = 14
+          ether_type = uint16(data, 12)
+          tags = 0
+          while VLAN_TYPES.include?(ether_type)
+            return if tags >= 4 || data.bytesize < offset + 4
+
+            ether_type = uint16(data, offset + 2)
+            offset += 4
+            tags += 1
+          end
+          family = { 0x0800 => :ipv4, 0x86dd => :ipv6 }[ether_type]
+        when 0, 108 # DLT_NULL (host endian), DLT_LOOP (network endian)
+          return if data.bytesize < 4
+
+          values = datalink == 108 ? [data.unpack1('N')] : [data.unpack1('V'), data.unpack1('N')]
+          af = values.find { |value| [2, 10, 24, 28, 30].include?(value) }
+          family = af == 2 ? :ipv4 : :ipv6 if af
+          offset = 4
+        when 12, 101 # DLT_RAW on different libpcap platforms
+          family = { 4 => :ipv4, 6 => :ipv6 }[data.getbyte(0).to_i >> 4]
+          offset = 0
+        when 228, 229 # DLT_IPV4, DLT_IPV6
+          family = datalink == 228 ? :ipv4 : :ipv6
+          offset = 0
+        else
+          return
+        end
+
+        decode(data.byteslice(offset..), family: family, local_capture: local_capture) if family
+      end
+
+      def match?(reply, probe)
+        return false unless reply.is_a?(Hash) && reply[:family] == probe.family
+        return false unless same_address?(reply[:destination], probe.source_address)
+
+        case reply[:kind]
+        when :echo_reply
+          probe.protocol == :icmp && same_address?(reply[:source], probe.destination_address) &&
+            icmp_identity_match?(reply, probe)
+        when :tcp_reply
+          tcp_match?(reply, probe)
+        when *ICMP_ERROR_KINDS
+          quote_match?(reply[:quoted], probe)
+        else
+          false
+        end
+      end
+
+      def destination_reached?(reply, probe)
+        return false unless match?(reply, probe)
+        return false unless same_address?(reply[:source], probe.destination_address)
+
+        case probe.protocol
+        when :icmp
+          reply[:kind] == :echo_reply
+        when :tcp
+          reply[:kind] == :tcp_reply
+        when :udp
+          reply[:kind] == :unreachable &&
+            [reply[:icmp_type], reply[:icmp_code]] == (probe.family == :ipv4 ? [3, 3] : [1, 4])
+        else
+          false
+        end
+      end
+
+      private
+
+      def decode_ip(data, family:, quoted: false, local_capture: false)
+        family == :ipv4 ? decode_ipv4(data, quoted: quoted, local_capture: local_capture) : decode_ipv6(data, quoted: quoted)
+      end
+
+      def decode_ipv4(data, quoted:, local_capture: false)
+        return if data.bytesize < 20 || data.getbyte(0) >> 4 != 4
+
+        header_length = (data.getbyte(0) & 0x0f) * 4
+        total_length = uint16(data, 2)
+        return if header_length < 20 || total_length < header_length || data.bytesize < header_length
+        return if !quoted && total_length > data.bytesize
+        if !quoted && checksum(data.byteslice(0, header_length)) != 0
+          return unless local_capture == true && data.getbyte(9) == 6 && uint16(data, 10).zero?
+        end
+        # An outer response must be complete. A quoted first fragment can still
+        # identify a kernel-fragmented probe from its first eight payload bytes.
+        fragment = uint16(data, 6)
+        return unless (fragment & 0x1fff).zero?
+        return if !quoted && (fragment & 0x2000).positive?
+
+        limit = [total_length, data.bytesize].min
+        {
+          family: :ipv4,
+          source: IPAddr.new_ntoh(data.byteslice(12, 4)).to_s,
+          destination: IPAddr.new_ntoh(data.byteslice(16, 4)).to_s,
+          number: data.getbyte(9),
+          payload: data.byteslice(header_length, limit - header_length)
+        }
+      end
+
+      def decode_ipv6(data, quoted:)
+        return if data.bytesize < 40 || data.getbyte(0) >> 4 != 6
+
+        payload_length = uint16(data, 4)
+        return if payload_length.zero? # Jumbo Payload options are unsupported.
+
+        total_length = 40 + payload_length
+        return if !quoted && total_length > data.bytesize
+
+        limit = [total_length, data.bytesize].min
+        number = data.getbyte(6)
+        offset = 40
+        extension_count = 0
+        while [0, 43, 44, 51, 60].include?(number)
+          return if extension_count >= MAX_EXTENSION_HEADERS || offset + 2 > limit
+
+          length = case number
+                   when 44
+                     return if offset + 8 > limit
+                     fragment = uint16(data, offset + 2)
+                     return unless (fragment & 0xfff8).zero?
+                     return if !quoted && (fragment & 1).positive?
+
+                     8
+                   when 51
+                     return if data.getbyte(offset + 1).zero?
+
+                     (data.getbyte(offset + 1) + 2) * 4
+                   else
+                     (data.getbyte(offset + 1) + 1) * 8
+                   end
+          return if offset + length > limit
+
+          number = data.getbyte(offset)
+          offset += length
+          extension_count += 1
+        end
+
+        {
+          family: :ipv6,
+          source: IPAddr.new_ntoh(data.byteslice(8, 16)).to_s,
+          destination: IPAddr.new_ntoh(data.byteslice(24, 16)).to_s,
+          number: number,
+          payload: data.byteslice(offset, limit - offset)
+        }
+      end
+
+      def decode_icmp(payload, reply)
+        return if payload.bytesize < 8
+
+        family = reply[:family]
+        check = family == :ipv4 ? payload : pseudoheader(family, reply[:source], reply[:destination], 58, payload.bytesize) + payload
+        return unless checksum(check).zero?
+
+        type = payload.getbyte(0)
+        code = payload.getbyte(1)
+        kind = icmp_kind(family, type, code)
+        return unless kind
+
+        reply = reply.merge(kind: kind, icmp_type: type, icmp_code: code)
+        if kind == :echo_reply
+          reply.merge(identifier: uint16(payload, 4), sequence: uint16(payload, 6))
+        else
+          quoted = decode_quote(payload.byteslice(8..), family)
+          return unless quoted
+
+          mtu = family == :ipv4 ? uint16(payload, 6) : uint32(payload, 4) if kind == :packet_too_big
+          reply.merge(quoted: quoted, mtu: mtu)
+        end
+      end
+
+      def icmp_kind(family, type, code)
+        if family == :ipv4
+          case type
+          when 0 then :echo_reply if code.zero?
+          when 3 then code == 4 ? :packet_too_big : :unreachable
+          when 11 then :time_exceeded if code <= 1
+          when 12 then :parameter_problem
+          end
+        else
+          case type
+          when 129 then :echo_reply if code.zero?
+          when 1 then :unreachable
+          when 2 then :packet_too_big if code.zero?
+          when 3 then :time_exceeded if code <= 1
+          when 4 then :parameter_problem
+          end
+        end
+      end
+
+      def decode_tcp(payload, reply, checksum_offloaded: false, local_capture: false)
+        return if payload.bytesize < 20
+
+        header_length = (payload.getbyte(12) >> 4) * 4
+        return if header_length < 20 || header_length > payload.bytesize
+
+        unless checksum_offloaded == true || local_capture == true
+          header = pseudoheader(reply[:family], reply[:source], reply[:destination], 6, payload.bytesize)
+          return unless checksum(header + payload).zero?
+        end
+
+        decoded = reply.merge(
+          kind: :tcp_reply,
+          source_port: uint16(payload, 0), destination_port: uint16(payload, 2),
+          tcp_sequence: uint32(payload, 4), tcp_ack: uint32(payload, 8), tcp_flags: payload.getbyte(13)
+        )
+        if local_capture == true
+          decoded[:checksum_status] = :unverified_local_capture
+        elsif checksum_offloaded == true
+          decoded[:checksum_status] = :kernel_offload
+        end
+        decoded
+      end
+
+      def decode_quote(data, family)
+        ip = decode_ip(data, family: family, quoted: true)
+        return unless ip && ip[:payload].bytesize >= 8
+
+        quote = ip.slice(:family, :source, :destination)
+        payload = ip[:payload]
+        case ip[:number]
+        when 17
+          return if uint16(payload, 4) < 8
+
+          quote.merge(protocol: :udp, source_port: uint16(payload, 0), destination_port: uint16(payload, 2))
+        when 6
+          quote.merge(protocol: :tcp, source_port: uint16(payload, 0), destination_port: uint16(payload, 2), tcp_sequence: uint32(payload, 4))
+        when family == :ipv4 ? 1 : 58
+          return unless payload.getbyte(0) == (family == :ipv4 ? 8 : 128) && payload.getbyte(1).zero?
+
+          quote.merge(protocol: :icmp, identifier: uint16(payload, 4), sequence: uint16(payload, 6))
+        end
+      end
+
+      def quote_match?(quote, probe)
+        return false unless quote.is_a?(Hash) && quote[:family] == probe.family && quote[:protocol] == probe.protocol
+        return false unless same_address?(quote[:source], probe.source_address) && same_address?(quote[:destination], probe.destination_address)
+
+        case probe.protocol
+        when :icmp
+          icmp_identity_match?(quote, probe)
+        when :udp
+          ports_match?(quote, probe.source_port, probe.destination_port)
+        when :tcp
+          ports_match?(quote, probe.source_port, probe.destination_port) &&
+            valid_uint?(quote[:tcp_sequence], 32) && quote[:tcp_sequence] == probe.tcp_sequence
+        else
+          false
+        end
+      end
+
+      def tcp_match?(reply, probe)
+        return false unless probe.protocol == :tcp && same_address?(reply[:source], probe.destination_address)
+        return false unless ports_match?(reply, probe.destination_port, probe.source_port)
+
+        flags = reply[:tcp_flags]
+        ack = reply[:tcp_ack]
+        return false unless valid_uint?(flags, 8) && valid_uint?(ack, 32) && valid_uint?(probe.tcp_sequence, 32)
+        return false unless (flags & 0x10).positive? && [0x02, 0x04].include?(flags & 0x06) && (flags & 0x01).zero?
+
+        payload_size = probe.respond_to?(:payload_size) ? probe.payload_size : 0
+        payload_size ||= 0
+        return false unless valid_uint?(payload_size, 16)
+
+        delta = (ack - probe.tcp_sequence) & 0xffff_ffff
+        delta.between?(1, 1 + payload_size)
+      end
+
+      def icmp_identity_match?(reply, probe)
+        valid_uint?(reply[:identifier], 16) && valid_uint?(reply[:sequence], 16) &&
+          reply[:identifier] == probe.identifier && reply[:sequence] == probe.sequence
+      end
+
+      def ports_match?(reply, source_port, destination_port)
+        valid_uint?(reply[:source_port], 16) && valid_uint?(reply[:destination_port], 16) &&
+          reply[:source_port] == source_port && reply[:destination_port] == destination_port
+      end
+
+      def protocol_number(protocol, family)
+        { icmp: family == :ipv4 ? 1 : 58, tcp: 6, udp: 17 }[protocol]
+      end
+
+      def checksum(data)
+        total = 0
+        offset = 0
+        while offset + 1 < data.bytesize
+          total += (data.getbyte(offset) << 8) | data.getbyte(offset + 1)
+          offset += 2
+        end
+        total += data.getbyte(offset) << 8 if offset < data.bytesize
+        total = (total & 0xffff) + (total >> 16) while total > 0xffff
+        (~total) & 0xffff
+      end
+
+      def pseudoheader(family, source, destination, protocol, length)
+        unless address_family?(source, family) && address_family?(destination, family)
+          raise ArgumentError, 'source and destination must match the address family'
+        end
+
+        addresses = address(source).hton + address(destination).hton
+        addresses + (family == :ipv4 ? [0, protocol, length].pack('CCn') : [length, protocol].pack('NN'))
+      end
+
+      def address(value)
+        IPAddr.new(value.to_s.split('%', 2).first)
+      end
+
+      def address_family?(value, family)
+        return false unless value
+
+        ip = address(value)
+        family == :ipv4 ? ip.ipv4? : ip.ipv6?
+      rescue ArgumentError
+        false
+      end
+
+      def same_address?(left, right)
+        left && right && address(left) == address(right) || false
+      rescue ArgumentError
+        false
+      end
+
+      def uint16(data, offset)
+        data.byteslice(offset, 2).unpack1('n')
+      end
+
+      def uint32(data, offset)
+        data.byteslice(offset, 4).unpack1('N')
+      end
+
+      def validate_family!(family)
+        raise ArgumentError, 'family must be :ipv4 or :ipv6' unless %i[ipv4 ipv6].include?(family)
+      end
+
+      def validate_uint!(value, bits, name)
+        raise ArgumentError, "#{name} must be an unsigned #{bits}-bit integer" unless valid_uint?(value, bits)
+      end
+
+      def valid_uint?(value, bits)
+        value.is_a?(Integer) && value.between?(0, (1 << bits) - 1)
+      end
+
+      def validate_payload!(payload, maximum)
+        raise ArgumentError, 'payload must be a String' unless payload.is_a?(String)
+        raise ArgumentError, "payload exceeds #{maximum} bytes" if payload.bytesize > maximum
+      end
+    end
+  end
+end