redhound 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f9c914cea67f4e0f32f6dcf84149039eb95f1f2311bd6f410641b67b81d441f
-  data.tar.gz: ac1012da2b103d27bb43d98ca273567efc44fa4995de92af315370f73a899dc8
+  metadata.gz: 7fc9146df6d249b2bdd3ca7c529c6d72eaad8c78970e6cc21d4be41f9e233a25
+  data.tar.gz: 9f66932249c4235042d3934579fdf7f9be92ad531f30e1e5c05ed1a55ae436e4
 SHA512:
-  metadata.gz: 4c26cd6fea83dcbd1f60e2615a8070f60ccb036f506f9a46c77d0f935a57027ddf19d7f408271dccc8a31cc3d9624b6e6db62b252bd9b6393de858819a2855c9
-  data.tar.gz: 4ce4cf820846e2e652bfa33a16d08ca942eb1739d0f29a04a18389fb6d992b9ab4b13504de5d5684ab67f753bc02cc94a1c9cd702dcc922b95b2de5a7a9983a8
+  metadata.gz: 4ee95bd38fa1717c5286ae994db3b4d2c024c07119489d65f7b48a2cd9f5337b1a0cf0ebf36659f37d113052aaee178cd8ee29d50c2d995bee06d97443335fc6
+  data.tar.gz: 895d8f8b92858aaf63ac5bfc9b7ee2dc4a4fb594313e20052a96bdf893380aaae4853988c8e2966657ea3f2788eabf604a3ef44ebb16cf9954f0df5c4aeef444

data/CHANGELOG.md

@@ -1,9 +1,22 @@
-## [Unreleased]
+# Changelog
 
-## [0.2.0] - 2025-01-03
+## Unreleased
+
+## 1.0.1 - 2025-01-17
+
+- Fix an NameError in Redhound::L3::Arp
+
+## 1.0.0 - 2025-01-16
+
+- Add ARP header support.
+- Add IPv6 header support.
+- Improve formatting of packet output.
+- Remove debug print statement from IPv4 header parsing.
+
+## 0.2.0 - 2025-01-03
 
 - Add option to write packets to file as PCAP Capture File Format.
 
-## [0.1.0] - 2024-11-05
+## 0.1.0 - 2024-11-05
 
 - Initial release

data/Dockerfile

@@ -1,5 +1,5 @@
 FROM ruby:3.3.4
-RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
+RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs iputils-ping iproute2 iptables
 WORKDIR /app
 COPY Gemfile /app/Gemfile
 RUN bundle install

data/README.md

@@ -1,4 +1,4 @@
-# Redhound
+# Redhound [![Gem Version](https://badge.fury.io/rb/redhound.svg)](https://badge.fury.io/rb/redhound) [![Test](https://github.com/ydah/redhound/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/redhound/actions/workflows/main.yml)
 
 Pure Ruby packet analyzer.
 At this time, it is only guaranteed to work on Linux.
@@ -25,7 +25,7 @@ gem install redhound
  / , _/ -_) _  / _ \/ _ \/ // / _ \/ _  /
 /_/|_|\__/\_,_/_//_/\___/\_,_/_//_/\_,_/
 
-Version: 0.1.0
+Version: 1.0.1
 Dump and analyze network packets.
 
 Usage: redhound [options] ...

data/Rakefile

@@ -1,4 +1,15 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-task default: %i[]
+
+desc "steep check"
+task :steep do
+  sh "bundle exec steep check"
+end
+
+desc "Run rbs-inline"
+task :rbs_inline do
+  sh "bundle exec rbs-inline --output lib/"
+end
+
+task default: %i[rbs_inline steep]

data/Steepfile

@@ -0,0 +1,4 @@
+target :lib do
+  signature "sig"
+  check "lib"
+end

data/lib/redhound/analyzer.rb

@@ -1,30 +1,34 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module Redhound
   class Analyzer
-    def self.analyze(msg:)
-      new(msg: msg).analyze
+    # @rbs (msg: String, count: Integer) -> void
+    def self.analyze(msg:, count:)
+      new(msg:, count:).analyze
     end
 
