rptrace 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db5900c94042eb61d01de6b3c3394d23833fde0ccf3c23a7974618d52686cf68
+  data.tar.gz: a34a2007bca148522855b1e5019c1c6d5975440621a9132ec50d6a71f6f04c20
+SHA512:
+  metadata.gz: 748068d4a08b509c8ccd31bf30c5643236b7b8d9df3eaaf737c251c67173c162629a0e5a3780efb0a69037a9bee66de38f0a4905a0bf63cc05f91e971cd6aef8
+  data.tar.gz: 4a87fb8ea9fa2c52f2d36b1889d2d124f5bc53728688a351b2e5c3c5c9785584967b80d37684a410773fb360134cb6cd1e2c73c9c1dccb8431bf1a61eddd1cc3

data/.yardopts

@@ -0,0 +1,4 @@
+--readme README.md
+--output-dir doc
+--markup markdown
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2026-02-21)
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# rptrace
+
+`rptrace` is a Ruby wrapper for Linux `ptrace(2)` focused on building tracers and debugger-like tooling with a Ruby-friendly API.
+
+## Overview and Motivation
+
+Linux `ptrace(2)` is powerful but low-level. This gem wraps process control, register/memory access, and syscall decoding behind a small Ruby API so you can build:
+
+- `strace`-like tools
+- process instrumentation utilities
+- debugger-oriented experiments
+
+## Features
+
+- Top-level namespace is `Rptrace` (no `Rptrace::Ruby` nesting)
+- `Tracee` API for `spawn`, `attach`, `cont`, `syscall`, `detach`, and `wait`
+- Register and memory wrappers (`Registers`, `Memory`)
+- `/proc/<pid>/maps` parser (`ProcMaps`, `Tracee#memory_maps`)
+- Software breakpoints on x86_64 (`Tracee#set_breakpoint`, `remove_breakpoint`)
+- Syscall lookup (`Rptrace::Syscall`) for `x86_64`/`aarch64`
+- High-level tracing helper `Rptrace.strace` (`follow_children` / `yield_seccomp` supported)
+- ptrace event helpers (`Tracee#event_message`, `Tracee#seccomp_data`, `Tracee#seccomp_metadata`, `Tracee#seccomp_filter`)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "rptrace"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "rptrace"
+
+Rptrace.strace("/bin/ls", "-la", "/tmp") do |event|
+  next unless event.exit?
+
+  puts event
+end
+```
+
+Follow child processes/threads (clone/fork/vfork):
+
+```ruby
+Rptrace.strace("/usr/bin/ruby", "-e", "pid = fork { sleep 0.1 }; Process.wait(pid)", follow_children: true) do |event|
+  next unless event.enter?
+  puts "pid=#{event.tracee.pid} #{event.syscall.name}"
+end
+```
+
+Include seccomp stop events in trace stream:
+
+```ruby
+Rptrace.strace("/bin/ls", "/tmp", yield_seccomp: true) do |event|
+  case event
+  when Rptrace::SyscallEvent
+    puts event if event.exit?
+  when Rptrace::SeccompEvent
+    warn event.to_s
+  end
+end
+```
+
+Set and clear a software breakpoint (x86_64):
+
+```ruby
+tracee = Rptrace::Tracee.attach(target_pid)
+bp = tracee.set_breakpoint(0x401000)
+# ...
+bp.restore
+```
+
+Inspect seccomp filter metadata and decoded BPF instructions:
+
+```ruby
+tracee = Rptrace::Tracee.attach(target_pid)
+tracee.enable_seccomp_events!
+supported = tracee.seccomp_supported?
+available = tracee.seccomp_filter_available?(index: 0)
+meta = tracee.seccomp_metadata(index: 0) # => { filter_off: 0, flags: ... }
+flag_names = tracee.seccomp_metadata_flag_names(index: 0) # => [:tsync, :log, ...]
+insns = tracee.seccomp_filter(index: 0)  # => [{ code:, jt:, jf:, k: }, ...]
+```
+
+## Permission Guide
+
+`ptrace` requires privilege on Linux:
+
+- run as `root`, or
+- run with `CAP_SYS_PTRACE`, and
+- ensure Yama policy allows tracing (`/proc/sys/kernel/yama/ptrace_scope`)
+
+Integration specs are opt-in and require:
+
+```bash
+PTRACE_RUN_INTEGRATION=1 bundle exec rspec spec/integration
+```
+
+You can inspect local ptrace capability setup from Ruby:
+
+```ruby
+diagnostics = Rptrace.ptrace_permissions
+puts diagnostics # => { ptrace_privileged:, cap_sys_ptrace:, yama_ptrace_scope:, hints: [...] }
+```
+
+Fail fast with an actionable permission error:
+
+```ruby
+Rptrace.ensure_ptrace_privileged!(request: :attach)
+```
+
+## Examples
+
+- `examples/simple_strace.rb`
+- `examples/syscall_counter.rb`
+- `examples/file_access_tracer.rb`
+- `examples/memory_reader.rb`
+
+## API Reference
+
+- Generate docs: `bundle exec yard doc`
+- Open index: `doc/index.html`
+
+## Development
+
+```bash
+bundle exec rspec
+```
+
+Run specs with coverage threshold check:
+
+```bash
+COVERAGE=1 COVERAGE_MIN_LINE=95 bundle exec rspec spec/unit spec/rptrace_spec.rb
+```
+
+Generate syscall tables from Linux headers (`x86_64` / `aarch64`):
+
+```bash
+bundle exec rake syscall:generate
+```
+
+You can override header paths with:
+
+- `PTRACE_SYSCALL_HEADER_X86_64`
+- `PTRACE_SYSCALL_HEADER_AARCH64`
+
+Optional task controls:
+
+- `ARCH=x86_64` (or `ARCH=x86_64,aarch64`) to limit architectures
+- `STRICT=1` to fail if any requested architecture header is missing
+
+Generate YARD documentation:
+
+```bash
+bundle exec yard doc
+```
+
+## Release
+
+- CI release workflow: `.github/workflows/release.yml`
+- Trigger by pushing a tag (example: `v0.1.0`) or via `workflow_dispatch`
+- Set repository secret `RUBYGEMS_API_KEY` to enable `gem push`
+- Local preflight: `bundle exec rake release:preflight`
+- Local credential check: `bundle exec rake release:check_credentials`
+
+## Limitations
+
+- Linux only
+- Ruby 3.1+
+- Architecture support: `x86_64` and `aarch64`
+- Integration tests require ptrace permission (`root` or `CAP_SYS_PTRACE`)
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require_relative "lib/rptrace/syscall_table/generator"
+require "yaml"
+
+RSpec::Core::RakeTask.new(:spec)
+
+namespace :syscall do
+  desc "Generate syscall tables from Linux headers"
+  task :generate do
+    arches = ENV.fetch("ARCH", "").split(",").map(&:strip).reject(&:empty?).map(&:to_sym)
+    arches = Rptrace::SyscallTable::Generator::ARCH_CONFIG.keys if arches.empty?
+    strict = ENV["STRICT"] == "1"
+
+    if strict
+      results = Rptrace::SyscallTable::Generator.generate_all(root_dir: __dir__, arches: arches, skip_missing: false)
+      skipped = []
+    else
+      output = Rptrace::SyscallTable::Generator.generate_available(root_dir: __dir__, arches: arches)
+      results = output.fetch(:generated)
+      skipped = output.fetch(:skipped)
+    end
+
+    abort("syscall:generate failed: no headers found for requested architectures") if results.empty?
+
+    results.each do |result|
+      puts "generated #{result[:arch]} table (#{result[:entries_count]} entries)"
+      puts "  header: #{result[:header_path]}"
+      puts "  output: #{result[:output_path]}"
+    end
+
+    skipped.each do |entry|
+      warn "skipped #{entry[:arch]}: #{entry[:reason]}"
+    end
+  rescue Rptrace::SyscallTable::Generator::HeaderNotFoundError, ArgumentError => e
+    abort("syscall:generate failed: #{e.message}")
+  end
+end
+
+namespace :release do
+  desc "Run release preflight checks (unit specs, docs, gem build)"
+  task :preflight do
+    sh "bundle exec rspec spec/unit spec/rptrace_spec.rb"
+    sh "bundle exec yard doc -n --no-cache"
+    sh "gem build rptrace.gemspec"
+  end
+
+  desc "Check RubyGems API key availability for gem push"
+  task :check_credentials do
+    env_key = ENV["RUBYGEMS_API_KEY"]
+    if env_key && !env_key.strip.empty?
+      puts "RUBYGEMS_API_KEY is set in environment"
+      next
+    end
+
+    credentials_path = File.expand_path("~/.gem/credentials")
+    if File.readable?(credentials_path)
+      credentials = YAML.load_file(credentials_path) || {}
+      api_key = credentials[":rubygems_api_key"] || credentials["rubygems_api_key"]
+      if api_key && !api_key.to_s.strip.empty?
+        puts "RubyGems API key found in #{credentials_path}"
+        next
+      end
+    end
+
+    abort("release:check_credentials failed: RUBYGEMS_API_KEY is not configured")
+  end
+end
+
+task default: :spec

data/examples/file_access_tracer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rptrace"
+
+if ARGV.empty?
+  warn "usage: bundle exec ruby examples/file_access_tracer.rb <command> [args...]"
+  exit 1
+end
+
+command = ARGV.shift
+
+Rptrace.strace(command, *ARGV) do |event|
+  next unless event.exit?
+  next unless %i[open openat].include?(event.syscall.name)
+
+  puts event.to_s
+end

data/examples/memory_reader.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rptrace"
+
+pid_str = ARGV.shift || begin
+  warn "usage: bundle exec ruby examples/memory_reader.rb <pid> [address_hex] [length]"
+  exit 1
+end
+
+pid = Integer(pid_str, 10)
+
+requested_address = nil
+length_arg = nil
+
+case ARGV.length
+when 0
+  length_arg = "64"
+when 1
+  token = ARGV[0]
+  if token.start_with?("0x", "0X")
+    requested_address = Integer(token, 0)
+    length_arg = "64"
+  else
+    length_arg = token
+  end
+else
+  requested_address = Integer(ARGV[0], 0)
+  length_arg = ARGV[1]
+end
+
+length = Integer(length_arg, 10)
+raise ArgumentError, "length must be positive" if length <= 0
+
+tracee = Rptrace::Tracee.attach(pid)
+
+begin
+  candidates = []
+  if requested_address
+    candidates << requested_address
+  else
+    registers = tracee.registers.read
+    arch_candidates = case Rptrace::CStructs.arch
+                      when :x86_64 then [registers[:rdi], registers[:rsp]]
+                      when :aarch64 then [registers[:x0], registers[:sp]]
+                      else []
+                      end
+    candidates.concat(arch_candidates.compact)
+    tracee.memory_maps.each do |map|
+      next unless map.readable?
+
+      candidates << map.start_addr
+    end
+  end
+
+  address = candidates.find do |candidate|
+    tracee.memory.read(candidate, 1)
+    true
+  rescue Rptrace::Error
+    false
+  end
+
+  unless address
+    warn "failed to find readable address for pid=#{pid}"
+    exit 1
+  end
+
+  data = tracee.memory.read(address, length)
+  puts "pid=#{pid} addr=0x#{address.to_s(16)} bytes=#{data.unpack1('H*')} size=#{data.bytesize}"
+ensure
+  tracee&.detach
+end

data/examples/simple_strace.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rptrace"
+
+if ARGV.empty?
+  warn "usage: bundle exec ruby examples/simple_strace.rb <command> [args...]"
+  exit 1
+end
+
+command = ARGV.shift
+
+Rptrace.strace(command, *ARGV) do |event|
+  next unless event.exit?
+
+  puts event
+end

data/examples/syscall_counter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rptrace"
+
+if ARGV.empty?
+  warn "usage: bundle exec ruby examples/syscall_counter.rb <command> [args...]"
+  exit 1
+end
+
+command = ARGV.shift
+counts = Hash.new(0)
+
+Rptrace.strace(command, *ARGV) do |event|
+  next unless event.exit?
+
+  counts[event.syscall.name] += 1
+end
+
+counts.sort_by { |(_name, count)| -count }.each do |name, count|
+  puts format("%-20s %d", name, count)
+end

data/lib/rptrace/binding.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "fiddle/import"
+
+module Rptrace
+  # Low-level libc bindings for ptrace and waitpid.
+  module Binding
+    extend Fiddle::Importer
+    include Constants
+
+    dlload Fiddle::Handle::DEFAULT
+
+    extern "long ptrace(int, int, unsigned long, unsigned long)"
+    extern "int waitpid(int, void*, int)"
+    extern "int fork()"
+    extern "int execvp(char*, void*)"
+
+    # Maps errno values to specific Rptrace error subclasses.
+    ERRNO_CLASS_MAP = {
+      Errno::EPERM::Errno => PermissionError,
+      Errno::ESRCH::Errno => NoProcessError,
+      Errno::EBUSY::Errno => BusyError,
+      Errno::EINVAL::Errno => InvalidArgError
+    }.freeze
+    # Guidance suffix appended to EPERM-related ptrace errors.
+    PERMISSION_HINT = "try running as root, granting CAP_SYS_PTRACE, and checking /proc/sys/kernel/yama/ptrace_scope".freeze
+
+    class << self
+      # Calls ptrace and raises mapped Rptrace::Error subclasses on failure.
+      #
+      # @param request [Integer, Symbol]
+      # @param pid [Integer]
+      # @param addr [Integer]
+      # @param data [Integer]
+      # @return [Integer]
+      def safe_ptrace(request, pid, addr, data)
+        clear_errno!
+        result = ptrace(request, pid, addr, data)
+        errno = Fiddle.last_error
+        return result unless result == -1 && errno.positive?
+
+        raise_ptrace_error(errno, request)
+      end
+
+      # Calls waitpid and decodes raw status.
+      #
+      # @param pid [Integer]
+      # @param flags [Integer]
+      # @return [Array<(Integer, Integer)>] waited pid and raw status
+      def safe_waitpid(pid, flags: 0)
+        status_ptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT)
+
+        loop do
+          clear_errno!
+          waited_pid = waitpid(pid, status_ptr, flags)
+          errno = Fiddle.last_error
+
+          next if waited_pid == -1 && errno == Errno::EINTR::Errno
+          raise_ptrace_error(errno, :waitpid) if waited_pid == -1
+
+          status = status_ptr[0, Fiddle::SIZEOF_INT].unpack1("i")
+          return [waited_pid, status]
+        end
+      end
+
+      # Resets thread-local errno to zero.
+      #
+      # @return [Integer]
+      def clear_errno!
+        Fiddle.last_error = 0
+      end
+
+      # Raises a mapped Rptrace::Error subclass for an errno code.
+      #
+      # @param errno [Integer]
+      # @param request [Integer, Symbol]
+      # @raise [Rptrace::Error]
+      # @return [void]
+      def raise_ptrace_error(errno, request)
+        klass = ERRNO_CLASS_MAP.fetch(errno, Error)
+        message = SystemCallError.new("ptrace", errno).message
+        message = "#{message}; #{PERMISSION_HINT}" if klass == PermissionError
+        raise klass.new(message, errno: errno, request: request)
+      end
+    end
+  end
+end

data/lib/rptrace/breakpoint.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rptrace
+  # Software breakpoint descriptor for a traced process.
+  class Breakpoint
+    attr_reader :tracee, :address, :original_byte
+
+    # @param tracee [Rptrace::Tracee]
+    # @param address [Integer]
+    # @param original_byte [String] one-byte opcode before patching
+    # @param enabled [Boolean]
+    def initialize(tracee:, address:, original_byte:, enabled: true)
+      byte = original_byte.to_s.b
+      raise ArgumentError, "original_byte must be exactly one byte" unless byte.bytesize == 1
+
+      @tracee = tracee
+      @address = Integer(address)
+      @original_byte = byte
+      @enabled = enabled
+    end
+
+    # @return [Boolean]
+    def enabled?
+      @enabled
+    end
+
+    # @return [Rptrace::Breakpoint]
+    def disable!
+      @enabled = false
+      self
+    end
+
+    # Restores original opcode through the owning tracee.
+    #
+    # @return [Rptrace::Breakpoint, nil]
+    def restore
+      tracee.remove_breakpoint(address)
+    end
+
+    # @return [String]
+    def inspect
+      state = enabled? ? "enabled" : "disabled"
+      "#<#{self.class} addr=0x#{address.to_s(16)} state=#{state}>"
+    end
+  end
+end