landlock 0.4.1 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06c677a70d7c9573f8900255447f3407b917a32d20b431ddf3639660ae410847
-  data.tar.gz: 07a99cefc054bbc33693f9d72531ef2639e8b926895de8f5972cd62a40974413
+  metadata.gz: 5bfc5c69234e004834818ba52aab192c9219ff0a398d40ada62c4f45be461cdb
+  data.tar.gz: 6ec4b746a959a8f68c5ba11e1c4b7342d0a4facda031a8627f05ae6fedc6c6cf
 SHA512:
-  metadata.gz: 44ff2dd41500ebfb8751aca02d09582a92a9cbcc5abce973f53ce1981fe579afde5bfe63b739c032404e874654de414ca13c17581a2ec51a34fe9e20c708105f
-  data.tar.gz: d98885b52ebe803ee29d3d5db0ee83ba44417377ddd7f9f6ce47b41576be326b5246b62ebfbd47723f79ae3d3be7c5608916816c86264e6832e7f1bfb515d793
+  metadata.gz: efd09558eb3b207ca4be70d4a6509b39338f9cc6374f6422a0fbeee87f2fb8fbb99dd4095044a27f94355062da6016672719a64ab3af78d8d89f622b3b0bb64b
+  data.tar.gz: f7e6d2ebf580fd200fa05217d3266f4a48e93d226757e4a3d9c409d22a844c3f6245fb81956201a4b03c3b8ced3ddd29c169653367efa007a8cd1c71bc833048

data/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## [0.5] - 2026-09-01
+
+### Added
+
+- Add `Landlock.fork` for running a sandboxed Ruby block in a supervised forked child.
+
 ## [0.4.1] - 2026-08-20
 
 ### Fixed

data/README.md

@@ -135,6 +135,42 @@ Capture options:
 - `success_status_codes:` and `failure_message:` — `capture!` failure handling options.
 - `allow_all_known:` — when filesystem rules are present, handle all Landlock filesystem rights known to the running ABI so unlisted filesystem access is denied.
 
+## Forking a Ruby block
+
+`Landlock.fork` is a supervised, synchronous fork. It forks the current Ruby process, applies the requested restrictions in the child, runs the block there, waits for it, and returns a `Landlock::CaptureResult`. It is intended for applications that need to reuse initialized Ruby state without executing a new command:
+
+```ruby
+result = Landlock.fork(
+  read: [input_path],
+  timeout: 5,
+  rlimits: { cpu_seconds: 5, memory_bytes: 512 * 1024 * 1024 },
+  seccomp_deny_network: true
+) do |stdout, _stderr|
+  stdout.write(calculate_dominant_color(input_path))
+end
+
+color = result.stdout if result.success?
+```
+
+The block receives its child-side stdout and stderr streams. Write response data to stdout and diagnostics to stderr, then inspect them through the capture result in the parent. The block's return value is discarded. An exception makes the child exit with status 1 and writes a diagnostic to stderr. `fork` accepts the capture options listed above except `success_status_codes:` and `failure_message:`, which only apply to `capture!`.
+
+By default, `Landlock.fork` requires Linux Landlock support and raises `Landlock::UnsupportedError` before forking when the Landlock ABI is unavailable. A Linux caller that explicitly accepts running without Landlock filesystem, TCP, and scope enforcement can opt in to the fallback:
+
+```ruby
+result = Landlock.fork(
+  on_unsupported: :run_without_landlock,
+  timeout: 5,
+  rlimits: { memory_bytes: 512 * 1024 * 1024 },
+  seccomp_deny_network: true
+) { |stdout, _stderr| stdout.write(run_plugin) }
+```
+
+This fallback is used only when the Linux kernel has no Landlock ABI. It skips only Landlock policy enforcement; fork supervision, timeout handling, environment changes, descriptor closing, rlimits, output capture, and seccomp remain active. It is never selected implicitly, and non-Linux systems still raise `Landlock::UnsupportedError`. When fallback is active, the call must include `seccomp_deny_network: true` or at least one `rlimits:` entry because Landlock rules are not effective restrictions in that mode. Timeout, environment handling, descriptor closing, and output limits do not satisfy this requirement. `Landlock.fork` requires an actual restriction. By default, the child closes inherited Ruby `IO` objects other than stdin, stdout, and stderr, then closes every other application descriptor numbered 3 or higher while preserving Ruby VM-reserved descriptors. It enumerates `/proc/self/fd` for this sweep and fails closed with setup status 127 if enumeration is unavailable or fails. Pass `close_others: false` only when the child intentionally needs an inherited descriptor. Child setup failures exit 127.
+
+The worker is a process-group leader and reserves Linux real-time signal `SIGRTMIN+2` for parent-death handling while the block runs. If the Ruby thread supervising the synchronous `Landlock.fork` call terminates, a native signal handler sends `SIGKILL` to the worker's process group. This terminates the worker and ordinary descendants that remain in that group. It does not cover descendants that create another process group or session, and the group-wide guarantee can be disabled by code that replaces or blocks the reserved signal, clears the parent-death signal, changes credentials in a way that clears it, or replaces the worker with `exec`. After `exec`, the reserved signal still terminates the worker by default, but the reset handler no longer kills its process group. This is process-lifecycle hardening, not a cgroup, PID namespace, or hostile-process containment boundary.
+
+Fork only from a process whose loaded libraries and runtime state are safe to use after `fork`. `Landlock.fork` cannot make an unsafe parent fork-safe, and the block must not depend on threads that exist only in the parent.
+
 ## Restrict current process
 
 This is irreversible for the current thread and its future children. Use `Landlock.exec` or `Landlock.spawn` unless you really mean it.

