rptrace 0.1.0

data/lib/rptrace/c_structs.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Rptrace
+  # Architecture-specific register layouts and binary helpers.
+  module CStructs
+    # Host pointer width in bytes.
+    POINTER_SIZE = begin
+      [0].pack("J").bytesize
+    rescue StandardError
+      8
+    end
+    # Pointer pack format for host pointer size.
+    POINTER_PACK = POINTER_SIZE == 8 ? "Q<" : "L<"
+    # Register word width in bytes.
+    WORD_SIZE = 8
+    # Register word bitmask.
+    WORD_MASK = (1 << (WORD_SIZE * 8)) - 1
+    # Register word unpack/pack format.
+    PACK_FORMAT = "Q<"
+    # seccomp metadata struct pack format.
+    SECCOMP_METADATA_FORMAT = "Q<Q<"
+    # seccomp metadata struct size.
+    SECCOMP_METADATA_SIZE = 16
+    # BPF instruction size in seccomp filter dump.
+    SECCOMP_FILTER_INSN_SIZE = 8
+
+    # x86_64 user_regs_struct register names.
+    X86_64_REGS = %i[
+      r15 r14 r13 r12 rbp rbx r11 r10 r9 r8
+      rax rcx rdx rsi rdi orig_rax rip cs eflags
+      rsp ss fs_base gs_base ds es fs gs
+    ].freeze
+
+    # aarch64 register names returned by NT_PRSTATUS regset.
+    AARCH64_REGS = (0..30).map { |i| :"x#{i}" }.push(:sp, :pc, :pstate).freeze
+
+    module_function
+
+    # @return [Symbol] :x86_64 or :aarch64
+    def arch
+      @arch ||= detect_arch
+    end
+
+    # @param arch [Symbol]
+    # @return [Array<Symbol>]
+    def reg_names(arch: self.arch)
+      case arch
+      when :x86_64 then X86_64_REGS
+      when :aarch64 then AARCH64_REGS
+      else
+        raise UnsupportedArchError, "Unsupported architecture: #{arch}"
+      end
+    end
+
+    # @param arch [Symbol]
+    # @return [Integer]
+    def regs_size(arch: self.arch)
+      reg_names(arch: arch).size * 8
+    end
+
+    # @param source [String, Fiddle::Pointer]
+    # @param arch [Symbol]
+    # @return [Hash<Symbol, Integer>]
+    def decode_regs(source, arch: self.arch)
+      bytes = source.is_a?(String) ? source : source[0, regs_size(arch: arch)]
+      values = bytes.unpack("#{PACK_FORMAT}*")
+      names = reg_names(arch: arch)
+
+      names.each_with_index.each_with_object({}) do |(name, index), decoded|
+        decoded[name] = values.fetch(index, 0)
+      end
+    end
+
+    # @param regs [Hash<Symbol, Integer>]
+    # @param arch [Symbol]
+    # @return [String] packed binary register bytes
+    def encode_regs(regs, arch: self.arch)
+      names = reg_names(arch: arch)
+      values = names.map { |name| Integer(regs.fetch(name, 0)) & WORD_MASK }
+      values.pack("#{PACK_FORMAT}*")
+    end
+
+    # @param base [Integer]
+    # @param length [Integer]
+    # @return [String] packed iovec
+    def pack_iovec(base:, length:)
+      [Integer(base), Integer(length)].pack("#{POINTER_PACK}#{POINTER_PACK}")
+    end
+
+    # @param bytes [String]
+    # @return [Hash<Symbol, Integer>]
+    def unpack_iovec(bytes)
+      base, length = bytes.unpack("#{POINTER_PACK}#{POINTER_PACK}")
+      { base: base, length: length }
+    end
+
+    # @return [Integer]
+    def seccomp_metadata_size
+      SECCOMP_METADATA_SIZE
+    end
+
+    # @param filter_off [Integer]
+    # @param flags [Integer]
+    # @return [String]
+    def pack_seccomp_metadata(filter_off:, flags: 0)
+      [Integer(filter_off), Integer(flags)].pack(SECCOMP_METADATA_FORMAT)
+    end
+
+    # @param bytes [String]
+    # @return [Hash<Symbol, Integer>]
+    def unpack_seccomp_metadata(bytes)
+      filter_off, flags = bytes.unpack(SECCOMP_METADATA_FORMAT)
+      { filter_off: filter_off, flags: flags }
+    end
+
+    # @param bytes [String]
+    # @return [Array<Hash<Symbol, Integer>>]
+    def decode_seccomp_filter(bytes)
+      blob = bytes.to_s.b
+      raise ArgumentError, "seccomp filter bytes must align to #{SECCOMP_FILTER_INSN_SIZE}" unless (blob.bytesize % SECCOMP_FILTER_INSN_SIZE).zero?
+
+      instructions = []
+      blob.bytes.each_slice(SECCOMP_FILTER_INSN_SIZE) do |insn|
+        code, jt, jf, k = insn.pack("C*").unpack("S<CCL<")
+        instructions << { code: code, jt: jt, jf: jf, k: k }
+      end
+      instructions
+    end
+
+    # @return [Symbol]
+    # @raise [Rptrace::UnsupportedArchError]
+    def detect_arch
+      host_cpu = RbConfig::CONFIG.fetch("host_cpu", "")
+
+      case host_cpu
+      when /x86_64|amd64/
+        :x86_64
+      when /aarch64|arm64/
+        :aarch64
+      else
+        raise UnsupportedArchError, "Unsupported architecture: #{host_cpu}"
+      end
+    end
+  end
+end