-    def initialize(msg:)
+    # @rbs (msg: String, count: Integer) -> void
+    def initialize(msg:, count:)
       @msg = msg
+      @count = count
     end
 
+    # @rbs () -> void
     def analyze
-      puts 'Analyzing...'
-      ether = Header::Ether.generate(bytes: @msg.bytes[0..13])
-      ether.dump
-      return unless ether.ipv4?
+      l2 = L2::Ether.generate(bytes: @msg.bytes[0..], count: @count)
+      l2.dump
+      return unless l2.supported_type?
 
-      ip = Header::Ipv4.generate(bytes: @msg.bytes[14..33])
-      ip.dump
-      if ip.udp?
-        udp = Header::Udp.generate(bytes: @msg.bytes[34..41])
-        udp.dump
-      elsif ip.icmp?
-        icmp = Header::Icmp.generate(bytes: @msg.bytes[34..41])
-        icmp.dump
+      l3 = L3::Resolver.resolve(bytes: @msg.bytes[l2.size..], l2:)
+      return if !l3 || @msg.bytes.size <= l2.size + l3.size
+      l3.dump
+      unless l3.supported_protocol?
+        puts "    └─ Unsupported protocol #{l3.protocol}"
+        return
       end
+
+      L4::Resolver.resolve(bytes: @msg.bytes[(l2.size + l3.size)..], l3:)&.dump
     end
   end
 end

data/lib/redhound/builder/packet_mreq.rb

@@ -0,0 +1,56 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'socket'
+
+module Redhound
+  module Builder
+    class PacketMreq
+      PACKET_MR_PROMISC = 0x0001 # NOTE: netpacket/packet.h
+
+      # @rbs (ifname: String) -> void
+      def initialize(ifname:)
+        @ifname = ifname
+      end
+
+      # see: https://man7.org/linux/man-pages/man7/packet.7.html
+      # struct packet_mreq {
+      #   int            mr_ifindex;    /* interface index */
+      #   unsigned short mr_type;       /* action */
+      #   unsigned short mr_alen;       /* address length */
+      #   unsigned char  mr_address[8]; /* physical-layer address */
+      # };
+      # @rbs () -> String
+      def build
+        mr_ifindex + mr_type + mr_alen + mr_address
+      end
+
+      # @rbs () -> String
+      def mr_ifindex
+        @mr_ifindex ||= [[index].pack('I')].pack('a4')
+      end
+
+      private
+
+      # @rbs () -> Integer?
+      def index
+        ::Socket.getifaddrs.find { |ifaddr| ifaddr.name == @ifname }&.ifindex
+      end
+
+      # @rbs () -> String
+      def mr_type
+        @mr_type ||= [PACKET_MR_PROMISC].pack('S')
+      end
+
+      # @rbs () -> String
+      def mr_alen
+        @mr_alen ||= [0].pack('S')
+      end
+
+      # @rbs () -> String
+      def mr_address
+        @mr_address ||= [0].pack('C') * 8
+      end
+    end
+  end
+end

data/lib/redhound/builder/socket.rb

@@ -0,0 +1,35 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require 'socket'
+
+module Redhound
+  module Builder
+    class Socket
+      SOL_PACKET            = 0x0107 # bits/socket.h
+      PACKET_ADD_MEMBERSHIP = 0x0001 # NOTE: netpacket/packet.h
+      ETH_P_ALL             = 768    # NOTE: htons(ETH_P_ALL) => linux/if_ether.h
+      PACKED_ETH_P_ALL = [ETH_P_ALL].pack('S').unpack1('S>')
+
+      class << self
+        # @rbs (ifname: String) -> Redhound::Source::Socket
+        def build(ifname:)
+          new(ifname:).build
+        end
+      end
+
+      # @rbs (ifname: String) -> void
+      def initialize(ifname:)
+        @mq_req = PacketMreq.new(ifname:)
+      end
+
+      # @rbs () -> Redhound::Source::Socket
+      def build
+        socket = ::Socket.new(::Socket::AF_PACKET, ::Socket::SOCK_RAW, ETH_P_ALL)
+        socket.bind([::Socket::AF_PACKET, PACKED_ETH_P_ALL, @mq_req.mr_ifindex].pack('SS>a16'))
+        socket.setsockopt(SOL_PACKET, PACKET_ADD_MEMBERSHIP, @mq_req.build)
+        Redhound::Source::Socket.new(socket:)
+      end
+    end
+  end
+end

