landlock 0.1.0 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cf65089e4af85184c67c7a2e6c679932dd21c492882ccf9cf4612d5603cb7a4
-  data.tar.gz: a987aaefb3e9ec52f69087c533fed5e384157aa4e1caebbc56226030c84e1112
+  metadata.gz: baea0cbd5b22406f288880dd5bcec85569c3134b256657d876a502f37e622364
+  data.tar.gz: a383e9cb807f51e2fd6e5d15a5d3d22c61d20a9ee2f9dffb046a1a97e24c2a6e
 SHA512:
-  metadata.gz: 6de7d6d837c0365fcf6d18e4cf3d41d291d6d043b71a3b05d1501e3c805faf7acd082865e67bad699814f0bdd342859f7790e80c3d58e510b83f8121e3445955
-  data.tar.gz: f87863bd3de8f8a8d5ce6ffd56382bafcf6cefc7ec74dca9ea9a7e6df7c5f759c556f51a2e687668d0fd30b809cf07a8136b73e26467dd069d021977a5abd4e2
+  metadata.gz: c385390bd6b239d5a7b495d74388ba9bb357787900ef73bfbd953d8353c49ce893117df8cc80fe95b0c9b2e8a6c836988a8540b2fbfdbce244ff76a6879d7067
+  data.tar.gz: b1d754bbfd7b60ec81cc4d036bc13ab627253fdf2fdb55a752477a43f917381d819f8fa20870abcad264e2a86d0c5635cb327799ccc614800e3adb1088b9dfec

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+### [0.2] - 2026-04-30
+
+- Add `Landlock::SafeExec.capture`, backed by a compiled `landlock-safe-exec` helper, for subprocess capture with Landlock, optional seccomp network denial, resource limits, exact environment handling, stdin, timeout handling, process-group cleanup, result metadata, and output limits.
+- Share native Landlock syscall/constant definitions between the Ruby extension and helper binary.
+- Add non-Linux/pass-through SafeExec behavior so integration code can run on platforms without the Linux sandbox backend while warning that sandbox options are ignored.
+
+## [0.1.1] - 2026-04-30
+
+### Security
+
+- Require `Landlock.exec` and `Landlock.spawn` commands to be passed as argument arrays. This avoids Ruby's implicit shell execution path for string commands.
+- Execute subprocesses with an explicit `argv[0]` tuple (`[command, command]`) so array commands keep their no-shell behavior.
+- Use `exit! 127` for child setup failures before `exec`, preventing inherited `at_exit` handlers from running in the forked child.
+- Honor `unsetenv_others: true` by passing Ruby's `unsetenv_others` exec option instead of only constructing a reduced environment hash.
+- Add ABI v6 Landlock scoping support via `scope: [:signal, :abstract_unix_socket]` to restrict signalling and abstract Unix-domain socket access outside the sandbox domain.
+- Expose `allow_all_known:` on `Landlock.exec` and `Landlock.spawn` so subprocess sandboxes can deny unlisted filesystem actions without needing dummy allow rules.
+
+### Fixed
+
+- Allow high-level `read`, `write`, and `execute` helpers to target individual files by filtering directory-only rights before adding file path rules.
+- Fix fallback Landlock syscall numbers on i386, handle x32, and prefer platform `__NR_*` constants when available.
+- Convert path rule arguments before opening path file descriptors in the native extension to avoid leaking descriptors on argument conversion errors.
+
+### Documentation
+
+- Document important sandbox caveats: only handled rights are restricted, TCP rules do not cover UDP/pathname Unix sockets, already-open descriptors remain usable, and `restrict!` applies to the calling thread and future children.
+
+### Tests
+
+- Add coverage for no-shell argv validation, child setup failure behavior, `unsetenv_others`, strict filesystem subprocess policies, file-specific path rules, and ABI v6 signal scoping.
+
+## [0.1.0] - 2026-04-30
+
+### Added
+
+- Initial Ruby bindings for Linux Landlock rulesets, filesystem path rules, TCP port rules, and safe subprocess helpers.

