seccomp-ruby 0.1.0

data/lib/seccomp/notification.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # One immutable user-notification request.
+  class Notification
+    # Fields copied from the kernel notification request.
+    # @api private
+    ATTRIBUTES = %i[id pid flags syscall arch instruction_pointer args].freeze
+    attr_reader :id, :pid, :flags, :syscall, :arch, :instruction_pointer, :args
+
+    # @param notifier [Notifier] response channel
+    # @param data [Hash] low-level request fields
+    # @return [void]
+    # @example `Notification.new(notifier, data)`
+    def initialize(notifier, data)
+      @notifier = notifier
+      ATTRIBUTES.each { |attribute| instance_variable_set("@#{attribute}", data.fetch(attribute)) }
+      @args.freeze
+    end
+
+    # @return [Boolean] whether the kernel still recognizes the request
+    # @raise [Error] if validation fails
+    # @example `notification.valid?`
+    def valid?
+      @notifier.id_valid?(id)
+    end
+
+    # @param val [Integer] syscall return value
+    # @param error [Integer, SystemCallError, Class] positive or negative errno
+    # @param flags [Integer] response flags
+    # @return [nil]
+    # @raise [Error] if responding fails
+    # @example `notification.respond(val: 3)`
+    def respond(val: 0, error: 0, flags: 0)
+      error = -errno_number(error).abs unless error.is_a?(Integer) && error.zero?
+      @notifier.respond(id: id, val: val, error: error, flags: flags)
+    end
+
+    # @param value [Integer] syscall return value
+    # @return [nil]
+    # @raise [Error] if responding fails
+    # @example `notification.allow(0)`
+    def allow(value = 0)
+      respond(val: value)
+    end
+
+    # @param errno [Integer, SystemCallError, Class] positive errno
+    # @return [nil]
+    # @raise [Error] if responding fails
+    # @raise [ArgumentError] for an invalid errno
+    # @example `notification.deny(Errno::EPERM)`
+    def deny(errno)
+      number = errno_number(errno)
+      raise ArgumentError, "errno must not be zero" if number.zero?
+
+      respond(error: -number.abs)
+    end
+
+    # @return [nil]
+    # @raise [Error] if responding fails
+    # @example `notification.continue!`
+    def continue!
+      respond(flags: LowLevel::USER_NOTIF_FLAG_CONTINUE)
+    end
+
+    # @param io [IO] descriptor to install
+    # @param flags [Integer] addfd flags
+    # @param newfd [Integer] requested target descriptor
+    # @param newfd_flags [Integer] target descriptor flags
+    # @return [Integer] installed descriptor
+    # @raise [NotSupportedError] when unavailable
+    # @example `notification.add_fd(file)`
+    def add_fd(io, flags: 0, newfd: 0, newfd_flags: 0)
+      @notifier.add_fd(id: id, source_fd: io.fileno, flags: flags,
+                       newfd: newfd, newfd_flags: newfd_flags)
+    end
+
+    private
+
+    def errno_number(value)
+      number = if value.is_a?(Class) && value < SystemCallError
+                 value.const_get(:Errno, false) if value.const_defined?(:Errno, false)
+               elsif value.is_a?(SystemCallError)
+                 value.errno
+               else
+                 value
+               end
+      unless number.is_a?(Integer)
+        raise ArgumentError, "errno must be an Integer or system error with an errno"
+      end
+
+      number
+    end
+  end
+end