data/lib/rptrace/constants.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Rptrace
+  # Linux ptrace and waitpid-related constants.
+  module Constants
+    NT_PRSTATUS = 1
+
+    PTRACE_TRACEME = 0
+    PTRACE_PEEKTEXT = 1
+    PTRACE_PEEKDATA = 2
+    PTRACE_PEEKUSER = 3
+    PTRACE_POKETEXT = 4
+    PTRACE_POKEDATA = 5
+    PTRACE_POKEUSER = 6
+    PTRACE_CONT = 7
+    PTRACE_KILL = 8
+    PTRACE_SINGLESTEP = 9
+    PTRACE_GETREGS = 12
+    PTRACE_SETREGS = 13
+    PTRACE_GETFPREGS = 14
+    PTRACE_SETFPREGS = 15
+    PTRACE_ATTACH = 16
+    PTRACE_DETACH = 17
+    PTRACE_GETFPXREGS = 18
+    PTRACE_SETFPXREGS = 19
+    PTRACE_SYSCALL = 24
+    PTRACE_SETOPTIONS = 0x4200
+    PTRACE_GETEVENTMSG = 0x4201
+    PTRACE_GETSIGINFO = 0x4202
+    PTRACE_SETSIGINFO = 0x4203
+    PTRACE_GETREGSET = 0x4204
+    PTRACE_SETREGSET = 0x4205
+    PTRACE_SEIZE = 0x4206
+    PTRACE_INTERRUPT = 0x4207
+    PTRACE_LISTEN = 0x4208
+    PTRACE_PEEKSIGINFO = 0x4209
+    PTRACE_GETSIGMASK = 0x420A
+    PTRACE_SETSIGMASK = 0x420B
+    PTRACE_SECCOMP_GET_FILTER = 0x420C
+    PTRACE_SECCOMP_GET_METADATA = 0x420D
+    PTRACE_GET_SYSCALL_INFO = 0x420E
+
+    PTRACE_O_TRACESYSGOOD = 0x00000001
+    PTRACE_O_TRACEFORK = 0x00000002
+    PTRACE_O_TRACEVFORK = 0x00000004
+    PTRACE_O_TRACECLONE = 0x00000008
+    PTRACE_O_TRACEEXEC = 0x00000010
+    PTRACE_O_TRACEVFORKDONE = 0x00000020
+    PTRACE_O_TRACEEXIT = 0x00000040
+    PTRACE_O_TRACESECCOMP = 0x00000080
+    PTRACE_O_EXITKILL = 0x00100000
+    PTRACE_O_SUSPEND_SECCOMP = 0x00200000
+
+    PTRACE_EVENT_FORK = 1
+    PTRACE_EVENT_VFORK = 2
+    PTRACE_EVENT_CLONE = 3
+    PTRACE_EVENT_EXEC = 4
+    PTRACE_EVENT_VFORK_DONE = 5
+    PTRACE_EVENT_EXIT = 6
+    PTRACE_EVENT_SECCOMP = 7
+    PTRACE_EVENT_STOP = 128
+
+    SECCOMP_FILTER_FLAG_TSYNC = 1
+    SECCOMP_FILTER_FLAG_LOG = 2
+    SECCOMP_FILTER_FLAG_SPEC_ALLOW = 4
+    SECCOMP_FILTER_FLAG_NEW_LISTENER = 8
+    SECCOMP_FILTER_FLAG_TSYNC_ESRCH = 16
+
+    WNOHANG = 1
+    WUNTRACED = 2
+    WCONTINUED = 8
+    WALL = 0x40000000
+  end
+
+  # Helpers mirroring wait status macros from sys/wait.h.
+  module WaitStatus
+    module_function
+
+    # @param status [Integer]
+    # @return [Boolean]
+    def exited?(status)
+      (status & 0x7F).zero?
+    end
+
+    # @param status [Integer]
+    # @return [Boolean]
+    def signaled?(status)
+      signal = status & 0x7F
+      !signal.zero? && signal != 0x7F
+    end
+
+    # @param status [Integer]
+    # @return [Boolean]
+    def stopped?(status)
+      (status & 0xFF) == 0x7F
+    end
+
+    # @param status [Integer]
+    # @return [Boolean]
+    def continued?(status)
+      status == 0xFFFF
+    end
+
+    # @param status [Integer]
+    # @return [Integer]
+    def exit_status(status)
+      (status >> 8) & 0xFF
+    end
+
+    # @param status [Integer]
+    # @return [Integer]
+    def term_signal(status)
+      status & 0x7F
+    end
+
+    # @param status [Integer]
+    # @return [Integer]
+    def stop_signal(status)
+      (status >> 8) & 0xFF
+    end
+
+    # @param status [Integer]
+    # @return [Boolean]
+    def core_dumped?(status)
+      signaled?(status) && (status & 0x80).positive?
+    end
+  end
+end

