seccomp-ruby 0.1.0

data/lib/seccomp/arch.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Architecture tokens and name conversion.
+  module Arch
+    module_function
+
+    # @return [Hash<Symbol, Integer>] constants available in the linked header
+    # @example `Arch.all[:x86_64]`
+    def all
+      @all ||= constants(false).grep_v(:NAMES).to_h do |name|
+        [name.to_s.downcase.to_sym, const_get(name)]
+      end.freeze
+    end
+
+    # @return [Integer] native runtime architecture token
+    # @example `Arch.native`
+    def native
+      LowLevel.arch_native
+    end
+
+    # @param value [Symbol, String, Integer] architecture
+    # @return [Integer] architecture token
+    # @raise [ArgumentError] for an unknown name
+    # @example `Arch.resolve(:x86_64)`
+    def resolve(value)
+      return value if value.is_a?(Integer)
+      unless value.respond_to?(:to_sym)
+        raise ArgumentError, "unknown architecture: #{value.inspect}"
+      end
+
+      key = value.to_sym
+      all.fetch(key) do
+        token = LowLevel.arch_resolve_name(value.to_s)
+        raise ArgumentError, "unknown architecture: #{value.inspect}" if token.zero?
+
+        token
+      end
+    end
+
+    # @param token [Integer] architecture token
+    # @return [Symbol, nil] known name
+    # @example `Arch.name(Arch.native)`
+    def name(token)
+      all.key(token) || (token == native ? all.key(native) : nil)
+    end
+  end
+end

data/lib/seccomp/arg.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Immutable syscall argument comparison.
+  class ArgCmp
+    # Largest accepted unsigned syscall datum.
+    # @api private
+    MAX_DATUM = (1 << 64) - 1
+    # Symbol-to-C-operator lookup.
+    # @api private
+    OPERATORS = {
+      ne: Compare::NE,
+      lt: Compare::LT,
+      le: Compare::LE,
+      eq: Compare::EQ,
+      ge: Compare::GE,
+      gt: Compare::GT,
+      masked_eq: Compare::MASKED_EQ
+    }.freeze
+
+    attr_reader :arg, :op, :datum_a, :datum_b
+
+    # @param arg [Integer] argument index from 0 through 5
+    # @param op [Symbol] comparison operator
+    # @param datum_a [Integer] first comparison datum
+    # @param datum_b [Integer] second datum for masked equality
+    # @param width [Integer] 32 or 64
+    # @return [void]
+    # @raise [ArgumentError] for invalid input
+    # @example `ArgCmp.new(arg: 0, op: :eq, datum_a: 2)`
+    def initialize(arg:, op:, datum_a:, datum_b: 0, width: 64)
+      unless arg.is_a?(Integer) && (0..5).cover?(arg)
+        raise ArgumentError, "arg must be an Integer between 0 and 5"
+      end
+      raise ArgumentError, "width must be 32 or 64" unless [32, 64].include?(width)
+
+      @arg = arg
+      operator = op.to_sym if op.respond_to?(:to_sym)
+      @op = OPERATORS.fetch(operator) { raise ArgumentError, "unknown comparison: #{op.inspect}" }
+      @datum_a = datum(datum_a, width)
+      @datum_b = datum(datum_b, width)
+    end
+
+    # @return [Array<Integer>] low-level comparison tuple
+    # @example `comparison.to_a`
+    def to_a
+      [arg, op, datum_a, datum_b]
+    end
+
+    private
+
+    def datum(value, width)
+      raise ArgumentError, "datum must be an Integer" unless value.is_a?(Integer)
+      raise ArgumentError, "datum must be between 0 and 2**64-1" unless (0..MAX_DATUM).cover?(value)
+
+      width == 32 ? value & 0xFFFF_FFFF : value
+    end
+  end
+
+  # Argument comparison DSL.
+  module Arg
+    # Builder bound to one syscall argument index.
+    class Reference
+      # @param index [Integer] argument index from 0 through 5
+      # @return [void]
+      # @raise [ArgumentError] outside 0..5
+      # @example `Reference.new(0)`
+      def initialize(index)
+        unless index.is_a?(Integer) && (0..5).cover?(index)
+          raise ArgumentError, "arg must be an Integer between 0 and 5"
+        end
+
+        @index = index
+      end
+
+      %i[ne lt le eq ge gt].each do |operator|
+        define_method(operator) do |value, width: 64|
+          ArgCmp.new(arg: @index, op: operator, datum_a: value, width: width)
+        end
+      end
+
+      alias == eq
+
+      # Build a masked equality comparison.
+      # @param mask [Integer] bit mask
+      # @param value [Integer] expected masked value
+      # @param width [Integer] 32 or 64
+      # @return [ArgCmp]
+      # @raise [ArgumentError] for invalid data
+      # @example `reference.masked_eq(mask: 0xff, value: 1)`
+      def masked_eq(mask:, value:, width: 64)
+        ArgCmp.new(arg: @index, op: :masked_eq, datum_a: mask, datum_b: value, width: width)
+      end
+    end
+
+    # Adds {#arg} to filter and DSL contexts.
+    module DSL
+      # @param index [Integer] argument index
+      # @return [Reference] comparison builder
+      # @raise [ArgumentError] outside 0..5
+      # @example `arg(0).eq(2)`
+      def arg(index)
+        Reference.new(index)
+      end
+    end
+  end
+end