data/lib/seccomp/notifier.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module Seccomp
+  # Receives and responds to seccomp user notifications.
+  class Notifier
+    include Enumerable
+
+    # ponytail: bounded polling avoids a native wakeup channel; replace only if idle cost matters.
+    CLOSE_POLL_INTERVAL = 0.1
+    private_constant :CLOSE_POLL_INTERVAL
+
+    # @param filter [Filter] loaded owner filter
+    # @param fd [Integer] notification listener descriptor
+    # @return [void]
+    # @example `Notifier.new(filter, fd)`
+    def initialize(filter, fd)
+      @filter = filter
+      @fd = fd
+      @io = IO.for_fd(fd, autoclose: false)
+      @receive_lock = filter.__send__(:notification_receive_lock)
+    end
+
+    # @param timeout [Numeric, nil] nonnegative finite real seconds to wait
+    # @return [Notification, nil] request or nil on timeout
+    # @raise [TypeError, ArgumentError, RangeError] if timeout is invalid
+    # @raise [ClosedFilterError] if the owning filter closes
+    # @raise [NotificationCanceledError] if the target exits
+    # @example `notifier.receive(timeout: 1)`
+    def receive(timeout: nil)
+      validate_timeout!(timeout)
+      deadline = monotonic_time + timeout if timeout
+      acquired = acquire_receive_lock(deadline)
+      return nil unless acquired
+
+      receive_locked(remaining_timeout(deadline))
+    ensure
+      @receive_lock.unlock if acquired
+    end
+
+    # @yield [Notification] each request
+    # @return [Enumerator, Notifier] enumerator or receiver
+    # @raise [Error] if receiving fails
+    # @example `notifier.each { |notification| notification.continue! }`
+    def each
+      return enum_for(__method__) unless block_given?
+
+      loop do
+        yield receive
+      rescue NotificationCanceledError
+        next
+      end
+    end
+
+    # @param id [Integer] notification ID
+    # @param val [Integer] syscall return value
+    # @param error [Integer] kernel-style negative errno
+    # @param flags [Integer] response flags
+    # @return [nil]
+    # @raise [Error] if responding fails
+    # @example `notifier.respond(id: id, val: 0)`
+    def respond(id:, val: 0, error: 0, flags: 0)
+      ensure_open!
+      check_notification_result!(LowLevel.notify_respond(@fd, id, val, error, flags),
+                                 call: "seccomp_notify_respond")
+      nil
+    end
+
+    # @param id [Integer] notification ID
+    # @return [Boolean] whether still valid
+    # @raise [Error] if validation fails
+    # @example `notifier.id_valid?(id)`
+    def id_valid?(id)
+      ensure_open!
+      result = LowLevel.notify_id_valid(@fd, id)
+      return true if result.zero?
+
+      ensure_open!
+      return false if [-Errno::ENOENT::Errno, -Errno::EINVAL::Errno].include?(result)
+
+      check_notification_result!(result, call: "seccomp_notify_id_valid")
+    end
+
+    # @param id [Integer] notification ID
+    # @param source_fd [Integer] local descriptor
+    # @param flags [Integer] addfd flags
+    # @param newfd [Integer] requested target descriptor
+    # @param newfd_flags [Integer] target descriptor flags
+    # @return [Integer] installed descriptor
+    # @raise [NotSupportedError] when unavailable
+    # @example `notifier.add_fd(id: id, source_fd: file.fileno)`
+    def add_fd(id:, source_fd:, flags: 0, newfd: 0, newfd_flags: 0)
+      ensure_open!
+      result = LowLevel.notify_addfd(@fd, id, flags, source_fd, newfd, newfd_flags)
+      check_notification_result!(result, call: "seccomp_notify_addfd")
+    end
+
+    # @return [nil]
+    # @example `notifier.close`
+    def close
+      @filter.close
+    end
+
+    # @return [Boolean] whether the owner filter is closed
+    # @example `notifier.closed?`
+    def closed?
+      @filter.closed?
+    end
+
+    private
+
+    def receive_locked(timeout)
+      return nil unless wait_readable(timeout)
+
+      ensure_open!
+
+      result, data = LowLevel.notify_receive(@fd)
+      if [-Errno::ENOENT::Errno, -Errno::ECANCELED::Errno].include?(result)
+        ensure_open!
+        raise NotificationCanceledError.new(
+          "seccomp_notify_receive failed: notification was canceled",
+          errno: -result, call: "seccomp_notify_receive"
+        )
+      end
+
+      check_notification_result!(result, call: "seccomp_notify_receive")
+      Notification.new(self, data)
+    end
+
+    def acquire_receive_lock(deadline)
+      return @receive_lock.lock unless deadline
+
+      loop do
+        return true if @receive_lock.try_lock
+
+        remaining = deadline - monotonic_time
+        return false if remaining <= 0
+
+        sleep([remaining, CLOSE_POLL_INTERVAL].min)
+      end
+    end
+
+    def remaining_timeout(deadline)
+      deadline && [deadline - monotonic_time, 0].max
+    end
+
+    def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def validate_timeout!(timeout)
+      return if timeout.nil?
+      unless timeout.is_a?(Numeric) && timeout.real?
+        raise TypeError, "timeout must be a real Numeric or nil"
+      end
+      raise ArgumentError, "time interval must not be negative" if timeout.negative?
+      raise RangeError, "time interval must be finite" unless timeout.finite?
+    end
+
+    def check_notification_result!(result, call:)
+      ensure_open! if result.negative?
+      Error.check!(result, call: call)
+    end
+
+    def wait_readable(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+      remaining = timeout
+      loop do
+        ensure_open!
+        return true if @io.wait_readable(poll_timeout(remaining))
+
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC) if deadline
+        return false if remaining && remaining <= 0
+      end
+    rescue Errno::EBADF
+      ensure_open!
+      raise
+    end
+
+    def poll_timeout(remaining)
+      [remaining || CLOSE_POLL_INTERVAL, CLOSE_POLL_INTERVAL].min
+    end
+
+    def ensure_open!
+      raise ClosedFilterError, "notification filter is closed" if closed?
+    end
+  end
+end