data/lib/redhound/builder.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'builder/packet_mreq'
+require_relative 'builder/socket'

data/lib/redhound/command.rb

@@ -1,3 +1,4 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 require 'optparse'
@@ -5,10 +6,12 @@ require 'socket'
 
 module Redhound
   class Command
+    # @rbs () -> void
     def initialize
       @options = { ifname: nil }
     end
 
+    # @rbs (Array[untyped] argv) -> void
     def run(argv)
       parse(argv)
       if @options[:ifname].nil?
@@ -18,8 +21,9 @@ module Redhound
       Receiver.run(ifname: @options[:ifname], filename: @options[:filename])
     end
 
+    # @rbs (Array[untyped] argv) -> void
     def parse(argv)
-      OptionParser.new do |o|
+      OptionParser.new do |o| # steep:ignore
         o.banner = <<~'BANNER' + <<~BANNER2
              ___         ____                     __
             / _ \___ ___/ / /  ___  __ _____  ___/ /
@@ -55,6 +59,7 @@ module Redhound
 
     private
 
+    # @rbs () -> void
     def list_interfaces
       ::Socket.getifaddrs.each { |ifaddr| puts ifaddr.name }
     end

data/lib/redhound/l2/ether.rb

@@ -0,0 +1,68 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  class L2
+    class Ether
+      attr_reader :type #: Protocol
+
+      class << self
+        # @rbs (bytes: Array[Integer], count: Integer) -> Redhound::L2::Ether
+        def generate(bytes:, count:)
+          new(bytes:, count:).generate
+        end
+      end
+
+      # @rbs (bytes: Array[Integer], count: Integer) -> void
+      def initialize(bytes:, count:)
+        raise ArgumentError, "bytes must be #{size} bytes" unless bytes.size >= size
+
+        @bytes = bytes
+        @count = count
+      end
+
+      # @rbs () -> Integer
+      def size = 14
+
+      # @rbs () -> Redhound::L2::Ether
+      def generate
+        @dhost = @bytes[0..5]
+        @shost = @bytes[6..11]
+        @type = Protocol.new(protocol: hex_type(@bytes[12..13]))
+        self
+      end
+
+      # @rbs () -> void
+      def dump
+        puts self
+      end
+
+      # @rbs () -> String
+      def to_s
+        "[#{@count}] Ethernet Dst: #{dhost} Src: #{shost} Type: #{@type}"
+      end
+
+      # @rbs () -> bool
+      def supported_type?
+        @type.ipv4? || @type.ipv6? || @type.arp? # steep:ignore
+      end
+
+      private
+
+      # @rbs () -> String
+      def dhost
+        @dhost.map { |b| b.to_s(16).rjust(2, '0') }.join(':')
+      end
+
+      # @rbs () -> String
+      def shost
+        @shost.map { |b| b.to_s(16).rjust(2, '0') }.join(':')
+      end
+
+      # @rbs (Array[Integer] type) -> Integer
+      def hex_type(type)
+        type.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
+      end
+    end
+  end
+end

data/lib/redhound/l2/protocol.rb

@@ -0,0 +1,33 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  class L2
+    class Protocol
+      PROTO_TABLE = {
+        0x0060 => 'Loopback',
+        0x0800 => 'IPv4',
+        0x0806 => 'ARP',
+        0x86DD => 'IPv6',
+        0x8100 => 'VLAN',
+      }
+
+      # @rbs (protocol: Integer) -> void
+      def initialize(protocol:)
+        @protocol = protocol
+      end
+
+      # @rbs () -> String
+      def to_s
+        PROTO_TABLE[@protocol] || 'Unknown'
+      end
+
+      PROTO_TABLE.each do |id, name|
+        method_name = name.downcase.gsub(/[ \-]/, '_') + '?'
+        define_method(method_name) do
+          @protocol == id
+        end
+      end
+    end
+  end
+end

