seccomp-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40f614938f158e9d50bae1663c7a70e706e90e3708c40aad4fe104f51c7e580b
+  data.tar.gz: b31a0b00fe82b56887508fdd4d7d87e7fdcb71de4f5751f7d783b1ab5126786d
+SHA512:
+  metadata.gz: 0a44ae3091f60578544fa965c9ab93f52c29d8e0294fc115cd010028a55d62b4f8e72078413c951ee9116757f3a9720357ba9c6b5b596f4a901044daf888fa46
+  data.tar.gz: 0beda9a0f882861e3941cdff169695d951a132a4ad54a360e1f104e4a33b7fc12192888890ca17dc0feebeb83fdf0a16e8fd503233863615d01051ce2f93eb05

data/.rubocop.yml

@@ -0,0 +1,43 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/ClassLength:
+  Max: 250
+
+Metrics/MethodLength:
+  Max: 30
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Metrics/AbcSize:
+  Exclude:
+    - "spec/support/**/*"
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - fd
+    - id
+    - io
+    - op
+    - val
+
+Security/MarshalLoad:
+  Exclude:
+    - "spec/live/**/*"

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--no-private
+lib/**/*.rb

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,132 @@
+# seccomp-ruby
+
+Native CRuby bindings for [libseccomp](https://github.com/seccomp/libseccomp). The gem exposes
+the C API through `Seccomp::LowLevel` and a Ruby-friendly filter, argument DSL, transaction, and
+user-notification API.
+
+> [!WARNING]
+> A loaded seccomp filter cannot be removed or relaxed before the process exits. Ruby itself uses
+> many system calls; an incomplete allowlist can crash the VM immediately. Always validate a filter
+> in a forked child process before using it in production.
+
+## Requirements
+
+- Linux and CRuby 3.1 or newer
+- libseccomp 2.5 or newer and its development headers
+- A C compiler
+
+On Debian or Ubuntu:
+
+```sh
+sudo apt-get install libseccomp-dev build-essential
+bundle install
+bundle exec rake compile
+```
+
+The gem name is currently `seccomp-ruby`:
+
+```ruby
+gem "seccomp-ruby"
+```
+
+## Quick start
+
+Construct and inspect filters in the parent process, but load them only after `fork`:
+
+```ruby
+require "libseccomp"
+
+filter = Seccomp.filter(default: :kill_process) do
+  no_new_privs true
+  deny :ptrace, errno: Errno::EPERM
+  allow :read, :write, :exit, :exit_group, :rt_sigreturn
+end
+
+puts filter.to_pfc
+pid = fork do
+  filter.load!
+  # Run sandboxed work here.
+  Process.exit!(0)
+end
+Process.waitpid(pid)
+filter.close
+```
+
+Argument comparisons use explicit keywords for masked equality:
+
+```ruby
+filter.allow(:openat, filter.arg(2).masked_eq(mask: 0o3, value: 0))
+filter.deny(:close, filter.arg(0).eq(2), errno: Errno::EBADF)
+```
+
+Use `Seccomp.supports?` before calling optional APIs. It checks both compile-time availability and
+the runtime API level where applicable:
+
+```ruby
+filter.transaction { filter.allow(:read) } if Seccomp.supports?(:transaction)
+filter.precompute if Seccomp.supports?(:precompute)
+notification.add_fd(file) if Seccomp.supports?(:notify_addfd)
+```
+
+## User notifications
+
+`Seccomp::Notifier#receive` integrates with Ruby IO waiting and accepts a timeout. Notification
+errors use normal positive errno values at the Ruby boundary:
+
+```ruby
+notification.deny(Errno::EPERM) # converted to the kernel's negative errno convention
+notification.respond(error: Errno::EPERM) # direct responses use the same conversion
+notification.continue!
+```
+
+> [!CAUTION]
+> Notification arguments may contain pointers into another process. If you read through
+> `/proc/<pid>/mem`, call `notification.valid?` again after reading and before responding. This
+> reduces, but cannot eliminate, time-of-check/time-of-use races. `continue!` must only be used when
+> the target syscall is safe to execute with its current arguments.
+
+libseccomp keeps one notification listener in process-global state. Closing its `Notifier` or
+owning `Filter` closes and resets that listener. A second notification filter is rejected while
+the listener is active; use one notification supervisor per process.
+
+> [!WARNING]
+> A loaded notification filter must allow `close(2)` while its listener is being released. A rule
+> that denies or kills `close(2)` can leave the listener open, and a notification rule for
+> `close(2)` requires a supervisor to answer during cleanup. This cannot be repaired after the
+> irreversible filter is loaded; keep the supervisor running or end the sandbox with
+> `Process.exit!`.
+
+If file descriptor 0 is closed when a notification filter is loaded, the gem reserves it with
+`/dev/null` and keeps it open after a successful load; closing it afterward could itself be blocked
+by the irreversible filter. Filters without notification actions leave file descriptor 0 unchanged.
+If a notification load fails after an earlier filter was loaded, the reservation is kept rather than
+risk an internal `close(2)` being intercepted. Rolling back a transaction that added a notification
+rule requires `Filter#reset` or a new notification rule before loading that filter, due to native
+libseccomp state retained by the rejected transaction.
+
+## Thread and architecture notes
+
+- `tsync` applies a filter to every thread. Ruby VM threads require syscalls such as `futex`,
+  `rt_sigprocmask`, and `membarrier`; blocking them may terminate or deadlock the VM.
+- `width: 32` masks comparison values to 32 bits. On 32-bit ABIs, upper halves of 64-bit syscall
+  arguments may not be meaningful.
+- x32 and x86_64 are distinct architecture tokens.
+- `Seccomp.api_level=` changes process-global libseccomp state and should be used once at startup.
+
+## Development
+
+```sh
+bundle exec rake compile
+bundle exec rake spec:unit
+bundle exec rake spec:live # all load! calls are fork-isolated
+bundle exec rubocop
+bundle exec rbs validate
+bundle exec yard stats --list-undoc
+```
+
+The live suite must run on Linux. In a container, use `--security-opt seccomp=unconfined`.
+
+## License
+
+This project retains its existing MIT license. It dynamically links to libseccomp, which is
+licensed under LGPL-2.1.

data/Rakefile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/extensiontask"
+require "rspec/core/rake_task"
+
+Rake::ExtensionTask.new("seccomp_ext")
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "spec/{unit,live}/**/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new("spec:unit") do |task|
+  task.pattern = "spec/unit/**/*_spec.rb"
+end
+
+RSpec::Core::RakeTask.new("spec:live") do |task|
+  task.pattern = "spec/live/**/*_spec.rb"
+end
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "bundle exec rbs validate"
+end
+
+desc "Report API documentation coverage"
+task :yard do
+  sh "bundle exec yard stats --list-undoc"
+end
+
+task default: %i[compile spec rubocop]

data/examples/arg_filter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# WARNING: load! is irreversible. This example loads only in a forked child.
+require "libseccomp"
+
+pid = fork do
+  filter = Seccomp::Filter.new(:allow)
+  filter.deny(:write, filter.arg(0).eq($stdout.fileno), errno: Errno::EPERM)
+  filter.load!
+  begin
+    $stdout.syswrite("blocked\n")
+  rescue Errno::EPERM
+    $stderr.syswrite("writes to stdout are blocked\n")
+  end
+  Process.exit!(0)
+end
+_, status = Process.waitpid2(pid)
+abort "sandbox child failed" unless status.success?

data/examples/basic_allowlist.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# WARNING: load! is irreversible. This example loads only in a forked child.
+require "libseccomp"
+
+required = %i[
+  read write close exit exit_group rt_sigreturn rt_sigaction rt_sigprocmask futex mmap munmap
+  mprotect madvise brk clock_gettime getpid gettid sigaltstack fstat newfstatat getrandom
+]
+filter = Seccomp::Filter.new(:kill_process)
+required.each { |syscall| filter.allow(syscall) }
+
+pid = fork do
+  filter.load!
+  $stdout.syswrite("sandbox active\n")
+  Process.exit!(0)
+end
+_, status = Process.waitpid2(pid)
+filter.close
+abort "sandbox child failed" unless status.success?

data/examples/errno_filter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# WARNING: load! is irreversible. This example loads only in a forked child.
+require "libseccomp"
+
+pid = fork do
+  filter = Seccomp::Filter.new(:allow)
+  filter.deny(:openat, errno: Errno::EPERM)
+  filter.load!
+  begin
+    File.read("/etc/hostname")
+  rescue Errno::EPERM
+    $stdout.syswrite("openat denied with EPERM\n")
+  end
+  Process.exit!(0)
+end
+_, status = Process.waitpid2(pid)
+abort "sandbox child failed" unless status.success?

data/examples/notify_supervisor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# WARNING: load! is irreversible. This example loads only in a forked child.
+# Pointer arguments must be read before valid? is rechecked to reduce TOCTOU risk.
+require "fiddle"
+require "libseccomp"
+
+pid = fork do
+  queue = Queue.new
+  supervisor = Thread.new do
+    notification = queue.pop.receive(timeout: 5)
+    notification.valid? ? notification.continue! : nil
+  end
+  filter = Seccomp::Filter.new(:allow)
+  filter.notify(:getppid)
+  filter.load!
+  queue << filter.notifier
+
+  syscall = Fiddle::Function.new(Fiddle::Handle::DEFAULT["syscall"],
+                                 [Fiddle::TYPE_LONG], Fiddle::TYPE_LONG)
+  syscall.call(Seccomp::Syscall.number(:getppid))
+  supervisor.join
+  Process.exit!(0)
+end
+_, status = Process.waitpid2(pid)
+abort "sandbox child failed" unless status.success?

data/ext/seccomp_ext/const.c

@@ -0,0 +1,133 @@
+#include "seccomp_ext.h"
+
+#define CONST(module, name, value) rb_define_const((module), (name), seccomp_ext_uint32(value))
+
+void
+seccomp_ext_init_constants(void)
+{
+    VALUE action = rb_define_module_under(mSeccomp, "Action");
+    VALUE arch = rb_define_module_under(mSeccomp, "Arch");
+    VALUE compare = rb_define_module_under(mSeccomp, "Compare");
+    VALUE attribute = rb_define_module_under(mSeccomp, "FilterAttr");
+
+    CONST(action, "KILL_PROCESS", SCMP_ACT_KILL_PROCESS);
+    CONST(action, "KILL_THREAD", SCMP_ACT_KILL_THREAD);
+    CONST(action, "KILL", SCMP_ACT_KILL);
+    CONST(action, "TRAP", SCMP_ACT_TRAP);
+    CONST(action, "NOTIFY", SCMP_ACT_NOTIFY);
+    CONST(action, "LOG", SCMP_ACT_LOG);
+    CONST(action, "ALLOW", SCMP_ACT_ALLOW);
+#ifdef HAVE_SCMP_ACT_TRAPX
+    CONST(action, "TRAPX", SCMP_ACT_TRAPX(0));
+#endif
+
+#ifdef SCMP_ARCH_NATIVE
+    CONST(arch, "NATIVE", SCMP_ARCH_NATIVE);
+#endif
+#ifdef SCMP_ARCH_X86
+    CONST(arch, "X86", SCMP_ARCH_X86);
+#endif
+#ifdef SCMP_ARCH_X86_64
+    CONST(arch, "X86_64", SCMP_ARCH_X86_64);
+#endif
+#ifdef SCMP_ARCH_X32
+    CONST(arch, "X32", SCMP_ARCH_X32);
+#endif
+#ifdef SCMP_ARCH_ARM
+    CONST(arch, "ARM", SCMP_ARCH_ARM);
+#endif
+#ifdef SCMP_ARCH_AARCH64
+    CONST(arch, "AARCH64", SCMP_ARCH_AARCH64);
+#endif
+#ifdef SCMP_ARCH_LOONGARCH64
+    CONST(arch, "LOONGARCH64", SCMP_ARCH_LOONGARCH64);
+#endif
+#ifdef SCMP_ARCH_M68K
+    CONST(arch, "M68K", SCMP_ARCH_M68K);
+#endif
+#ifdef SCMP_ARCH_MIPS
+    CONST(arch, "MIPS", SCMP_ARCH_MIPS);
+#endif
+#ifdef SCMP_ARCH_MIPS64
+    CONST(arch, "MIPS64", SCMP_ARCH_MIPS64);
+#endif
+#ifdef SCMP_ARCH_MIPS64N32
+    CONST(arch, "MIPS64N32", SCMP_ARCH_MIPS64N32);
+#endif
+#ifdef SCMP_ARCH_MIPSEL
+    CONST(arch, "MIPSEL", SCMP_ARCH_MIPSEL);
+#endif
+#ifdef SCMP_ARCH_MIPSEL64
+    CONST(arch, "MIPSEL64", SCMP_ARCH_MIPSEL64);
+#endif
+#ifdef SCMP_ARCH_MIPSEL64N32
+    CONST(arch, "MIPSEL64N32", SCMP_ARCH_MIPSEL64N32);
+#endif
+#ifdef SCMP_ARCH_PPC
+    CONST(arch, "PPC", SCMP_ARCH_PPC);
+#endif
+#ifdef SCMP_ARCH_PPC64
+    CONST(arch, "PPC64", SCMP_ARCH_PPC64);
+#endif
+#ifdef SCMP_ARCH_PPC64LE
+    CONST(arch, "PPC64LE", SCMP_ARCH_PPC64LE);
+#endif
+#ifdef SCMP_ARCH_S390
+    CONST(arch, "S390", SCMP_ARCH_S390);
+#endif
+#ifdef SCMP_ARCH_S390X
+    CONST(arch, "S390X", SCMP_ARCH_S390X);
+#endif
+#ifdef SCMP_ARCH_PARISC
+    CONST(arch, "PARISC", SCMP_ARCH_PARISC);
+#endif
+#ifdef SCMP_ARCH_PARISC64
+    CONST(arch, "PARISC64", SCMP_ARCH_PARISC64);
+#endif
+#ifdef SCMP_ARCH_RISCV64
+    CONST(arch, "RISCV64", SCMP_ARCH_RISCV64);
+#endif
+#ifdef SCMP_ARCH_SH
+    CONST(arch, "SH", SCMP_ARCH_SH);
+#endif
+#ifdef SCMP_ARCH_SHEB
+    CONST(arch, "SHEB", SCMP_ARCH_SHEB);
+#endif
+
+    CONST(compare, "NE", SCMP_CMP_NE);
+    CONST(compare, "LT", SCMP_CMP_LT);
+    CONST(compare, "LE", SCMP_CMP_LE);
+    CONST(compare, "EQ", SCMP_CMP_EQ);
+    CONST(compare, "GE", SCMP_CMP_GE);
+    CONST(compare, "GT", SCMP_CMP_GT);
+    CONST(compare, "MASKED_EQ", SCMP_CMP_MASKED_EQ);
+
+    CONST(attribute, "ACT_DEFAULT", SCMP_FLTATR_ACT_DEFAULT);
+    CONST(attribute, "ACT_BADARCH", SCMP_FLTATR_ACT_BADARCH);
+    CONST(attribute, "CTL_NNP", SCMP_FLTATR_CTL_NNP);
+    CONST(attribute, "CTL_TSYNC", SCMP_FLTATR_CTL_TSYNC);
+    CONST(attribute, "API_TSKIP", SCMP_FLTATR_API_TSKIP);
+    CONST(attribute, "CTL_LOG", SCMP_FLTATR_CTL_LOG);
+    CONST(attribute, "CTL_SSB", SCMP_FLTATR_CTL_SSB);
+#ifdef HAVE_CONST_SCMP_FLTATR_CTL_OPTIMIZE
+    CONST(attribute, "CTL_OPTIMIZE", SCMP_FLTATR_CTL_OPTIMIZE);
+#endif
+#ifdef HAVE_CONST_SCMP_FLTATR_API_SYSRAWRC
+    CONST(attribute, "API_SYSRAWRC", SCMP_FLTATR_API_SYSRAWRC);
+#endif
+#ifdef HAVE_CONST_SCMP_FLTATR_CTL_WAITKILL
+    CONST(attribute, "CTL_WAITKILL", SCMP_FLTATR_CTL_WAITKILL);
+#endif
+
+    rb_define_const(mSeccompLowLevel, "NR_SCMP_ERROR", INT2NUM(__NR_SCMP_ERROR));
+    rb_define_const(mSeccompLowLevel, "NR_SCMP_UNDEF", INT2NUM(__NR_SCMP_UNDEF));
+#ifdef SECCOMP_USER_NOTIF_FLAG_CONTINUE
+    CONST(mSeccompLowLevel, "USER_NOTIF_FLAG_CONTINUE", SECCOMP_USER_NOTIF_FLAG_CONTINUE);
+#endif
+#ifdef SECCOMP_ADDFD_FLAG_SETFD
+    CONST(mSeccompLowLevel, "ADDFD_FLAG_SETFD", SECCOMP_ADDFD_FLAG_SETFD);
+#endif
+#ifdef SECCOMP_ADDFD_FLAG_SEND
+    CONST(mSeccompLowLevel, "ADDFD_FLAG_SEND", SECCOMP_ADDFD_FLAG_SEND);
+#endif
+}

data/ext/seccomp_ext/extconf.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+abort "libseccomp is Linux-only" unless RUBY_PLATFORM.include?("linux")
+abort "seccomp.h is required" unless have_header("seccomp.h")
+abort "libseccomp is required" unless have_library("seccomp", "seccomp_init")
+abort "libseccomp >= 2.5 is required" unless have_func("seccomp_notify_alloc", "seccomp.h")
+
+%w[
+  seccomp_notify_addfd
+  seccomp_transaction_start
+  seccomp_transaction_commit
+  seccomp_transaction_reject
+  seccomp_precompute
+  seccomp_export_bpf_mem
+].each { |function| have_func(function, "seccomp.h") }
+
+if have_macro("SECCOMP_IOCTL_NOTIF_ADDFD", %w[seccomp.h sys/ioctl.h])
+  # mkmf exposes extra compiler definitions through this global.
+  # rubocop:disable-next Style/GlobalVars
+  $defs << "-DHAVE_SECCOMP_IOCTL_NOTIF_ADDFD"
+end
+
+%w[
+  SCMP_ACT_TRAPX
+  SCMP_ARCH_LOONGARCH64
+  SCMP_ARCH_M68K
+  SCMP_ARCH_SH
+  SCMP_ARCH_SHEB
+  SCMP_ARCH_RISCV64
+].each do |macro|
+  # mkmf exposes extra compiler definitions through this global.
+  # rubocop:disable-next Style/GlobalVars
+  $defs << "-DHAVE_#{macro}" if have_macro(macro, "seccomp.h")
+end
+
+%w[
+  SCMP_FLTATR_CTL_WAITKILL
+  SCMP_FLTATR_API_SYSRAWRC
+  SCMP_FLTATR_CTL_OPTIMIZE
+].each { |constant| have_const(constant, "seccomp.h") }
+
+have_struct_member("struct seccomp_notif_addfd", "newfd_flags", "seccomp.h")
+create_makefile("seccomp_ext")