data/lib/seccomp/syscall.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Syscall name and number resolution.
+  module Syscall
+    module_function
+
+    # @param value [Symbol, String, Integer] syscall
+    # @param arch [Symbol, String, Integer, nil] target architecture
+    # @param rewrite [Boolean] rewrite multiplexed syscalls
+    # @return [Integer] syscall number
+    # @raise [UnknownSyscallError] for an unknown name
+    # @example `Syscall.number(:write, arch: :x86_64)`
+    def number(value, arch: nil, rewrite: false)
+      return value if value.is_a?(Integer)
+
+      name = value.to_s
+      result = if arch
+                 token = Arch.resolve(arch)
+                 if rewrite
+                   LowLevel.syscall_resolve_name_rewrite(token, name)
+                 else
+                   LowLevel.syscall_resolve_name_arch(token, name)
+                 end
+               else
+                 LowLevel.syscall_resolve_name(name)
+               end
+      return result unless result == LowLevel::NR_SCMP_ERROR
+
+      raise UnknownSyscallError, "unknown syscall: #{value.inspect}"
+    end
+
+    # @param number [Integer] syscall number
+    # @param arch [Symbol, String, Integer] target architecture
+    # @return [String, nil] syscall name
+    # @raise [ArgumentError] unless number is an Integer
+    # @example `Syscall.name(1, arch: :x86_64)`
+    def name(number, arch: Arch.native)
+      raise ArgumentError, "syscall number must be an Integer" unless number.is_a?(Integer)
+
+      LowLevel.syscall_resolve_num_arch(Arch.resolve(arch), number)
+    end
+  end
+end

data/lib/seccomp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Gem version.
+  VERSION = "0.1.0"
+end

data/lib/seccomp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "libseccomp"

data/sig/seccomp.rbs