data/ext/landlock/landlock.c

@@ -2,8 +2,14 @@
 #include "landlock_native.h"
 #include "seccomp_deny_network.h"
 
+#include <signal.h>
 #include <string.h>
 
+#ifdef __linux__
+#include <dirent.h>
+#include <stdlib.h>
+#endif
+
 static VALUE mLandlock;
 static VALUE eLandlockError;
 static VALUE eSyscallError;
@@ -121,6 +127,49 @@ static VALUE rb_ll_close_fd(VALUE self, VALUE fd_value) {
   return Qnil;
 }
 
+static VALUE rb_ll_close_inherited_fds(VALUE self) {
+  /* The forked child keeps running Ruby, so interpreter-reserved descriptors
+   * must survive. This rules out close_range across the entire descriptor table. */
+#ifdef __linux__
+  DIR *dir = opendir("/proc/self/fd");
+  if (!dir) {
+    raise_syscall_error("opendir(/proc/self/fd)");
+  }
+
+  int dir_fd = dirfd(dir);
+  struct dirent *entry;
+  for (;;) {
+    errno = 0;
+    entry = readdir(dir);
+    if (!entry) {
+      if (errno != 0) {
+        int saved_errno = errno;
+        closedir(dir);
+        errno = saved_errno;
+        raise_syscall_error("readdir(/proc/self/fd)");
+      }
+      break;
+    }
+
+    char *end = NULL;
+    errno = 0;
+    long fd = strtol(entry->d_name, &end, 10);
+    if (errno == 0 && end && *end == '\0' && fd >= 3 && fd != dir_fd &&
+        !rb_reserved_fd_p((int)fd)) {
+      close((int)fd);
+    }
+  }
+  if (closedir(dir) != 0) {
+    raise_syscall_error("closedir(/proc/self/fd)");
+  }
+  return Qtrue;
+#else
+  errno = ENOSYS;
+  raise_syscall_error("opendir(/proc/self/fd)");
+  return Qnil;
+#endif
+}
+
 static VALUE rb_ll_pidfd_open(VALUE self, VALUE pid_value) {
 #ifdef SYS_pidfd_open
   int fd = syscall(SYS_pidfd_open, NUM2PIDT(pid_value), 0);
@@ -135,6 +184,62 @@ static VALUE rb_ll_pidfd_open(VALUE self, VALUE pid_value) {
 #endif
 }
 
+/* Runs after the worker has become its own process-group leader. */
+static void terminate_own_process_group(int signal_number) {
+  (void)signal_number;
+  kill(0, SIGKILL);
+  _exit(0);
+}
+
+static VALUE rb_ll_arm_parent_death_process_group(VALUE self, VALUE parent_pid_value) {
+#ifdef __linux__
+  pid_t parent_pid = NUM2PIDT(parent_pid_value);
+  /* Leave the first two application-visible realtime signals available to callers. */
+  int parent_death_signal = SIGRTMIN + 2;
+
+  struct sigaction action;
+  memset(&action, 0, sizeof(action));
+  action.sa_handler = terminate_own_process_group;
+  sigemptyset(&action.sa_mask);
+  if (sigaction(parent_death_signal, &action, NULL) != 0) {
+    raise_syscall_error("sigaction(parent death process group)");
+  }
+
+  sigset_t signals;
+  sigemptyset(&signals);
+  sigaddset(&signals, parent_death_signal);
+  if (sigprocmask(SIG_UNBLOCK, &signals, NULL) != 0) {
+    raise_syscall_error("sigprocmask(parent death process group)");
+  }
+
+  if (prctl(PR_SET_PDEATHSIG, parent_death_signal) != 0) {
+    raise_syscall_error("prctl(PR_SET_PDEATHSIG)");
+  }
+
+  if (getppid() != parent_pid) {
+    terminate_own_process_group(parent_death_signal);
+  }
+
+  return Qtrue;
+#else
+  errno = ENOSYS;
+  raise_syscall_error("parent death process group");
+  return Qnil;
+#endif
+}
+
+static VALUE rb_ll_set_parent_death_signal(VALUE self) {
+#ifdef __linux__
+  if (prctl(PR_SET_PDEATHSIG, SIGKILL) != 0) {
+    raise_syscall_error("prctl(PR_SET_PDEATHSIG)");
+  }
+  return Qtrue;
+#else
+  errno = ENOSYS;
+  raise_syscall_error("prctl(PR_SET_PDEATHSIG)");
+#endif
+}
+
 static VALUE rb_ll_seccomp_deny_network(VALUE self) {
   const char *error_message = "seccomp(SECCOMP_SET_MODE_FILTER)";
   if (rb_landlock_seccomp_deny_network(&error_message) != 0) {
@@ -164,7 +269,12 @@ void Init_landlock(void) {
   rb_define_singleton_method(mLandlock, "_add_net_rule", rb_ll_add_net_rule, 3);
   rb_define_singleton_method(mLandlock, "_restrict_self", rb_ll_restrict_self, 1);
   rb_define_singleton_method(mLandlock, "_close_fd", rb_ll_close_fd, 1);
+  rb_define_singleton_method(mLandlock, "_close_inherited_fds", rb_ll_close_inherited_fds, 0);
   rb_define_singleton_method(mLandlock, "_pidfd_open", rb_ll_pidfd_open, 1);
+  rb_define_singleton_method(mLandlock, "_arm_parent_death_process_group",
+                             rb_ll_arm_parent_death_process_group, 1);
+  rb_define_singleton_method(mLandlock, "_set_parent_death_signal", rb_ll_set_parent_death_signal,
+                             0);
   rb_define_singleton_method(mLandlock, "seccomp_deny_network!", rb_ll_seccomp_deny_network, 0);
 
   rb_define_const(mLandlock, "ACCESS_FS_EXECUTE", ULL2NUM(LANDLOCK_ACCESS_FS_EXECUTE));

data/lib/landlock/execution.rb

@@ -80,6 +80,36 @@ module Landlock
       capture_with(argv, raise_on_failure: true, **options)
     end
 
+    def fork(on_unsupported: :raise, **options, &block)
+      raise ArgumentError, "fork requires a block" if !block
+      if !%i[raise run_without_landlock].include?(on_unsupported)
+        raise ArgumentError, "on_unsupported must be :raise or :run_without_landlock"
+      end
+
+      enforce_landlock = Native.abi_version.positive?
+      if !enforce_landlock && (on_unsupported == :raise || !RUBY_PLATFORM.include?("linux"))
+        raise UnsupportedError, "Linux Landlock is unavailable"
+      end
+
+      capture_options = prepare_capture_options(**options, require_landlock: enforce_landlock)
+      validate_fallback_restriction!(**capture_options) if !enforce_landlock
+
+      Runner::Fork.call_block(
+        **capture_options,
+        enforce_landlock:,
+        &block
+      )
+    rescue OutputTooLargeError => error
+      result = error.result
+      raise CommandError.new(
+              error.message,
+              stdout: result&.stdout.to_s,
+              stderr: result&.stderr.to_s,
+              status: result&.status,
+              result:
+            )
+    end
+
     def capture_with(
       argv,
       read: nil,
@@ -105,31 +135,30 @@ module Landlock
       raise_on_failure:
     )
       argv = Validation.normalize_argv(argv).map(&:to_s)
-      ensure_landlock_supported!
-      max_output_bytes = Validation.validate_output_limit!(max_output_bytes)
-      timeout = Validation.validate_timeout!(timeout)
-      normalized_rlimits = Rlimits.normalize(rlimits)
-      env = Env.normalize(env)
-      policy =
-        prepare_policy(read:, write:, execute:, connect_tcp:, bind_tcp:, paths:, scope:, chdir:, allow_all_known:)
-      validate_capture_restriction!(**policy, seccomp_deny_network:, rlimits: normalized_rlimits)
-
-      result =
-        call_with_runner(
-          argv,
-          **policy,
+      options =
+        prepare_capture_options(
+          read:,
+          write:,
+          execute:,
+          connect_tcp:,
+          bind_tcp:,
+          paths:,
+          scope:,
           chdir:,
           env:,
           unsetenv_others:,
           close_others:,
+          allow_all_known:,
           timeout:,
           stdin:,
-          rlimits: normalized_rlimits,
+          rlimits:,
           seccomp_deny_network:,
           max_output_bytes:,
           truncate_output:
         )
 
+      result = call_with_runner(argv, **options)
+
       if raise_on_failure &&
            (result.timed_out? || !result.status.exited? || !success_status_codes.include?(result.status.exitstatus))
         message = [argv.join(" "), failure_message, result.stderr].filter { |part| part.to_s != "" }.join("\n")
@@ -149,6 +178,51 @@ module Landlock
             )
     end
 
+    def prepare_capture_options(
+      read: nil,
+      write: nil,
+      execute: nil,
+      connect_tcp: nil,
+      bind_tcp: nil,
+      paths: nil,
+      scope: nil,
+      chdir: nil,
+      env: nil,
+      unsetenv_others: false,
+      close_others: true,
+      allow_all_known: false,
+      timeout: nil,
+      stdin: nil,
+      rlimits: {},
+      seccomp_deny_network: false,
+      max_output_bytes: nil,
+      truncate_output: false,
+      require_landlock: true
+    )
+      ensure_landlock_supported! if require_landlock
+      max_output_bytes = Validation.validate_output_limit!(max_output_bytes)
+      timeout = Validation.validate_timeout!(timeout)
+      rlimits = Rlimits.normalize(rlimits)
+      env = Env.normalize(env)
+      policy =
+        prepare_policy(read:, write:, execute:, connect_tcp:, bind_tcp:, paths:, scope:, chdir:, allow_all_known:)
+      validate_capture_restriction!(**policy, seccomp_deny_network:, rlimits:)
+
+      {
+        **policy,
+        chdir:,
+        env:,
+        unsetenv_others:,
+        close_others:,
+        timeout:,
+        stdin:,
+        rlimits:,
+        seccomp_deny_network:,
+        max_output_bytes:,
+        truncate_output:
+      }
+    end
+
     def spawn_with_runner(argv, **options)
       if Runner::Native.available?
         begin
@@ -199,6 +273,12 @@ module Landlock
       raise ArgumentError, "empty Landlock policy: provide filesystem paths, TCP ports, or scopes"
     end
 
+    def validate_fallback_restriction!(seccomp_deny_network:, rlimits:, **)
+      return if seccomp_deny_network || rlimits.any?
+
+      raise ArgumentError, "Landlock fallback requires seccomp_deny_network or rlimits"
+    end
+
     def validate_capture_restriction!(
       read:,
       write:,

data/lib/landlock/native.rb

@@ -31,10 +31,22 @@ module Landlock
       Landlock.__send__(:_close_fd, fd)
     end
 
+    def close_inherited_fds!
+      Landlock.__send__(:_close_inherited_fds)
+    end
+
     def pidfd_open(pid)
       Landlock.__send__(:_pidfd_open, pid)
     end
 
+    def arm_parent_death_process_group!(parent_pid)
+      Landlock.__send__(:_arm_parent_death_process_group, parent_pid)
+    end
+
+    def set_parent_death_signal!
+      Landlock.__send__(:_set_parent_death_signal)
+    end
+
     def seccomp_deny_network!
       Landlock.seccomp_deny_network!
     end

data/lib/landlock/runner/fork.rb

@@ -71,44 +71,97 @@ module Landlock
         seccomp_deny_network:,
         max_output_bytes:,
         truncate_output:
+      )
+        capture_pipes(timeout:, stdin:, max_output_bytes:, truncate_output:) do
+          setup_child!(
+            argv,
+            read:,
+            write:,
+            execute:,
+            connect_tcp:,
+            bind_tcp:,
+            paths:,
+            scope:,
+            chdir:,
+            env:,
+            unsetenv_others:,
+            close_others:,
+            allow_all_known:,
+            rlimits:,
+            seccomp_deny_network:
+          )
+        rescue Exception => error
+          Runner.exit_child!(error)
+        end
+      end
+
+      def call_block(timeout:, stdin:, max_output_bytes:, truncate_output:, enforce_landlock:, **options, &block)
+        capture_pipes(
+          timeout:,
+          stdin:,
+          max_output_bytes:,
+          truncate_output:,
+          kill_process_group_on_parent_death: true
+        ) do
+          begin
+            prepare_forked_block!(**options, enforce_landlock:)
+          rescue SystemExit, SignalException
+            raise
+          rescue Exception => error
+            Runner.exit_child!(error)
+          end
+
+          block.call(STDOUT, STDERR)
+          exit! 0
+        rescue SystemExit => error
+          exit! error.status
+        rescue SignalException
+          raise
+        rescue Exception => error
+          Runner.exit_forked_block!(error)
+        end
+      end
+
+      def capture_pipes(
+        timeout:,
+        stdin:,
+        max_output_bytes:,
+        truncate_output:,
+        kill_process_group_on_parent_death: false
       )
         stdout_reader, stdout_writer = IO.pipe
         stderr_reader, stderr_writer = IO.pipe
         stdin_reader, stdin_writer = IO.pipe
+        parent_pid = ::Process.pid
 
         pid =
           fork do
             begin
+              # Arm group cleanup only after leaving the supervisor's process group.
+              ::Process.setpgrp
+              if kill_process_group_on_parent_death
+                Landlock::Native.arm_parent_death_process_group!(parent_pid)
+              else
+                Landlock::Native.set_parent_death_signal!
+                exit! 1 if ::Process.ppid != parent_pid
+              end
               stdout_reader.close
               stderr_reader.close
               stdin_writer.close
-              ::Process.setpgrp
               STDIN.reopen(stdin_reader)
               STDOUT.reopen(stdout_writer)
               STDERR.reopen(stderr_writer)
+              STDOUT.sync = true
+              STDERR.sync = true
               stdin_reader.close
               stdout_writer.close
               stderr_writer.close
 
-              setup_child!(
-                argv,
-                read:,
-                write:,
-                execute:,
-                connect_tcp:,
-                bind_tcp:,
-                paths:,
-                scope:,
-                chdir:,
-                env:,
-                unsetenv_others:,
-                close_others:,
-                allow_all_known:,
-                rlimits:,
-                seccomp_deny_network:
-              )
+              yield
+            rescue SystemExit, SignalException
+              raise
             rescue Exception => error
-              Runner.exit_child!(error)
+              Runner.exit_child!(error, stderr: capture_error_stream(stderr_writer))
             end
           end
 
@@ -141,6 +194,12 @@ module Landlock
         end
       end
 
+      def capture_error_stream(stderr_writer)
+        stderr_writer && !stderr_writer.closed? ? stderr_writer : STDERR
+      rescue IOError
+        STDERR
+      end
+
       def setup_child!(
         argv,
         read:,
@@ -166,6 +225,39 @@ module Landlock
         Rlimits.apply!(rlimits)
         Kernel.exec(*Runner.kernel_exec_args(argv, env, unsetenv_others:, close_others:))
       end
+
+      def prepare_forked_block!(
+        chdir:,
+        env:,
+        unsetenv_others:,
+        close_others:,
+        rlimits:,
+        seccomp_deny_network:,
+        enforce_landlock:,
+        **policy
+      )
+        close_inherited_ios if close_others
+        Dir.public_send(:chdir, chdir) if chdir
+        ENV.clear if unsetenv_others
+        env&.each { |key, value| value.nil? ? ENV.delete(key) : ENV[key] = value }
+        Landlock.restrict!(**policy) if enforce_landlock && Policy.requested?(**policy)
+        Landlock::Native.seccomp_deny_network! if seccomp_deny_network
+        Rlimits.apply!(rlimits)
+      end
+
+      def close_inherited_ios
+        ObjectSpace
+          .each_object(IO)
+          .to_a
+          .each do |io|
+            next if io.closed? || io.fileno <= 2
+
+            io.close
+          rescue IOError
+          end
+
+        Landlock::Native.close_inherited_fds!
+      end
     end
   end
 end

data/lib/landlock/runner.rb

@@ -16,11 +16,19 @@ module Landlock
       env ? [env, *argv_for_exec(argv), exec_options] : [*argv_for_exec(argv), exec_options]
     end
 
-    def exit_child!(error)
-      warn "Landlock child failed before exec: #{error.class}: #{error.message}"
+    def exit_child!(error, stderr: STDERR)
+      stderr.puts "Landlock child setup failed: #{error.class}: #{error.message}"
+      stderr.flush
     ensure
       exit! 127
     end
+
+    def exit_forked_block!(error, stderr: STDERR)
+      stderr.puts "Landlock forked block failed: #{error.class}: #{error.message}"
+      stderr.flush
+    ensure
+      exit! 1
+    end
   end
 end
 

data/lib/landlock/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Landlock
-  VERSION = "0.4.1"
+  VERSION = "0.5"
 end

data/lib/landlock.rb

@@ -39,5 +39,9 @@ module Landlock
     def capture!(...)
       Execution.capture!(...)
     end
+
+    def fork(...)
+      Execution.fork(...)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: landlock
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: '0.5'
 platform: ruby
 authors:
 - Sam Saffron