data/README.md

@@ -1,12 +1,12 @@
 # landlock
 
-Ruby bindings for Linux [Landlock](https://docs.kernel.org/userspace-api/landlock.html): unprivileged, kernel-enforced sandboxing for the current process and its descendants.
+Ruby bindings for Linux [Landlock](https://docs.kernel.org/userspace-api/landlock.html): unprivileged, kernel-enforced sandboxing for the calling thread and its future descendants.
 
 This gem includes a small native extension around the three Landlock syscalls and a Ruby API for safe subprocess execution.
 
 ## Status
 
-Experimental. Filesystem support requires Landlock ABI v1+. TCP network rules require ABI v4+.
+Experimental. Filesystem support requires Landlock ABI v1+. TCP network rules require ABI v4+. Signal and abstract Unix-domain socket scopes require ABI v6+.
 
 ```ruby
 require "landlock"
@@ -15,8 +15,12 @@ puts Landlock.abi_version
 puts Landlock.supported?
 ```
 
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
 ## Safe subprocess execution
 
+Pass commands as an argument array. `Landlock.exec` and `Landlock.spawn` do not invoke a shell implicitly; use an explicit shell in the array if that is really required. Both helpers accept `env:` and `unsetenv_others:` and pass them through to `Kernel.exec` so subprocesses can run with a controlled environment.
+
 Allow Ruby to execute and read its runtime, but only allow outbound TCP connections to port 443:
 
 ```ruby
@@ -24,7 +28,8 @@ status = Landlock.exec(
   [RbConfig.ruby, "script.rb"],
   read: ["/usr", "/lib", "/lib64", "/etc/ssl"],
   execute: ["/usr", "/lib", "/lib64"],
-  connect_tcp: [443]
+  connect_tcp: [443],
+  allow_all_known: true
 )
 
 abort "failed" unless status.success?
@@ -35,12 +40,20 @@ Deny all outbound TCP except the listed ports:
 ```ruby
 Landlock.exec(
   ["curl", "https://example.com"],
-  read: ["/usr", "/lib", "/lib64", "/etc/ssl", "/etc/resolv.conf", "/etc/hosts"],
+  read: [
+    "/usr", "/lib", "/lib64",
+    "/etc/ssl", "/etc/resolv.conf", "/etc/hosts",
+    "/etc/nsswitch.conf", "/etc/gai.conf", "/etc/host.conf",
+    "/run/systemd/resolve", "/var/lib/sss"
+  ].select { |path| File.exist?(path) },
   execute: ["/usr", "/lib", "/lib64"],
-  connect_tcp: [443]
+  connect_tcp: [443],
+  allow_all_known: true
 )
 ```
 
+TLS and name-resolution dependencies vary by distribution and NSS configuration; add any local CA, DNS, NSS, or resolver paths your system needs.
+
 Allow binding a local TCP port:
 
 ```ruby
@@ -48,22 +61,99 @@ Landlock.exec(
   [RbConfig.ruby, "server.rb"],
   read: ["/usr", "/lib", "/lib64", Dir.pwd],
   execute: ["/usr", "/lib", "/lib64"],
-  bind_tcp: [9292]
+  bind_tcp: [9292],
+  allow_all_known: true
+)
+```
+
+## SafeExec helper
+
+`Landlock::SafeExec.capture` runs a command through the compiled `landlock-safe-exec` helper. The helper applies Landlock rules, resource limits, and an optional seccomp network-deny filter in the execing process before replacing itself with the target command. This keeps the privileged setup out of Ruby/FFI and avoids running Ruby code in a post-fork child. Use `capture!` when unsuccessful exit statuses should raise.
+
+For example, inspect an uploaded video with `ffprobe` while only allowing reads from the upload and system runtime paths, denying network access, and bounding CPU/output:
+
+```ruby
+result = Landlock::SafeExec.capture(
+  "ffprobe",
+  "-v", "error",
+  "-show_format",
+  "-show_streams",
+  "-of", "json",
+  upload_path,
+  read: [upload_path, *Landlock::SafeExec.default_read_paths],
+  execute: Landlock::SafeExec.default_execute_paths,
+  env: { "PATH" => ENV.fetch("PATH", "") },
+  rlimits: {
+    cpu_seconds: 5,
+    memory_bytes: 512 * 1024 * 1024,
+    file_size_bytes: 0,
+    open_files: 64,
+    processes: 0
+  },
+  seccomp_deny_network: true,
+  max_output_bytes: 256 * 1024,
+  truncate_output: false
+)
+
+metadata = JSON.parse(result.stdout) if result.success?
+```
+
+Pass `stdin:` when a tool should read from standard input instead of a file:
+
+```ruby
+stdout, stderr, status = Landlock::SafeExec.capture(
+  "tr", "a-z", "A-Z",
+  stdin: "hello",
+  env: { "PATH" => ENV.fetch("PATH", "") }
 )
 ```
 
+`capture` returns a `Landlock::SafeExec::Result` with `stdout`, `stderr`, `status`, `success?`, `timed_out?`, and `output_truncated?`, including for unsuccessful exit statuses. It also supports array destructuring:
+
+```ruby
+stdout, stderr, status = Landlock::SafeExec.capture("tool", "arg")
+```
+
+`capture!` has the same return shape for successful commands, but raises `Landlock::SafeExec::CommandError` for unsuccessful statuses. The error also exposes `stdout`, `stderr`, `status`, and `result`.
+
+SafeExec options:
+
+- `read:`, `write:`, `execute:` — filesystem allowlists. Explicit paths must exist; missing paths raise `ArgumentError` instead of being silently ignored.
+- `connect_tcp:` — allowed outbound TCP ports. If omitted on Landlock ABI v4+, SafeExec denies outbound TCP by installing a dummy allow rule for port `0`. Pass `connect_tcp: []` to leave outbound TCP unrestricted.
+- `bind_tcp:` — allowed TCP bind ports. Binding is unrestricted unless this is provided.
+- `seccomp_deny_network:` — additionally deny common Linux network syscalls with seccomp. This is Linux-specific and intended as defense in depth.
+- `rlimits:` — resource limits. Supported keys are `:cpu_seconds`, `:memory_bytes`, `:file_size_bytes`, `:open_files`, and `:processes`. Values must be non-negative integers.
+- `timeout:` — wall-clock timeout in seconds. On timeout SafeExec terminates the process group and returns/raises with `result.timed_out?` true.
+- `max_output_bytes:` — combined stdout+stderr byte limit. With `truncate_output: false`, exceeding the limit raises. With `truncate_output: true`, output is truncated and `result.output_truncated?` is true.
+- `stdin:` — string or IO-like object to write to the child process stdin.
+- `chdir:` — working directory for the child.
+- `env:` — exact child environment by default.
+- `inherit_env:` — when true, inherit the parent environment and apply `env:` as overrides.
+- `success_status_codes:` — status codes considered successful by `capture!`; defaults to `[0]`.
+- `allow_all_known:` — when filesystem rules are present, handle all Landlock filesystem rights known to the running ABI so unlisted filesystem access is denied. Defaults to `true`.
+
+SafeExec uses an exact environment by default: `env:` is the full environment passed to the child, not additions to the parent environment. Use `inherit_env: true` when a command really needs the parent environment plus the supplied `env:` overrides.
+
+Use `Landlock::SafeExec.supported?` (or `sandboxing?`) to check whether the Linux helper and Landlock are available. When this is false, SafeExec still runs commands in pass-through mode but does not enforce Landlock/seccomp sandbox options.
+
+On non-Linux platforms, or when the compiled helper is unavailable, SafeExec runs as a pass-through compatibility wrapper. Process-management features such as capture, timeout, environment handling, `chdir:`, output limits, `stdin:`, and supported `rlimits:` still apply, but Landlock and seccomp options (`read:`, `write:`, `execute:`, `connect_tcp:`, `bind_tcp:`, `seccomp_deny_network:`) are ignored and a warning is emitted. This makes cross-platform integration easier while keeping the security guarantees explicit: sandboxing is Linux-only.
+
 ## Restrict current process
 
-This is irreversible for the current thread/process. Use `Landlock.exec` or `Landlock.spawn` unless you really mean it.
+This is irreversible for the current thread and its future children. Use `Landlock.exec` or `Landlock.spawn` unless you really mean it.
 
 ```ruby
 Landlock.restrict!(
   read: ["/usr", "/app"],
   write: ["/tmp/my-output"],
-  connect_tcp: [443]
+  connect_tcp: [443],
+  scope: [:signal, :abstract_unix_socket],
+  allow_all_known: true
 )
 ```
 
+`write:` grants the filesystem rights needed for practical writes under the listed paths, including directory traversal and reads (`read_file`/`read_dir`). If you need exact rights, use `paths:` with an explicit `rights:` list.
+
 ## Lower-level path rules
 
 ```ruby
@@ -76,6 +166,48 @@ Landlock.restrict!(
 )
 ```
 
+## Performance
+
+Landlock enforcement is done by the kernel after a ruleset is installed. In normal use the practical cost should be dominated by the one-time sandbox setup and by the work your process already performs, not by Ruby-side wrappers.
+
+This repository includes a small benchmark suite that compares common workloads before and after applying a read-only Landlock policy:
+
+```sh
+bundle exec rake bench
+# or
+bundle exec ruby benchmark/landlock_overhead.rb
+```
+
+The suite reports median timings for CPU-only work, file metadata reads, small file reads, directory scans, and the one-time ruleset setup cost. You can tune the run length with environment variables:
+
+```sh
+SAMPLES=15 ITERATIONS=100000 DIR_ITERATIONS=5000 bundle exec rake bench
+```
+
+Sample output looks like:
+
+```text
+workload           baseline     landlocked        delta    delta %
+--------------------------------------------------------------------
+cpu_loop           0.650 ms       0.648 ms    -0.002 ms     -0.31%
+file_stat         42.100 ms      42.300 ms     0.200 ms      0.48%
+file_read        120.500 ms     120.900 ms     0.400 ms      0.33%
+dir_scan          88.000 ms      88.200 ms     0.200 ms      0.23%
+
+Setup cost (create ruleset, add read rules, restrict current process):
+  median 0.080 ms (25 samples)
+```
+
+Treat small positive or negative deltas as noise and benchmark on the kernel, filesystem, and hardware you deploy on. The expected result is no practical steady-state overhead for typical application work, with a small one-time cost when installing the sandbox.
+
 ## Caveats
 
-Landlock is not a complete container. It does not impose CPU/memory limits, hide already-open file descriptors, or replace seccomp/namespaces/cgroups. For serious untrusted execution, combine it with controlled environment, `close_others`, resource limits, and preferably process isolation.
+Landlock is not a complete container. It does not impose CPU/memory limits, hide already-open file descriptors, or replace seccomp/namespaces/cgroups. For serious untrusted execution, combine it with a controlled environment, `close_others`, resource limits, and preferably process isolation.
+
+If a child fails during sandbox setup or `exec`, the helpers print a diagnostic and the child exits 127. That code can collide with a command that legitimately exits 127; unsupported kernels are checked before forking so they raise `Landlock::UnsupportedError` synchronously instead.
+
+Path rules follow the kernel's normal path resolution when the rule is installed. Because paths are opened without `O_NOFOLLOW`, a symlink rule applies to the symlink target's inode, not to the symlink path itself.
+
+Landlock only restricts access rights included in a ruleset's handled set: omitted categories remain allowed. Use `allow_all_known: true` when you want unlisted filesystem actions denied. The high-level helpers handle the categories you pass (`read`, `write`, `execute`, `connect_tcp`, `bind_tcp`, `scope`). Landlock's TCP rules do not cover UDP or pathname Unix-domain sockets; ABI v6+ scopes can restrict signals and abstract Unix-domain sockets.
+
+`Landlock.restrict!` applies to the calling thread and its future children; already-running sibling threads are not retroactively sandboxed. Prefer `Landlock.exec` or `Landlock.spawn` for subprocess sandboxing from a larger Ruby application.

data/benchmark/landlock_overhead.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "json"
+require "rbconfig"
+require "tmpdir"
+require "fileutils"
+require "open3"
+
+root = File.expand_path("..", __dir__)
+lib_dir = File.join(root, "lib")
+ext_lib_dir = File.join(lib_dir, "landlock")
+
+$LOAD_PATH.unshift(lib_dir)
+$LOAD_PATH.unshift(ext_lib_dir)
+
+require "landlock"
+
+module LandlockBench
+  ROOT = File.expand_path("..", __dir__)
+  DEFAULT_SAMPLES = Integer(ENV.fetch("SAMPLES", 7))
+  DEFAULT_ITERATIONS = Integer(ENV.fetch("ITERATIONS", 25_000))
+  DIR_ITERATIONS = Integer(ENV.fetch("DIR_ITERATIONS", 2_000))
+  SETUP_SAMPLES = Integer(ENV.fetch("SETUP_SAMPLES", 25))
+
+  WORKLOADS = [
+    ["cpu_loop", "integer arithmetic loop"],
+    ["file_stat", "File.stat on an allowed file"],
+    ["file_read", "File.binread of a small allowed file"],
+    ["dir_scan", "Dir.foreach over an allowed directory"]
+  ].freeze
+
+  module_function
+
+  def monotonic_ns
+    Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+  end
+
+  def measure
+    started = monotonic_ns
+    yield
+    monotonic_ns - started
+  end
+
+  def runtime_paths
+    [
+      File.dirname(RbConfig.ruby),
+      RbConfig::CONFIG["libdir"],
+      RbConfig::CONFIG["archlibdir"],
+      "/usr",
+      "/lib",
+      "/lib64",
+      "/etc"
+    ].compact.uniq.select { |path| File.exist?(path) }
+  end
+
+  def prepare_workspace
+    Dir.mktmpdir("landlock-bench") do |dir|
+      file = File.join(dir, "small.txt")
+      entries = File.join(dir, "entries")
+      Dir.mkdir(entries)
+      File.binwrite(file, "x" * 1024)
+      100.times { |index| File.binwrite(File.join(entries, "entry-#{index}.txt"), "x") }
+
+      yield({ "dir" => dir, "file" => file, "entries" => entries })
+    end
+  end
+
+  def child_command(payload)
+    [RbConfig.ruby, __FILE__, "--child", JSON.generate(payload)]
+  end
+
+  def run_child(payload)
+    stdout, stderr, status = Open3.capture3(*child_command(payload), chdir: ROOT)
+    unless status.success?
+      abort "bench child failed (#{status.exitstatus})\nSTDOUT:\n#{stdout}\nSTDERR:\n#{stderr}"
+    end
+
+    JSON.parse(stdout)
+  end
+
+  def run_parent
+    puts "Landlock performance benchmark"
+    puts "Ruby: #{RUBY_DESCRIPTION}"
+    puts "Landlock ABI: #{Landlock.abi_version}"
+    puts "Samples: #{DEFAULT_SAMPLES}, iterations: #{DEFAULT_ITERATIONS}"
+    puts
+
+    prepare_workspace do |workspace|
+      read_paths = (runtime_paths + [workspace.fetch("dir")]).uniq
+      common = {
+        mode: "workloads",
+        iterations: DEFAULT_ITERATIONS,
+        dir_iterations: DIR_ITERATIONS,
+        read_paths: read_paths,
+        workspace: workspace
+      }
+
+      baseline = collect_samples(DEFAULT_SAMPLES) { run_child(common.merge(sandbox: false)) }
+
+      unless Landlock.supported?
+        puts "Landlock is not supported on this host; only baseline timings were collected."
+        print_workload_table(baseline, nil)
+        return
+      end
+
+      sandbox = collect_samples(DEFAULT_SAMPLES) { run_child(common.merge(sandbox: true)) }
+      setup = collect_samples(SETUP_SAMPLES) do
+        run_child(mode: "setup", read_paths: read_paths).fetch("setup_ns")
+      end
+
+      print_workload_table(baseline, sandbox)
+      puts
+      puts "Setup cost (create ruleset, add read rules, restrict current process):"
+      puts "  median #{format_ms(median(setup))} (#{SETUP_SAMPLES} samples)"
+      puts
+      puts "Lower is better. Negative deltas mean the sandboxed sample was faster in this run."
+      puts "Expect small differences to be noise; compare medians across repeated runs."
+    end
+  end
+
+  def collect_samples(count)
+    Array.new(count) { yield }
+  end
+
+  def print_workload_table(baseline, sandbox)
+    puts format("%-12s %14s %14s %12s %10s", "workload", "baseline", "landlocked", "delta", "delta %")
+    puts "-" * 68
+
+    WORKLOADS.each do |name, description|
+      base = median(baseline.map { |sample| sample.fetch(name) })
+      if sandbox
+        locked = median(sandbox.map { |sample| sample.fetch(name) })
+        delta = locked - base
+        pct = base.positive? ? (delta.to_f / base * 100.0) : 0.0
+        puts format(
+          "%-12s %14s %14s %12s %9.2f%%",
+          name,
+          format_ms(base),
+          format_ms(locked),
+          format_ms(delta),
+          pct
+        )
+      else
+        puts format("%-12s %14s %14s %12s %10s", name, format_ms(base), "n/a", "n/a", "n/a")
+      end
+      puts "  #{description}"
+    end
+  end
+
+  def median(values)
+    sorted = values.sort
+    midpoint = sorted.length / 2
+    return sorted.fetch(midpoint) if sorted.length.odd?
+
+    (sorted.fetch(midpoint - 1) + sorted.fetch(midpoint)) / 2.0
+  end
+
+  def format_ms(ns)
+    format("%.3f ms", ns.to_f / 1_000_000.0)
+  end
+
+  def run_child_mode(payload)
+    case payload.fetch("mode")
+    when "setup"
+      puts JSON.generate("setup_ns" => measure { restrict_for(payload) })
+    when "workloads"
+      restrict_for(payload) if payload.fetch("sandbox")
+      puts JSON.generate(run_workloads(payload))
+    else
+      raise ArgumentError, "unknown child mode: #{payload.fetch("mode").inspect}"
+    end
+  end
+
+  def restrict_for(payload)
+    Landlock.restrict!(read: payload.fetch("read_paths"))
+  end
+
+  def run_workloads(payload)
+    iterations = Integer(payload.fetch("iterations"))
+    dir_iterations = Integer(payload.fetch("dir_iterations"))
+    workspace = payload.fetch("workspace")
+    file = workspace.fetch("file")
+    entries = workspace.fetch("entries")
+    sink = 0
+
+    GC.disable
+    {
+      "cpu_loop" => measure do
+        iterations.times { |index| sink ^= ((index * 31) & 0xffff) }
+      end,
+      "file_stat" => measure do
+        iterations.times { sink ^= File.stat(file).size }
+      end,
+      "file_read" => measure do
+        iterations.times { sink ^= File.binread(file).bytesize }
+      end,
+      "dir_scan" => measure do
+        dir_iterations.times do
+          Dir.foreach(entries) { |entry| sink ^= entry.bytesize }
+        end
+      end
+    }.merge("sink" => sink)
+  ensure
+    GC.enable
+  end
+end
+
+if ARGV.first == "--child"
+  LandlockBench.run_child_mode(JSON.parse(ARGV.fetch(1)))
+else
+  LandlockBench.run_parent
+end