seccomp-notify 0.1.0

data/lib/seccomp/notify/policy.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Seccomp
+  module Notify
+    class Policy
+      BOOTSTRAP_SYSCALLS = %i[fcntl sendmsg].freeze
+      ALLOWED_FLAGS = Constants::SECCOMP_FILTER_FLAG_LOG |
+        Constants::SECCOMP_FILTER_FLAG_SPEC_ALLOW |
+        Constants::SECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV
+      DEFAULTS = {
+        allow: Constants::SECCOMP_RET_ALLOW,
+        errno: Constants::SECCOMP_RET_ERRNO | Errno::EPERM::Errno,
+        kill: Constants::SECCOMP_RET_KILL_PROCESS
+      }.freeze
+
+      attr_reader :default_action
+
+      def initialize(default: :allow, deny_io_uring: true, flags: 0, &block)
+        @default_action = DEFAULTS.fetch(default) { raise InvalidPolicyError, "invalid default action: #{default.inspect}" }
+        raise ArgumentError, "flags must be an integer" unless flags.is_a?(Integer)
+
+        @flags = flags
+        @notifications = []
+        @denials = {}
+        deny_io_uring! if deny_io_uring
+        instance_eval(&block) if block
+        validate!
+      end
+
+      # Marks syscalls for supervisor notification.
+      # @param names [Array<Symbol>]
+      # @return [void]
+      def notify(*names)
+        @notifications.concat(names.map(&:to_sym))
+      end
+
+      # Rejects syscalls in the kernel without notifying the supervisor.
+      # @param names [Array<Symbol>]
+      # @param errno [Class, Integer] an Errno class or numeric errno
+      # @return [void]
+      def deny(*names, errno: Errno::EPERM)
+        number = Constants.errno_number(errno)
+        names.each { |name| @denials[name.to_sym] = number }
+      end
+
+      # Denies io_uring setup so submitted I/O cannot bypass seccomp.
+      #
+      # @return [void]
+      def deny_io_uring!
+        deny(:io_uring_setup, errno: Errno::ENOSYS)
+      end
+
+      def flags
+        @flags
+      end
+
+      def decisions(arch)
+        validate!
+        notified = @notifications.to_h { |name| [Syscalls.number(name, arch), Constants::SECCOMP_RET_USER_NOTIF] }
+        denied = @denials.to_h { |name, errno| [Syscalls.number(name, arch), Constants::SECCOMP_RET_ERRNO | errno] }
+        notified.merge(denied).tap do |decisions|
+          BOOTSTRAP_SYSCALLS.each do |name|
+            decisions[Syscalls.number(name, arch)] = Constants::SECCOMP_RET_ALLOW unless @default_action == Constants::SECCOMP_RET_ALLOW
+          end
+        end
+      end
+
+      def notified?(name)
+        @notifications.include?(name.to_sym)
+      end
+
+      private
+
+      def validate!
+        invalid_bootstrap = BOOTSTRAP_SYSCALLS.find { |name| notified?(name) || @denials.key?(name) }
+        if invalid_bootstrap
+          raise InvalidPolicyError, "#{invalid_bootstrap} must be allowed while transferring the listener fd"
+        end
+        raise InvalidPolicyError, "TSYNC and NEW_LISTENER cannot be combined" if (@flags & Constants::SECCOMP_FILTER_FLAG_TSYNC).positive?
+        raise InvalidPolicyError, "unsupported filter flags: 0x#{@flags.to_s(16)}" unless (@flags & ~ALLOWED_FLAGS).zero?
+      end
+    end
+  end
+end