@@ -0,0 +1,300 @@
+module Seccomp
+  VERSION: String
+
+  type errno = Integer | SystemCallError | singleton(SystemCallError)
+  type action = Integer | Symbol | String | [Symbol, untyped]
+  type arch = Integer | Symbol | String
+  type syscall = Integer | Symbol | String
+
+  def self.library_version: () -> LibraryVersion
+  def self.api_level: () -> Integer
+  def self.api_level=: (Integer) -> Integer
+  def self.supports?: (Symbol) -> bool
+  def self.filter: (?default: action) { (Filter) -> untyped } -> Filter
+                 | (?default: action) { () -> untyped } -> Filter
+                 | (?default: action) -> Filter
+
+  class LibraryVersion
+    attr_accessor major: Integer
+    attr_accessor minor: Integer
+    attr_accessor micro: Integer
+    def to_s: () -> String
+  end
+
+  class Error < StandardError
+    attr_reader errno: Integer?
+    attr_reader call: String?
+    def initialize: (?String?, ?errno: Integer?, ?call: String?) -> void
+    def self.check!: (Integer, call: String, ?hint: String?) -> Integer
+  end
+  class PermissionError < Error
+  end
+  class KernelError < Error
+  end
+  class ArchError < Error
+  end
+  class ExistsError < Error
+  end
+  class InvalidArgumentError < Error
+  end
+  class NotFoundError < Error
+  end
+  class OutOfMemoryError < Error
+  end
+  class NotSupportedError < Error
+  end
+  class ValueRangeError < Error
+  end
+  class ThreadSyncError < Error
+  end
+  class UnknownSyscallError < Error
+  end
+  class ClosedFilterError < Error
+  end
+  class NotificationError < Error
+  end
+  class NotificationCanceledError < NotificationError
+  end
+
+  module LowLevel
+    NR_SCMP_ERROR: Integer
+    NR_SCMP_UNDEF: Integer
+    USER_NOTIF_FLAG_CONTINUE: Integer
+    ADDFD_FLAG_SETFD: Integer
+    ADDFD_FLAG_SEND: Integer
+
+    class Context
+    end
+
+    def self.version: () -> [Integer, Integer, Integer]
+    def self.api_get: () -> Integer
+    def self.api_set: (Integer) -> Integer
+    def self.supports?: (Symbol) -> bool
+    def self.init: (Integer) -> Context
+    def self.release: (Context) -> nil
+    def self.closed?: (Context) -> bool
+    def self.reset: (Context, Integer) -> Integer
+    def self.merge: (Context, Context) -> Integer
+    def self.attr_get: (Context, Integer) -> [Integer, Integer]
+    def self.attr_set: (Context, Integer, Integer) -> Integer
+    def self.arch_add: (Context, Integer) -> Integer
+    def self.arch_remove: (Context, Integer) -> Integer
+    def self.arch_exist: (Context, Integer) -> Integer
+    def self.arch_resolve_name: (String) -> Integer
+    def self.arch_native: () -> Integer
+    def self.syscall_resolve_name: (String) -> Integer
+    def self.syscall_resolve_name_arch: (Integer, String) -> Integer
+    def self.syscall_resolve_name_rewrite: (Integer, String) -> Integer
+    def self.syscall_resolve_num_arch: (Integer, Integer) -> String?
+    def self.rule_add_array: (Context, Integer, Integer, Array[[Integer, Integer, Integer, Integer]]) -> Integer
+    def self.rule_add_exact_array: (Context, Integer, Integer, Array[[Integer, Integer, Integer, Integer]]) -> Integer
+    def self.syscall_priority: (Context, Integer, Integer) -> Integer
+    def self.export_pfc: (Context, Integer) -> Integer
+    def self.export_bpf: (Context, Integer) -> Integer
+    def self.export_bpf_mem: (Context) -> [Integer, String?]
+    def self.precompute: (Context) -> Integer
+    def self.load: (Context) -> Integer
+    def self.loaded?: (Context) -> bool
+    def self.transaction_start: (Context) -> Integer
+    def self.transaction_commit: (Context) -> Integer
+    def self.transaction_reject: (Context) -> Integer
+    def self.notify_fd: (Context) -> Integer
+    def self.notify_receive: (Integer) -> [Integer, Hash[Symbol, untyped]?]
+    def self.notify_respond: (Integer, Integer, Integer, Integer, Integer) -> Integer
+    def self.notify_id_valid: (Integer, Integer) -> Integer
+    def self.notify_addfd: (Integer, Integer, Integer, Integer, Integer, Integer) -> Integer
+  end
+
+  module Action
+    KILL_PROCESS: Integer
+    KILL_THREAD: Integer
+    KILL: Integer
+    TRAP: Integer
+    NOTIFY: Integer
+    LOG: Integer
+    ALLOW: Integer
+    TRAPX: Integer
+
+    def self.errno: (errno) -> Integer
+    def self.trace: (Integer) -> Integer
+    def self.trap: (?Integer) -> Integer
+    def self.resolve: (action) -> Integer
+    def self.describe: (Integer) -> String
+  end
+
+  module Arch
+    NATIVE: Integer
+    X86: Integer
+    X86_64: Integer
+    X32: Integer
+    ARM: Integer
+    AARCH64: Integer
+    LOONGARCH64: Integer
+    M68K: Integer
+    MIPS: Integer
+    MIPS64: Integer
+    MIPS64N32: Integer
+    MIPSEL: Integer
+    MIPSEL64: Integer
+    MIPSEL64N32: Integer
+    PPC: Integer
+    PPC64: Integer
+    PPC64LE: Integer
+    S390: Integer
+    S390X: Integer
+    PARISC: Integer
+    PARISC64: Integer
+    RISCV64: Integer
+    SH: Integer
+    SHEB: Integer
+
+    def self.all: () -> Hash[Symbol, Integer]
+    def self.native: () -> Integer
+    def self.resolve: (arch) -> Integer
+    def self.name: (Integer) -> Symbol?
+  end
+
+  module Syscall
+    def self.number: (syscall, ?arch: arch?, ?rewrite: bool) -> Integer
+    def self.name: (Integer, ?arch: arch) -> String?
+  end
+
+  module Compare
+    NE: Integer
+    LT: Integer
+    LE: Integer
+    EQ: Integer
+    GE: Integer
+    GT: Integer
+    MASKED_EQ: Integer
+  end
+
+  module FilterAttr
+    ACT_DEFAULT: Integer
+    ACT_BADARCH: Integer
+    CTL_NNP: Integer
+    CTL_TSYNC: Integer
+    API_TSKIP: Integer
+    CTL_LOG: Integer
+    CTL_SSB: Integer
+    CTL_OPTIMIZE: Integer
+    API_SYSRAWRC: Integer
+    CTL_WAITKILL: Integer
+  end
+
+  class ArgCmp
+    attr_reader arg: Integer
+    attr_reader op: Integer
+    attr_reader datum_a: Integer
+    attr_reader datum_b: Integer
+    def initialize: (arg: Integer, op: Symbol, datum_a: Integer, ?datum_b: Integer, ?width: Integer) -> void
+    def to_a: () -> [Integer, Integer, Integer, Integer]
+  end
+
+  module Arg
+    class Reference
+      def initialize: (Integer) -> void
+      def ne: (Integer, ?width: Integer) -> ArgCmp
+      def lt: (Integer, ?width: Integer) -> ArgCmp
+      def le: (Integer, ?width: Integer) -> ArgCmp
+      def eq: (Integer, ?width: Integer) -> ArgCmp
+      def ge: (Integer, ?width: Integer) -> ArgCmp
+      def gt: (Integer, ?width: Integer) -> ArgCmp
+      def ==: (Integer, ?width: Integer) -> ArgCmp
+      def masked_eq: (mask: Integer, value: Integer, ?width: Integer) -> ArgCmp
+    end
+
+    module DSL
+      def arg: (Integer) -> Reference
+    end
+  end
+
+  class Filter
+    include Arg::DSL
+
+    def initialize: (?action) -> void
+    def self.open: (?action) { (Filter) -> untyped } -> untyped
+                 | (?action) -> Filter
+    def close: () -> nil
+    def closed?: () -> bool
+    def reset: (?action?) -> self
+    def merge!: (Filter) -> self
+    def add_arch: (arch) -> self
+    def remove_arch: (arch) -> self
+    def arch?: (arch) -> bool
+    def archs: () -> Array[Symbol]
+    def add_rule: (action, syscall, *ArgCmp) -> self
+    def add_rule_exact: (action, syscall, *ArgCmp) -> self
+    def allow: (syscall, *(syscall | ArgCmp)) -> self
+    def deny: (syscall, *ArgCmp, ?errno: errno) -> self
+    def kill: (syscall, *ArgCmp) -> self
+    def log: (syscall, *ArgCmp) -> self
+    def notify: (syscall, *ArgCmp) -> self
+    def trap: (syscall, *ArgCmp) -> self
+    def trace: (syscall, Integer, *ArgCmp) -> self
+    def priority: (syscall, Integer) -> self
+    def []: (Symbol | Integer) -> Integer
+    def []=: (Symbol | Integer, Integer) -> Integer
+    def default_action: () -> Integer
+    def bad_arch_action: () -> Integer
+    def bad_arch_action=: (action) -> Integer
+    def no_new_privs?: () -> bool
+    def no_new_privs=: (bool) -> bool
+    def tsync?: () -> bool
+    def tsync=: (bool) -> bool
+    def tskip?: () -> bool
+    def tskip=: (bool) -> bool
+    def log?: () -> bool
+    def log=: (bool) -> bool
+    def ssb?: () -> bool
+    def ssb=: (bool) -> bool
+    def raw_rc?: () -> bool
+    def raw_rc=: (bool) -> bool
+    def wait_killable?: () -> bool
+    def wait_killable=: (bool) -> bool
+    def optimize: () -> Integer
+    def optimize=: (Integer) -> Integer
+    def export_pfc: (IO) -> nil
+    def export_bpf: (IO) -> nil
+    def to_pfc: () -> String
+    def to_bpf: () -> String
+    def precompute: () -> self
+    def load!: () -> nil
+    def loaded?: () -> bool
+    def transaction: () { () -> untyped } -> untyped
+    def notifier: () -> Notifier
+    def arch: (*arch) -> self
+    def no_new_privs: (bool) -> self
+    def tsync: (bool) -> self
+  end
+
+  class Notifier
+    include Enumerable[Notification]
+    def initialize: (Filter, Integer) -> void
+    def receive: (?timeout: Numeric?) -> Notification?
+    def each: () { (Notification) -> untyped } -> self
+            | () -> Enumerator[Notification, self]
+    def respond: (id: Integer, ?val: Integer, ?error: Integer, ?flags: Integer) -> nil
+    def id_valid?: (Integer) -> bool
+    def add_fd: (id: Integer, source_fd: Integer, ?flags: Integer, ?newfd: Integer, ?newfd_flags: Integer) -> Integer
+    def close: () -> nil
+    def closed?: () -> bool
+  end
+
+  class Notification
+    attr_reader id: Integer
+    attr_reader pid: Integer
+    attr_reader flags: Integer
+    attr_reader syscall: Integer
+    attr_reader arch: Integer
+    attr_reader instruction_pointer: Integer
+    attr_reader args: Array[Integer]
+    def initialize: (Notifier, Hash[Symbol, untyped]) -> void
+    def valid?: () -> bool
+    def respond: (?val: Integer, ?error: errno, ?flags: Integer) -> nil
+    def allow: (?Integer) -> nil
+    def deny: (errno) -> nil
+    def continue!: () -> nil
+    def add_fd: (IO, ?flags: Integer, ?newfd: Integer, ?newfd_flags: Integer) -> Integer
+  end
+end