redhound 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6935c5774360fee584469172ce32fb3d5d75d9c6afac07471d6f81a1c2abeab
-  data.tar.gz: 98f8c7e7e2910174326df83669f9f2d48e3fbabed8ce74083e060299fd95b724
+  metadata.gz: 21334546fae10c6cbeb5b8d679e658317e39b569741ef671c45b7261dbb42106
+  data.tar.gz: 28046b9bfb2814928662e4d52768537bfd780778554c3073c1aebabf45da443b
 SHA512:
-  metadata.gz: 17a0eb8f7d9cf19e20c2e44a98c23054aaedc51e1fac0d314b4832c85a3c586d68057a3367887beb8a33ac41b27c1746569510cc4da874bf23ab92b130fe0c7c
-  data.tar.gz: 0c3cae42594bfc3e341885efb840212b6d1e36b39c7ef53ece6dddb7ad59fc97d59842d9397fe82ae2f7b1f9ad3775d4e493c9987611058b85b65d4d40e405b5
+  metadata.gz: 81a384c6381bb1473013536513b1b5e12e2faf7c78300cebf0dde4d778e0521ac8d80d6e0c31b5e27199158464711b3cc450f8b00e2cefc6e650d5801fd94c9c
+  data.tar.gz: b9f2fec1904e462b2d650cfbdb3d1704408160005dc103f4d6db39fbffacb28b1e3d371dfc4f518306e349f1269f9bea36ffdbaeecf51e5ac28ac2f29fb55b8c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2024-11-05
+## Unreleased
+
+## 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
 
 - 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.
@@ -20,11 +20,20 @@ gem install redhound
 ## Usage
 
 ```command
+   ___         ____                     __
+  / _ \___ ___/ / /  ___  __ _____  ___/ /
+ / , _/ -_) _  / _ \/ _ \/ // / _ \/ _  /
+/_/|_|\__/\_,_/_//_/\___/\_,_/_//_/\_,_/
+
+Version: 1.0.0
+Dump and analyze network packets.
+
 Usage: redhound [options] ...
 
 Options:
     -i, --interface INTERFACE        name or idx of interface
     -D, --list-interfaces            print list of interfaces and exit
+    -w FILE                          write packets to a pcap capture file format to file
     -h, --help                       display this help and exit
     -v, --version                    display version information and exit
 ```

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,21 +6,24 @@ 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?
         warn 'Error: interface is required'
         exit 1
       end
-      Receiver.run(ifname: @options[:ifname])
+      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
              ___         ____                     __
             / _ \___ ___/ / /  ___  __ _____  ___/ /
@@ -39,6 +43,7 @@ module Redhound
           list_interfaces
           exit
         end
+        o.on('-w FILE', 'write packets to a pcap capture file format to file') { |v| @options[:filename] = v }
         o.on('-h', '--help', 'display this help and exit') do
           puts o
           exit
@@ -54,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