data/lib/seccomp/notify/request.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Seccomp
+  module Notify
+    class Request
+      attr_reader :id, :tid, :flags, :nr, :instruction_pointer, :args
+      alias_method :pid, :tid
+
+      def self.from_binary(binary, listener:, sizes:, memory_cache:, memory_cache_mutex:, features:)
+        id, tid, flags, nr, audit_arch, ip, *args = binary.unpack(Structs::NOTIF_FORMAT)
+        arch = case audit_arch
+        when Constants::AUDIT_ARCH_X86_64 then :x86_64
+        when Constants::AUDIT_ARCH_AARCH64 then :aarch64
+        else raise NotSupportedError, "unsupported audit architecture 0x#{audit_arch.to_s(16)}"
+        end
+        new(id:, tid:, flags:, nr:, arch:, instruction_pointer: ip, args:, listener:, sizes:, memory_cache:, memory_cache_mutex:, features:)
+      end
+
+      def initialize(id:, tid:, flags:, nr:, arch:, instruction_pointer:, args:, listener:, sizes:, memory_cache:, memory_cache_mutex:, features:)
+        @id = id
+        @tid = tid
+        @flags = flags
+        @nr = nr
+        @arch = arch
+        @instruction_pointer = instruction_pointer
+        @args = args.freeze
+        @listener = listener
+        @sizes = sizes
+        @features = features
+        @memory = TargetMemory.new(listener, self, memory_cache, memory_cache_mutex)
+        @responded = false
+        @pointer_read = false
+      end
+
+      attr_reader :arch
+
+      def syscall
+        Syscalls.name(@nr, @arch)
+      end
+
+      def responded?
+        @responded
+      end
+
+      def valid?
+        buffer = [@id].pack("Q<")
+        validate_id(Ioctl::NOTIF_ID_VALID, buffer)
+        true
+      rescue Errno::EINVAL
+        begin
+          validate_id(Ioctl::NOTIF_ID_VALID_OLD, buffer)
+          true
+        rescue Errno::ENOENT
+          false
+        end
+      rescue Errno::ENOENT
+        false
+      end
+
+      # Reads bytes from target memory and revalidates the notification afterward.
+      # @return [String]
+      def read(address, length)
+        @memory.read(address, length)
+      end
+
+      # Reads a NUL-terminated string from target memory.
+      # @return [String]
+      def read_string(address, max: 4096)
+        @memory.read_string(address, max:)
+      end
+      alias_method :read_cstring, :read_string
+
+      # Decodes an AF_INET, AF_INET6, or AF_UNIX socket address.
+      # @return [Addrinfo]
+      def read_sockaddr(address, length)
+        @memory.read_sockaddr(address, length)
+      end
+
+      # Emulates a successful syscall return.
+      # @return [void]
+      def allow!(value = 0)
+        respond!(value:, error: 0, flags: 0)
+      end
+
+      # Emulates a failed syscall return.
+      # @return [void]
+      def error!(error = Errno::EPERM)
+        errno = Constants.errno_number(error)
+        respond!(value: 0, error: -errno, flags: 0)
+      end
+
+      # Lets the kernel execute the original syscall.
+      # @param unsafe [Boolean] acknowledges pointer-read TOCTOU risk
+      # @return [void]
+      def continue!(unsafe: false)
+        raise NotSupportedError, "SECCOMP_USER_NOTIF_FLAG_CONTINUE is unavailable" unless @features[:continue]
+        warn("seccomp-notify: continuing after reading target memory is subject to TOCTOU; pass unsafe: true to acknowledge") if @pointer_read && !unsafe
+        respond!(value: 0, error: 0, flags: Constants::SECCOMP_USER_NOTIF_FLAG_CONTINUE)
+      end
+
+      # Injects an open file descriptor into the target.
+      # @return [Integer] the target file descriptor number
+      def add_fd!(io, flags: 0, newfd: 0, newfd_flags: 0)
+        raise NotSupportedError, "SECCOMP_IOCTL_NOTIF_ADDFD is unavailable" unless @features[:addfd]
+        ensure_unresponded!
+        unless [flags, newfd, newfd_flags].all? { |value| value.is_a?(Integer) } && (0..0xffff_ffff).cover?(newfd)
+          raise ArgumentError, "flags and fd values must be unsigned integers"
+        end
+        unless (flags & ~Constants::SECCOMP_ADDFD_FLAG_SETFD).zero?
+          raise ArgumentError, "flags may only contain SECCOMP_ADDFD_FLAG_SETFD"
+        end
+        unless (newfd_flags & ~Constants::O_CLOEXEC).zero?
+          raise ArgumentError, "newfd_flags may only contain O_CLOEXEC"
+        end
+        if (flags & Constants::SECCOMP_ADDFD_FLAG_SETFD).zero? && !newfd.zero?
+          raise ArgumentError, "newfd requires SECCOMP_ADDFD_FLAG_SETFD"
+        end
+
+        addfd_flags = flags
+        addfd_flags |= Constants::SECCOMP_ADDFD_FLAG_SEND if @features[:addfd_send]
+        buffer = [@id, addfd_flags, io.fileno, newfd, newfd_flags].pack(Structs::ADDFD_FORMAT)
+        injected = Ioctl.call(@listener, Ioctl::NOTIF_ADDFD, buffer)
+        if @features[:addfd_send]
+          @responded = true
+        else
+          allow!(injected)
+        end
+        injected
+      end
+
+      def kill!(signal = "KILL")
+        ensure_unresponded!
+        Process.kill(signal, @tid)
+        @responded = true
+      end
+
+      def mark_pointer_read!
+        @pointer_read = true
+      end
+
+      private
+
+      def validate_id(request, buffer)
+        Ioctl.call(@listener, request, buffer)
+      rescue Errno::EINTR
+        retry
+      end
+
+      def respond!(value:, error:, flags:)
+        ensure_unresponded!
+        buffer = [@id, value, error, flags].pack(Structs::RESPONSE_FORMAT).ljust(@sizes[:resp], "\0")
+        Ioctl.call(@listener, Ioctl::NOTIF_SEND, buffer)
+        @responded = true
+      rescue Errno::EINTR
+        retry
+      rescue Errno::ENOENT
+        @responded = true
+      end
+
+      def ensure_unresponded!
+        raise AlreadyRespondedError, "notification #{@id} has already been answered" if @responded
+      end
+    end
+  end
+end