data/lib/redhound/l2.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'l2/ether'
+require_relative 'l2/protocol'

data/lib/redhound/l3/arp.rb

@@ -0,0 +1,114 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  class L3
+    class Arp < Base
+      class << self
+        # @rbs (bytes: Array[Integer]) -> Redhound::L3::Arp
+        def generate(bytes:)
+          new(bytes:).generate
+        end
+      end
+
+      # @rbs (bytes: Array[Integer]) -> void
+      def initialize(bytes:)
+        raise ArgumentError, "bytes must be bigger than #{arp_size} bytes" unless bytes.size >= arp_size
+
+        @bytes = bytes
+      end
+
+      # @rbs () -> Redhound::L3::Arp
+      def generate
+        @htype = @bytes[0..1]
+        @ptype = @bytes[2..3]
+        @hlen = @bytes[4]
+        @plen = @bytes[5]
+        @oper = @bytes[6..7]
+        @sha = @bytes[8..13]
+        @spa = @bytes[14..17]
+        @tha = @bytes[18..23]
+        @tpa = @bytes[24..27]
+        @type = Redhound::L2::Protocol.new(protocol: ptype)
+        @l3 = generate_l3
+        self
+      end
+
+      # @rbs () -> Integer
+      def arp_size = 28
+
+      # @rbs () -> Integer
+      def size
+        if @l3.nil?
+          arp_size
+        else
+          arp_size + @l3.size
+        end
+      end
+
+      # @rbs () -> String
+      def to_s
+        "    └─ ARP HType: #{htype} PType: #{ptype} HLen: #{@hlen} PLen: #{@plen} Oper: #{oper} SHA: #{sha} SPA: #{spa} THA: #{tha} TPA: #{tpa}"
+      end
+
+      # @rbs () -> bool
+      def supported_protocol?
+        return false if @l3.nil?
+        @l3.supported_protocol?
+      end
+
+      # @rbs () -> String?
+      def protocol
+        @l3.protocol if @l3
+      end
+
+      private
+
+      # @rbs () -> Integer
+      def htype
+        @htype.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
+      end
+
+      # @rbs () -> Integer
+      def ptype
+        @ptype.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
+      end
+
+      # @rbs () -> Integer
+      def oper
+        @oper.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
+      end
+
+      # @rbs () -> String
+      def sha
+        @sha.map { |b| b.to_s(16).rjust(2, '0') }.join(':')
+      end
+
+      # @rbs () -> String
+      def spa
+        @spa.map { |b| b.to_s(16).rjust(2, '0') }.join('.')
+      end
+
+      # @rbs () -> String
+      def tha
+        @tha.map { |b| b.to_s(16).rjust(2, '0') }.join(':')
+      end
+
+      # @rbs () -> String
+      def tpa
+        @tpa.map { |b| b.to_s(16).rjust(2, '0') }.join('.')
+      end
+
+      # @rbs () -> Redhound::L3::Base?
+      def generate_l3
+        return if @bytes.size == arp_size
+
+        if @type.ipv4?
+          Ipv4.generate(bytes: @bytes[arp_size..])
+        elsif @type.ipv6?
+          Ipv6.generate(bytes: @bytes[arp_size..])
+        end
+      end
+    end
+  end
+end

data/lib/redhound/l3/base.rb

@@ -0,0 +1,49 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Redhound
+  class L3
+    class Base
+      class << self
+        # @rbs (bytes: Array[Integer]) -> Redhound::L3::Base
+        def generate(bytes:)
+          new(bytes:).generate
+        end
+      end
+
+      # @rbs (bytes: Array[Integer]) -> void
+      def initialize(bytes:)
+        warn 'initialize method must be implemented'
+      end
+
+      # @rbs () -> Redhound::L3::Base
+      def generate
+        warn 'generate method must be implemented'
+        self
+      end
+
+      # @rbs () -> void
+      def dump
+        puts self
+      end
+
+      # @rbs () -> Integer
+      def size
+        warn 'size method must be implemented'
+        0
+      end
+
+      # @rbs () -> bool
+      def supported_protocol?
+        warn 'supported_protocol? method must be implemented'
+        false
+      end
+
+      # @rbs () -> Protocol
+      def protocol
+        warn 'protocol method must be implemented'
+        Protocol.new(protocol: 0)
+      end
+    end
+  end
+end