data/lib/rptrace/dsl.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Rptrace
+  class << self
+    # Default option set to follow fork/clone descendants.
+    FOLLOW_CHILD_TRACE_OPTIONS = Tracee::DEFAULT_TRACE_OPTIONS |
+      Constants::PTRACE_O_TRACECLONE |
+      Constants::PTRACE_O_TRACEFORK |
+      Constants::PTRACE_O_TRACEVFORK
+
+    # Spawns and traces a command for the duration of the block.
+    #
+    # @param command [String] executable path or command name
+    # @param args [Array<String>] command arguments
+    # @param options [Integer] ptrace options passed to Tracee.spawn
+    # @yieldparam tracee [Rptrace::Tracee]
+    # @return [Object] block return value
+    def trace(command, *args, options: Tracee::DEFAULT_TRACE_OPTIONS)
+      tracee = Tracee.spawn(command, *args, options: options)
+      yield tracee
+    ensure
+      safe_detach(tracee)
+    end
+
+    # Runs a command and yields syscall enter/exit events.
+    #
+    # @param command [String] executable path or command name
+    # @param args [Array<String>] command arguments
+    # @param follow_children [Boolean] follow clone/fork/vfork descendants
+    # @param yield_seccomp [Boolean] yield seccomp stop events as {Rptrace::SeccompEvent}
+    # @yieldparam event [Rptrace::SyscallEvent, Rptrace::SeccompEvent]
+    # @return [void]
+    def strace(command, *args, follow_children: false, yield_seccomp: false)
+      options = follow_children ? FOLLOW_CHILD_TRACE_OPTIONS : Tracee::DEFAULT_TRACE_OPTIONS
+      trace(command, *args, options: options) do |tracee|
+        if follow_children
+          strace_with_children(tracee, yield_seccomp: yield_seccomp) { |event| yield event }
+        else
+          strace_single(tracee, yield_seccomp: yield_seccomp) { |event| yield event }
+        end
+      end
+    end
+
+    private
+
+    def strace_single(tracee, yield_seccomp:)
+      loop do
+        tracee.syscall
+        event = tracee.wait(flags: Constants::WALL)
+        break if event.exited? || event.signaled?
+        if yield_seccomp && event.seccomp_event?
+          yield build_seccomp_event(tracee)
+          next
+        end
+        next unless event.syscall_stop?
+
+        syscall = tracee.current_syscall
+        syscall_args = tracee.syscall_args
+
+        yield SyscallEvent.new(tracee: tracee, syscall: syscall, args: syscall_args, phase: :enter)
+
+        tracee.syscall
+        exit_event = tracee.wait(flags: Constants::WALL)
+        break if exit_event.exited? || exit_event.signaled?
+
+        yield SyscallEvent.new(
+          tracee: tracee,
+          syscall: syscall,
+          args: syscall_args,
+          return_value: tracee.syscall_return,
+          phase: :exit
+        )
+      end
+    end
+
+    def strace_with_children(root_tracee, yield_seccomp:)
+      tracees = { root_tracee.pid => root_tracee }
+      pending_syscalls = {}
+      begin
+        root_tracee.syscall
+      rescue NoProcessError
+        return
+      end
+
+      while tracees.any?
+        event = Tracee.wait_any(flags: Constants::WALL)
+        tracee = tracees.fetch(event.pid) { tracees[event.pid] = Tracee.new(event.pid) }
+
+        if event.exited? || event.signaled?
+          pending_syscalls.delete(event.pid)
+          tracees.delete(event.pid)
+          next
+        end
+
+        if event.fork_like_event?
+          child_pid = tracee.event_message
+          child_tracee = tracees.fetch(child_pid) do
+            created = Tracee.new(child_pid)
+            created.set_options(FOLLOW_CHILD_TRACE_OPTIONS)
+            tracees[child_pid] = created
+          end
+          pending_syscalls.delete(child_pid)
+          resume_tracee_syscall(child_tracee, tracees: tracees, pending_syscalls: pending_syscalls)
+        end
+
+        if yield_seccomp && event.seccomp_event?
+          yield build_seccomp_event(tracee)
+        elsif event.syscall_stop?
+          if pending_syscalls.key?(event.pid)
+            entry = pending_syscalls.delete(event.pid)
+            yield SyscallEvent.new(
+              tracee: tracee,
+              syscall: entry.fetch(:syscall),
+              args: entry.fetch(:args),
+              return_value: tracee.syscall_return,
+              phase: :exit
+            )
+          else
+            syscall = tracee.current_syscall
+            syscall_args = tracee.syscall_args
+            pending_syscalls[event.pid] = { syscall: syscall, args: syscall_args }
+            yield SyscallEvent.new(tracee: tracee, syscall: syscall, args: syscall_args, phase: :enter)
+          end
+        end
+
+        resume_tracee_syscall(tracee, tracees: tracees, pending_syscalls: pending_syscalls)
+      end
+    ensure
+      tracees&.each_value { |tracee| safe_detach(tracee) }
+    end
+
+    def resume_tracee_syscall(tracee, tracees:, pending_syscalls:)
+      tracee.syscall
+    rescue NoProcessError
+      pending_syscalls.delete(tracee.pid)
+      tracees.delete(tracee.pid)
+      nil
+    end
+
+    def build_seccomp_event(tracee)
+      metadata_flags = begin
+        tracee.seccomp_metadata_flag_names
+      rescue Error
+        []
+      end
+      SeccompEvent.new(
+        tracee: tracee,
+        syscall: tracee.current_syscall,
+        data: tracee.seccomp_data,
+        metadata_flags: metadata_flags
+      )
+    end
+
+    def safe_detach(tracee)
+      begin
+        tracee&.detach
+      rescue Error, Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/rptrace/error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rptrace
+  # Base error for ptrace operations.
+  class Error < StandardError
+    attr_reader :errno, :request
+
+    def initialize(message = nil, errno: nil, request: nil)
+      @errno = errno
+      @request = request
+
+      if errno && request
+        super("ptrace(#{request}): #{message} (errno=#{errno})")
+      else
+        super(message)
+      end
+    end
+  end
+
+  # Error raised for EPERM.
+  class PermissionError < Error; end
+  # Error raised for ESRCH.
+  class NoProcessError < Error; end
+  # Error raised for EBUSY.
+  class BusyError < Error; end
+  # Error raised for EINVAL.
+  class InvalidArgError < Error; end
+  # Unsupported architecture error.
+  class UnsupportedArchError < StandardError; end
+end