data/lib/seccomp/notify/structs.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Seccomp
+  module Notify
+    module Structs
+      NOTIF_FORMAT = "Q<L<L<l<L<Q<Q<6"
+      RESPONSE_FORMAT = "Q<q<l<L<"
+      ADDFD_FORMAT = "Q<L<L<L<L<"
+      SIZES_FORMAT = "S<S<S<"
+      INSTRUCTION_FORMAT = "S<CCL<"
+      PROGRAM_FORMAT = "S<x6J<"
+
+      NOTIF_SIZE = 80
+      RESPONSE_SIZE = 24
+      ADDFD_SIZE = 24
+      SIZES_SIZE = 6
+      INSTRUCTION_SIZE = 8
+      PROGRAM_SIZE = 16
+    end
+  end
+end

data/lib/seccomp/notify/supervisor.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Seccomp
+  module Notify
+    class Supervisor
+      USER_OPTIONS = %i[poll_interval default_errno timeout concurrency features].freeze
+      EXPECTED_SIZES = {notif: Structs::NOTIF_SIZE, resp: Structs::RESPONSE_SIZE, data: 64}.freeze
+
+      attr_reader :listener, :target_pid
+
+      def self.validate_options!(options)
+        unknown = options.keys - USER_OPTIONS
+        raise ArgumentError, "unknown supervisor options: #{unknown.join(", ")}" unless unknown.empty?
+        if options.key?(:concurrency) && (!options[:concurrency].is_a?(Integer) || !options[:concurrency].positive?)
+          raise ArgumentError, "concurrency must be a positive integer"
+        end
+        if options.key?(:poll_interval) && !valid_duration?(options[:poll_interval], allow_zero: true)
+          raise ArgumentError, "poll_interval must be non-negative"
+        end
+        if options[:timeout] && !valid_duration?(options[:timeout], allow_zero: false)
+          raise ArgumentError, "timeout must be positive"
+        end
+        if options.key?(:features) && !options[:features].is_a?(Hash)
+          raise ArgumentError, "features must be a hash"
+        end
+        return unless options.key?(:default_errno)
+
+        Constants.errno_number(options[:default_errno])
+      end
+
+      def self.valid_duration?(value, allow_zero:)
+        value.is_a?(Numeric) && value.real? && value.finite? && (allow_zero ? !value.negative? : value.positive?)
+      end
+
+      def initialize(listener, target_pid: nil, target_child: nil, poll_interval: 0.1, default_errno: Errno::EPERM,
+        timeout: nil, concurrency: 1, features: Notify.features, health_writer: nil)
+        self.class.validate_options!(poll_interval:, default_errno:, timeout:, concurrency:, features:)
+
+        @listener = listener
+        @target_pid = target_pid
+        @target_child = target_child
+        @poll_interval = poll_interval
+        @default_errno = default_errno
+        @timeout = timeout
+        @concurrency = concurrency
+        @features = features
+        @health_writer = health_writer
+        @sizes = Notify.notif_sizes
+        raise NotSupportedError, "unsupported kernel notification sizes: #{@sizes.inspect}" unless @sizes == EXPECTED_SIZES
+
+        @handlers = {}
+        @unknown_handler = ->(request) { request.error!(@default_errno) }
+        @error_handler = ->(error, _request) { warn("seccomp-notify supervisor: #{error.full_message(highlight: false, order: :top)}") }
+        @memory_cache = {}
+        @memory_cache_mutex = Mutex.new
+        @receive_mutex = Mutex.new
+        @stop = false
+        @listener_closed = false
+      end
+
+      # Registers a handler for a notified syscall.
+      # @param syscall [Symbol]
+      # @yieldparam request [Request]
+      # @return [Supervisor]
+      def on(syscall, &handler)
+        raise ArgumentError, "handler block is required" unless handler
+
+        @handlers[syscall.to_sym] = handler
+        self
+      end
+
+      # Registers the fallback handler for unregistered syscalls.
+      # @yieldparam request [Request]
+      # @return [Supervisor]
+      def on_unknown(&handler)
+        raise ArgumentError, "handler block is required" unless handler
+
+        @unknown_handler = handler
+        self
+      end
+
+      # Registers an exception callback.
+      # @yieldparam error [Exception]
+      # @yieldparam request [Request]
+      # @return [Supervisor]
+      def on_error(&handler)
+        raise ArgumentError, "handler block is required" unless handler
+
+        @error_handler = handler
+        self
+      end
+
+      # Runs until the target exits and returns its process status when available.
+      # @return [Process::Status, nil]
+      def run
+        workers = Array.new(@concurrency) { Thread.new { event_loop } }
+        status = wait_for_target
+        wait_until_listener_closes if @target_pid && !@stop
+        @stop = true
+        workers.each(&:join)
+        status
+      ensure
+        @stop = true
+        @memory_cache.each_value { |io| io.close unless io.closed? }
+        @listener.close unless @listener.closed?
+        @health_writer&.close unless @health_writer&.closed?
+      end
+
+      def stop
+        @stop = true
+      end
+
+      private
+
+      def wait_for_target
+        return wait_until_listener_closes unless @target_pid
+
+        loop do
+          return if @stop
+
+          waited = Process.waitpid2(@target_pid, Process::WNOHANG)
+          return waited.last if waited
+          sleep(@poll_interval)
+        end
+      rescue Errno::ECHILD
+        return if @target_child
+
+        wait_for_non_child
+      end
+
+      def wait_for_non_child
+        loop do
+          return if @stop
+
+          Process.kill(0, @target_pid)
+          sleep(@poll_interval)
+        end
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def wait_until_listener_closes
+        sleep(@poll_interval) until @stop || @listener_closed
+      end
+
+      def event_loop
+        process_one until @stop || @listener_closed
+      rescue IOError, Errno::EBADF, Errno::ENOTCONN
+        @stop = true
+      rescue StandardError => error
+        warn("seccomp-notify worker failed: #{error.message}")
+        @stop = true
+      end
+
+      def process_one
+        request = @receive_mutex.synchronize { receive_request }
+        return unless request
+
+        dispatch(request)
+      rescue Errno::EINTR
+        retry
+      rescue Errno::ENOENT
+        @listener_closed = true if Libc.poll_hup?(@listener.fileno)
+        nil
+      end
+
+      def receive_request
+        return unless IO.select([@listener], nil, nil, @poll_interval)
+
+        buffer = "\0" * @sizes[:notif]
+        Ioctl.call(@listener, Ioctl::NOTIF_RECV, buffer)
+        Request.from_binary(
+          buffer,
+          listener: @listener,
+          sizes: @sizes,
+          memory_cache: @memory_cache,
+          memory_cache_mutex: @memory_cache_mutex,
+          features: @features
+        )
+      end
+
+      def dispatch(request)
+        handler = @handlers.fetch(request.syscall, @unknown_handler)
+        @timeout ? Timeout.timeout(@timeout) { handler.call(request) } : handler.call(request)
+      rescue StandardError => error
+        begin
+          @error_handler.call(error, request)
+        rescue Exception => callback_error # rubocop:disable Lint/RescueException
+          warn("seccomp-notify error callback failed: #{callback_error.message}")
+        end
+      ensure
+        request&.error!(@default_errno) unless request&.responded?
+      end
+    end
+  end
+end