data/lib/redhound/{header → l3}/ipv4.rb

@@ -1,24 +1,26 @@
+# rbs_inline: enabled
 # frozen_string_literal: true
 
 module Redhound
-  class Header
-    class Ipv4
+  class L3
+    class Ipv4 < Base
       class << self
+        # @rbs (bytes: Array[Integer]) -> Redhound::L3::Ipv4
         def generate(bytes:)
           new(bytes:).generate
         end
       end
 
-      # ref: https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml#protocol-numbers-1
-      ICMP = 1
-      UDP = 17
+      attr_reader :protocol #: Protocol
 
+      # @rbs (bytes: Array[Integer]) -> void
       def initialize(bytes:)
-        raise ArgumentError, 'bytes must be 20 bytes' unless bytes.size == 20
+        raise ArgumentError, "bytes must be #{size} bytes" unless bytes.size >= size
 
         @bytes = bytes
       end
 
+      # @rbs () -> Redhound::L3::Ipv4
       def generate
         @version = @bytes[0]
         @ihl = @bytes[0]
@@ -27,85 +29,66 @@ module Redhound
         @id = @bytes[4..5]
         @frag_off = @bytes[6..7]
         @ttl = @bytes[8]
-        @protocol = @bytes[9]
+        @protocol = Protocol.new(protocol: @bytes[9])
         @check = @bytes[10..11]
         @saddr = @bytes[12..15]
         @daddr = @bytes[16..19]
         self
       end
 
-      def icmp?
-        @protocol == ICMP
-      end
-
-      def udp?
-        @protocol == UDP
-      end
+      # @rbs () -> Integer
+      def size = 20
 
-      def dump
-        puts 'IPv4 HEADER----------------'
-        puts self
+      # @rbs () -> String
+      def to_s
+        " └─ IPv4 Ver: #{version} IHL: #{ihl} TOS: #{@tos} Total Length: #{tot_len} ID: #{id} Offset: #{frag_off} TTL: #{@ttl} Protocol: #{@protocol} Checksum: #{check} Src: #{saddr} Dst: #{daddr}"
       end
 
-      def to_s
-        <<~IPV4
-          Version: #{@version}
-          IHL: #{@ihl}
-          TOS: #{@tos}
-          Total Length: #{tot_len}
-          ID: #{id}
-          Fragment Offset: #{frag_off}
-          TTL: #{@ttl}
-          Protocol: #{protocol}
-          Checksum: #{check}
-          Source IP: #{saddr}
-          Destination IP: #{daddr}
-        IPV4
+      # @rbs () -> bool
+      def supported_protocol?
+        @protocol.udp? || @protocol.icmp? # steep:ignore
       end
 
       private
 
+      # @rbs () -> Integer
       def version
         @version & 0xF0
       end
 
+      # @rbs () -> Integer
       def ihl
         @ihl & 0x0F
       end
 
+      # @rbs () -> Integer
       def tot_len
         @tot_len.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
       end
 
+      # @rbs () -> Integer
       def id
         @id.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
       end
 
+      # @rbs () -> Integer
       def frag_off
         @frag_off.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16) & 0x1FFF
       end
 
-      def protocol
-        case @protocol
-        when ICMP
-          'ICMP'
-        when UDP
-          'UDP'
-        else
-          'Unknown'
-        end
-      end
-
+      # @rbs () -> Integer
       def check
         @check.map { |b| b.to_s(16).rjust(2, '0') }.join.to_i(16)
       end
 
+      # @rbs () -> String
       def saddr
-        @saddr.map { |b| b.to_s(16).rjust(2, '0') }.join('.')
+        @saddr.join('.')
       end
 
+      # @rbs () -> String
       def daddr
-        @daddr.map { |b| b.to_s(16).rjust(2, '0') }.join('.')
+        @daddr.join('.')
       end
     end
   end