data/lib/seccomp/attributes.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Named accessors for libseccomp filter attributes.
+  module Attributes
+    # Symbol-to-C-attribute lookup.
+    # @api private
+    ATTRIBUTE_NAMES = {
+      default_action: FilterAttr::ACT_DEFAULT,
+      bad_arch_action: FilterAttr::ACT_BADARCH,
+      no_new_privs: FilterAttr::CTL_NNP,
+      tsync: FilterAttr::CTL_TSYNC,
+      tskip: FilterAttr::API_TSKIP,
+      log: FilterAttr::CTL_LOG,
+      ssb: FilterAttr::CTL_SSB,
+      optimize: FilterAttr.const_defined?(:CTL_OPTIMIZE) ? FilterAttr::CTL_OPTIMIZE : nil,
+      raw_rc: FilterAttr.const_defined?(:API_SYSRAWRC) ? FilterAttr::API_SYSRAWRC : nil,
+      wait_killable: FilterAttr.const_defined?(:CTL_WAITKILL) ? FilterAttr::CTL_WAITKILL : nil
+    }.compact.freeze
+
+    # Attributes exposed as predicate accessors.
+    # @api private
+    BOOLEAN_ATTRIBUTES = %i[no_new_privs tsync tskip log ssb raw_rc wait_killable].freeze
+    # Minimum runtime API level for newer attributes.
+    # @api private
+    ATTRIBUTE_API_LEVELS = {
+      FilterAttr::CTL_TSYNC => 2,
+      FilterAttr::CTL_LOG => 3,
+      FilterAttr::CTL_SSB => 4,
+      (FilterAttr::CTL_WAITKILL if FilterAttr.const_defined?(:CTL_WAITKILL)) => 7
+    }.compact.freeze
+
+    # @param attribute [Symbol, Integer] attribute name or enum value
+    # @return [Integer] raw attribute value
+    # @raise [Error] if the attribute cannot be read
+    # @example `filter[:optimize]`
+    def [](attribute)
+      synchronize do
+        rc, value = LowLevel.attr_get(@context, resolve_attribute(attribute))
+        Error.check!(rc, call: "seccomp_attr_get", hint: "attribute #{attribute}")
+        value
+      end
+    end
+
+    # @param attribute [Symbol, Integer] attribute name or enum value
+    # @param value [Integer] raw attribute value
+    # @return [Integer] assigned value
+    # @raise [Error] if the attribute cannot be set
+    # @example `filter[:optimize] = 2`
+    def []=(attribute, value)
+      synchronize do
+        resolved = resolve_attribute(attribute)
+        value = Action.resolve(value) if resolved == FilterAttr::ACT_BADARCH
+        if resolved == FilterAttr::CTL_TSYNC && value.is_a?(Integer) && !value.zero?
+          ensure_notification_tsync_supported!(tsync: true)
+        end
+
+        Error.check!(LowLevel.attr_set(@context, resolved, value),
+                     call: "seccomp_attr_set", hint: "attribute #{attribute}")
+      end
+      value
+    end
+
+    # @return [Integer] default action
+    # @example `filter.default_action`
+    def default_action
+      self[:default_action]
+    end
+
+    # @return [Integer] action for unsupported architectures
+    # @example `filter.bad_arch_action`
+    def bad_arch_action
+      self[:bad_arch_action]
+    end
+
+    # @param value [Symbol, Integer] action
+    # @return [Integer] assigned action
+    # @raise [Error] if rejected
+    # @example `filter.bad_arch_action = :kill_process`
+    def bad_arch_action=(value)
+      self[:bad_arch_action] = value
+    end
+
+    BOOLEAN_ATTRIBUTES.each do |name|
+      define_method("#{name}?") { self[name] != 0 }
+      define_method("#{name}=") do |value|
+        enabled = !!value
+        self[name] = enabled ? 1 : 0
+        enabled
+      end
+    end
+
+    # @return [Integer] optimization level
+    # @example `filter.optimize`
+    def optimize
+      self[:optimize]
+    end
+
+    # @param value [Integer] optimization level
+    # @return [Integer] assigned level
+    # @raise [Error] if rejected
+    # @example `filter.optimize = 2`
+    def optimize=(value)
+      self[:optimize] = value
+    end
+
+    private
+
+    def resolve_attribute(attribute)
+      resolved = if attribute.is_a?(Integer)
+                   attribute
+                 elsif attribute.respond_to?(:to_sym)
+                   ATTRIBUTE_NAMES.fetch(attribute.to_sym) do
+                     message = "filter attribute is not available: #{attribute.inspect}"
+                     raise NotSupportedError, message
+                   end
+                 else
+                   raise ArgumentError, "unknown filter attribute: #{attribute.inspect}"
+                 end
+      required = ATTRIBUTE_API_LEVELS[resolved]
+      return resolved unless required
+      return resolved if Seccomp.api_level >= required
+
+      raise NotSupportedError, "filter attribute requires libseccomp API level #{required}"
+    end
+  end
+end