data/lib/rptrace/event.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Rptrace
+  # waitpid status wrapper with ptrace-specific helpers.
+  class Event
+    # ptrace event code to symbolic name map for inspect output.
+    EVENT_NAME_BY_CODE = {
+      Constants::PTRACE_EVENT_FORK => "fork",
+      Constants::PTRACE_EVENT_VFORK => "vfork",
+      Constants::PTRACE_EVENT_CLONE => "clone",
+      Constants::PTRACE_EVENT_EXEC => "exec",
+      Constants::PTRACE_EVENT_VFORK_DONE => "vfork_done",
+      Constants::PTRACE_EVENT_EXIT => "exit",
+      Constants::PTRACE_EVENT_SECCOMP => "seccomp",
+      Constants::PTRACE_EVENT_STOP => "stop"
+    }.freeze
+
+    attr_reader :pid, :raw_status
+
+    def initialize(pid, raw_status)
+      @pid = Integer(pid)
+      @raw_status = Integer(raw_status)
+    end
+
+    # @return [Boolean]
+    def stopped?
+      WaitStatus.stopped?(raw_status)
+    end
+
+    # @return [Boolean]
+    def exited?
+      WaitStatus.exited?(raw_status)
+    end
+
+    # @return [Boolean]
+    def signaled?
+      WaitStatus.signaled?(raw_status)
+    end
+
+    # @return [Boolean]
+    def continued?
+      WaitStatus.continued?(raw_status)
+    end
+
+    # @return [Integer]
+    def stop_signal
+      WaitStatus.stop_signal(raw_status)
+    end
+
+    # @return [Integer]
+    def exit_status
+      WaitStatus.exit_status(raw_status)
+    end
+
+    # @return [Integer]
+    def term_signal
+      WaitStatus.term_signal(raw_status)
+    end
+
+    # @return [Boolean]
+    def syscall_stop?
+      stopped? && stop_signal == (Signal.list.fetch("TRAP") | 0x80)
+    end
+
+    # @return [Integer]
+    def event_code
+      (raw_status >> 16) & 0xFFFF
+    end
+
+    def fork_event?
+      event_code == Constants::PTRACE_EVENT_FORK
+    end
+
+    def clone_event?
+      event_code == Constants::PTRACE_EVENT_CLONE
+    end
+
+    def vfork_event?
+      event_code == Constants::PTRACE_EVENT_VFORK
+    end
+
+    def vfork_done_event?
+      event_code == Constants::PTRACE_EVENT_VFORK_DONE
+    end
+
+    def exec_event?
+      event_code == Constants::PTRACE_EVENT_EXEC
+    end
+
+    def exit_event?
+      event_code == Constants::PTRACE_EVENT_EXIT
+    end
+
+    def seccomp_event?
+      event_code == Constants::PTRACE_EVENT_SECCOMP
+    end
+
+    # @return [Boolean]
+    def fork_like_event?
+      fork_event? || clone_event? || vfork_event?
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} pid=#{pid} status=0x#{raw_status.to_s(16)} #{state_summary}>"
+    end
+
+    private
+
+    def state_summary
+      return "state=syscall_stop" if syscall_stop?
+      return "state=exited(#{exit_status})" if exited?
+      return "state=continued" if continued?
+      if stopped?
+        event_name = EVENT_NAME_BY_CODE[event_code]
+        summary = "state=stopped(#{signal_label(stop_signal)})"
+        return "#{summary} event=#{event_name}" if event_name
+
+        return summary
+      end
+      return "state=signaled(#{signal_label(term_signal)})" if signaled?
+
+      "state=unknown"
+    end
+
+    def signal_label(number)
+      signal_name = Signal.signame(number)
+      signal_name = "SIG#{signal_name}" unless signal_name.start_with?("SIG")
+      signal_name
+    rescue ArgumentError
+      "SIG#{number}"
+    end
+  end
+end