{"id":45758514,"url":"https://github.com/ydah/rptrace","last_synced_at":"2026-02-27T23:01:57.494Z","repository":{"id":339766365,"uuid":"1163003664","full_name":"ydah/rptrace","owner":"ydah","description":"Ruby wrapper for Linux `ptrace(2)` focused on building tracers and debugger-like tooling with a Ruby-friendly API.","archived":false,"fork":false,"pushed_at":"2026-02-21T12:11:54.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T22:23:03.288Z","etag":null,"topics":["building","debugger","linux","ptrace","ruby","tool","tracer"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ydah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T00:34:55.000Z","updated_at":"2026-02-21T12:11:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ydah/rptrace","commit_stats":null,"previous_names":["ydah/rptrace"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ydah/rptrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydah%2Frptrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydah%2Frptrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydah%2Frptrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydah%2Frptrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ydah","download_url":"https://codeload.github.com/ydah/rptrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ydah%2Frptrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29874448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T21:05:00.265Z","status":"ssl_error","status_checked_at":"2026-02-26T20:57:13.669Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["building","debugger","linux","ptrace","ruby","tool","tracer"],"created_at":"2026-02-25T21:41:02.944Z","updated_at":"2026-02-26T22:00:57.849Z","avatar_url":"https://github.com/ydah.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rptrace [![Gem Version](https://badge.fury.io/rb/rptrace.svg)](https://badge.fury.io/rb/rptrace) [![CI](https://github.com/ydah/rptrace/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/rptrace/actions/workflows/main.yml)\n\n`rptrace` is a Ruby wrapper for Linux `ptrace(2)` focused on building tracers and debugger-like tooling with a Ruby-friendly API.\n\n## Overview and Motivation\n\nLinux `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:\n\n- `strace`-like tools\n- process instrumentation utilities\n- debugger-oriented experiments\n\n## Features\n\n- Top-level namespace is `Rptrace` (no `Rptrace::Ruby` nesting)\n- `Tracee` API for `spawn`, `attach`, `cont`, `syscall`, `detach`, and `wait`\n- Register and memory wrappers (`Registers`, `Memory`)\n- `/proc/\u003cpid\u003e/maps` parser (`ProcMaps`, `Tracee#memory_maps`)\n- Software breakpoints on x86_64 (`Tracee#set_breakpoint`, `remove_breakpoint`)\n- Syscall lookup (`Rptrace::Syscall`) for `x86_64`/`aarch64`\n- High-level tracing helper `Rptrace.strace` (`follow_children` / `yield_seccomp` supported)\n- ptrace event helpers (`Tracee#event_message`, `Tracee#seccomp_data`, `Tracee#seccomp_metadata`, `Tracee#seccomp_filter`)\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"rptrace\"\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\n## Quick Start\n\n```ruby\nrequire \"rptrace\"\n\nRptrace.strace(\"/bin/ls\", \"-la\", \"/tmp\") do |event|\n  next unless event.exit?\n\n  puts event\nend\n```\n\nFollow child processes/threads (clone/fork/vfork):\n\n```ruby\nRptrace.strace(\"/usr/bin/ruby\", \"-e\", \"pid = fork { sleep 0.1 }; Process.wait(pid)\", follow_children: true) do |event|\n  next unless event.enter?\n  puts \"pid=#{event.tracee.pid} #{event.syscall.name}\"\nend\n```\n\nInclude seccomp stop events in trace stream:\n\n```ruby\nRptrace.strace(\"/bin/ls\", \"/tmp\", yield_seccomp: true) do |event|\n  case event\n  when Rptrace::SyscallEvent\n    puts event if event.exit?\n  when Rptrace::SeccompEvent\n    warn event.to_s\n  end\nend\n```\n\nSet and clear a software breakpoint (x86_64):\n\n```ruby\ntracee = Rptrace::Tracee.attach(target_pid)\nbp = tracee.set_breakpoint(0x401000)\n# ...\nbp.restore\n```\n\nInspect seccomp filter metadata and decoded BPF instructions:\n\n```ruby\ntracee = Rptrace::Tracee.attach(target_pid)\ntracee.enable_seccomp_events!\nsupported = tracee.seccomp_supported?\navailable = tracee.seccomp_filter_available?(index: 0)\nmeta = tracee.seccomp_metadata(index: 0) # =\u003e { filter_off: 0, flags: ... }\nflag_names = tracee.seccomp_metadata_flag_names(index: 0) # =\u003e [:tsync, :log, ...]\ninsns = tracee.seccomp_filter(index: 0)  # =\u003e [{ code:, jt:, jf:, k: }, ...]\n```\n\n## Permission Guide\n\n`ptrace` requires privilege on Linux:\n\n- run as `root`, or\n- run with `CAP_SYS_PTRACE`, and\n- ensure Yama policy allows tracing (`/proc/sys/kernel/yama/ptrace_scope`)\n\nIntegration specs are opt-in and require:\n\n```bash\nPTRACE_RUN_INTEGRATION=1 bundle exec rspec spec/integration\n```\n\nYou can inspect local ptrace capability setup from Ruby:\n\n```ruby\ndiagnostics = Rptrace.ptrace_permissions\nputs diagnostics # =\u003e { ptrace_privileged:, cap_sys_ptrace:, yama_ptrace_scope:, hints: [...] }\n```\n\nFail fast with an actionable permission error:\n\n```ruby\nRptrace.ensure_ptrace_privileged!(request: :attach)\n```\n\n## Examples\n\n- `examples/simple_strace.rb`\n- `examples/syscall_counter.rb`\n- `examples/file_access_tracer.rb`\n- `examples/memory_reader.rb`\n\n## API Reference\n\n- Generate docs: `bundle exec yard doc`\n- Open index: `doc/index.html`\n\n## Development\n\n```bash\nbundle exec rspec\n```\n\nRun specs with coverage threshold check:\n\n```bash\nCOVERAGE=1 COVERAGE_MIN_LINE=95 bundle exec rspec spec/unit spec/rptrace_spec.rb\n```\n\nGenerate syscall tables from Linux headers (`x86_64` / `aarch64`):\n\n```bash\nbundle exec rake syscall:generate\n```\n\nYou can override header paths with:\n\n- `PTRACE_SYSCALL_HEADER_X86_64`\n- `PTRACE_SYSCALL_HEADER_AARCH64`\n\nOptional task controls:\n\n- `ARCH=x86_64` (or `ARCH=x86_64,aarch64`) to limit architectures\n- `STRICT=1` to fail if any requested architecture header is missing\n\nGenerate YARD documentation:\n\n```bash\nbundle exec yard doc\n```\n\n## Release\n\n- CI release workflow: `.github/workflows/release.yml`\n- Trigger by pushing a tag (example: `v0.1.0`) or via `workflow_dispatch`\n- Set repository secret `RUBYGEMS_API_KEY` to enable `gem push`\n- Local preflight: `bundle exec rake release:preflight`\n- Local credential check: `bundle exec rake release:check_credentials`\n\n## Limitations\n\n- Linux only\n- Ruby 3.1+\n- Architecture support: `x86_64` and `aarch64`\n- Integration tests require ptrace permission (`root` or `CAP_SYS_PTRACE`)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydah%2Frptrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fydah%2Frptrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fydah%2Frptrace/lists"}