data/lib/seccomp/dsl.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Convenience methods used by {Seccomp.filter} blocks.
+  module DSL
+    # @param architectures [Array<Symbol, String, Integer>] architectures to add
+    # @return [Filter] receiver
+    # @raise [Error] if an architecture cannot be added
+    # @example `arch :x86_64, :x86`
+    def arch(*architectures)
+      architectures.each { |architecture| add_arch(architecture) }
+      self
+    end
+
+    # @param value [Boolean] no-new-privileges setting
+    # @return [Filter] receiver
+    # @raise [Error] if rejected
+    # @example `no_new_privs true`
+    def no_new_privs(value)
+      self.no_new_privs = value
+      self
+    end
+
+    # @param value [Boolean] thread synchronization setting
+    # @return [Filter] receiver
+    # @raise [Error] if rejected
+    # @example `tsync true`
+    def tsync(value)
+      self.tsync = value
+      self
+    end
+  end
+end

data/lib/seccomp/errors.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Seccomp
+  # Base error carrying the libseccomp errno and C call name.
+  class Error < StandardError
+    attr_reader :errno, :call
+
+    # errno-to-exception lookup.
+    # @api private
+    ERRORS = {
+      Errno::EACCES::Errno => :PermissionError,
+      Errno::ECANCELED::Errno => :KernelError,
+      Errno::EDOM::Errno => :ArchError,
+      Errno::EEXIST::Errno => :ExistsError,
+      Errno::EINVAL::Errno => :InvalidArgumentError,
+      Errno::ENOENT::Errno => :NotFoundError,
+      Errno::ENOMEM::Errno => :OutOfMemoryError,
+      Errno::EOPNOTSUPP::Errno => :NotSupportedError,
+      Errno::ERANGE::Errno => :ValueRangeError,
+      Errno::ESRCH::Errno => :ThreadSyncError
+    }.freeze
+
+    # @param message [String, nil] error message
+    # @param errno [Integer, nil] positive errno
+    # @param call [String, nil] C function name
+    # @return [void]
+    # @example `Error.new("failed", errno: 22, call: "seccomp_init")`
+    def initialize(message = nil, errno: nil, call: nil)
+      @errno = errno
+      @call = call
+      super(message)
+    end
+
+    # @param result [Integer] libseccomp return code
+    # @param call [String] C function name
+    # @param hint [String, nil] contextual hint
+    # @return [Integer] nonnegative result
+    # @raise [Error] for a negative result
+    # @example `Error.check!(0, call: "seccomp_load")`
+    def self.check!(result, call:, hint: nil)
+      return result unless result.negative?
+
+      errno = -result
+      name = Errno.constants.find do |constant|
+        error_class = Errno.const_get(constant)
+        error_class.is_a?(Class) && error_class < SystemCallError && errno == error_class::Errno
+      end
+      klass = Seccomp.const_get(ERRORS.fetch(errno, :Error))
+      message = "#{call} failed: #{name || "errno #{errno}"}"
+      message += " (#{hint})" if hint
+      raise klass.new(message, errno: errno, call: call)
+    end
+  end
+
+  # Operation was not permitted by libseccomp.
+  class PermissionError < Error; end
+  # Kernel-side filter generation or loading failed.
+  class KernelError < Error; end
+  # Architecture or ABI is invalid for the operation.
+  class ArchError < Error; end
+  # Architecture or rule already exists.
+  class ExistsError < Error; end
+  # An argument was rejected by libseccomp.
+  class InvalidArgumentError < Error; end
+  # Requested object was not found.
+  class NotFoundError < Error; end
+  # Native allocation failed.
+  class OutOfMemoryError < Error; end
+  # Linked libseccomp or kernel lacks the feature.
+  class NotSupportedError < Error; end
+  # A value is outside the supported range.
+  class ValueRangeError < Error; end
+  # Thread synchronization failed.
+  class ThreadSyncError < Error; end
+  # Syscall name could not be resolved.
+  class UnknownSyscallError < Error; end
+  # A released filter was accessed.
+  class ClosedFilterError < Error; end
+  # Base user-notification error.
+  class NotificationError < Error; end
+  # Notification target exited before a response.
+  class NotificationCanceledError < NotificationError; end
+end