seccomp-tools 1.6.2 → 1.7.1

data/lib/seccomp-tools/util.rb

@@ -1,38 +1,80 @@
 # frozen_string_literal: true
 
 module SeccompTools
-  # Define utility methods.
+  # Utility methods shared across the library: architecture detection and terminal colorizing.
   module Util
     module_function
 
     # Get currently supported architectures.
+    #
+    # Derived from the syscall tables shipped under +consts/sys_nr/+.
     # @return [Array<Symbol>]
-    #   Architectures.
+    #   Architecture names, sorted.
     def supported_archs
       @supported_archs ||= Dir.glob(File.join(__dir__, 'consts', 'sys_nr', '*.rb'))
                               .map { |f| File.basename(f, '.rb').to_sym }
                               .sort
     end
 
+    # Whether the host operating system is Linux, where the +ptrace+-based dumping works.
+    # @return [Boolean]
+    def linux?
+      RbConfig::CONFIG['host_os'].include?('linux')
+    end
+
     # Detect system architecture.
     # @return [Symbol]
+    #   One of {supported_archs}, or +:unknown+ if the host CPU is not supported.
     def system_arch
       case RbConfig::CONFIG['host_cpu']
       when /x86_64/ then :amd64
       when /i386/ then :i386
       when /aarch64/ then :aarch64
+      when /riscv64/ then :riscv64
       when /s390x/ then :s390x
       else :unknown
       end
     end
 
+    # ELF +e_machine+ values (the halfword at offset 18) of the architectures seccomp-tools supports,
+    # as they are laid out in the file - so the big-endian s390x reads the other way around. The keys
+    # are binary strings (+.b+) to match what is read off the file: this source is UTF-8, where a
+    # literal such as +"\xb7\x00"+ would never compare equal to those bytes.
+    ELF_MACHINE = {
+      "\x03\x00".b => :i386,
+      "\x3e\x00".b => :amd64,
+      "\xb7\x00".b => :aarch64,
+      "\xf3\x00".b => :riscv64,
+      "\x00\x16".b => :s390x
+    }.freeze
+
+    # The architecture a running process was built for, read from the ELF header of its executable.
+    #
+    # Filters dumped from another process are numbered for *its* architecture, so this is what makes
+    # the syscall names right when it differs from the host.
+    # @param [Integer] pid
+    #   Process identifier.
+    # @return [Symbol?]
+    #   One of {supported_archs}, or +nil+ when the executable cannot be read (no +/proc+, the
+    #   process is gone, permission denied) or its machine type is not one we know.
+    def process_arch(pid)
+      File.open("/proc/#{pid}/exe", 'rb') do |f|
+        f.pos = 18
+        ELF_MACHINE[f.read(2)]
+      end
+    rescue SystemCallError
+      nil
+    end
+
     # Enable colorize.
+    #
+    # Colors are still only emitted when the output is a tty, see {colorize_enabled?}.
     # @return [void]
     def enable_color!
       @disable_color = false
     end
 
-    # Disable colorize.
+    # Disable colorize, {colorize} becomes a no-op regardless of the output being a tty.
     # @return [void]
     def disable_color!
       @disable_color = true
@@ -40,28 +82,35 @@ module SeccompTools
 
     # Is colorize enabled?
     # @return [Boolean]
+    #   +true+ only if colors have not been disabled by {disable_color!} and +$stdout+ is a tty.
     def colorize_enabled?
       !@disable_color && $stdout.tty?
     end
 
     # color code of light yellow
     LIGHT_YELLOW = "\e[38;5;230m"
-    # Color codes for pretty print.
+    # Color codes for pretty print. +error+, +warn+ and +info+ are severities rather than parts of a
+    # filter, shading from alarming to quiet; {SeccompTools::Logger} colors its own levels by the
+    # same names.
     COLOR_CODE = {
       esc_m: "\e[0m",
       syscall: "\e[38;5;120m", # light green
       arch: LIGHT_YELLOW,
       args: LIGHT_YELLOW,
       gray: "\e[2m",
-      error: "\e[38;5;196m" # heavy red
+      error: "\e[38;5;196m", # heavy red
+      warn: LIGHT_YELLOW,
+      info: "\e[38;5;110m" # light blue
     }.freeze
-    # Wrapper color codes.
-    # @param [String] s
-    #   Contents to wrapper.
+    # Wrap contents with terminal color codes.
+    #
+    # Returns +s+ unchanged when {colorize_enabled?} is +false+.
+    # @param [#to_s] s
+    #   Contents to be wrapped.
     # @param [Symbol?] t
-    #   Specific which kind of color to use, valid symbols are defined in {Util.COLOR_CODE}.
+    #   Which kind of color to use, valid symbols are the keys of {Util::COLOR_CODE}.
     # @return [String]
-    #   Wrapper with color codes.
+    #   +s+ wrapped with color codes.
     def colorize(s, t: nil)
       s = s.to_s
       return s unless colorize_enabled?
@@ -71,13 +120,29 @@ module SeccompTools
       "#{color}#{s.sub(cc[:esc_m], cc[:esc_m] + color)}#{cc[:esc_m]}"
     end
 
+    # Does the file at +path+ start with the ELF magic bytes?
+    #
+    # Used to tell an executable apart from a raw BPF blob.
+    # @param [String] path
+    #   Path to the file to check.
+    # @return [Boolean]
+    #   +false+ when the file cannot be read.
+    def elf?(path)
+      File.binread(path, 4) == "\x7fELF".b
+    rescue SystemCallError
+      false
+    end
+
     # Get content of filename under directory templates/.
     #
     # @param [String] filename
-    #   The filename.
+    #   Basename of a file under +lib/seccomp-tools/templates/+.
     #
     # @return [String]
     #   Content of the file.
+    #
+    # @raise [Errno::ENOENT]
+    #   If no such template exists.
     def template(filename)
       File.binread(File.join(__dir__, 'templates', filename))
     end

data/lib/seccomp-tools/version.rb

@@ -2,5 +2,5 @@
 
 module SeccompTools
   # Gem version.
-  VERSION = '1.6.2'
+  VERSION = '1.7.1'
 end

data/lib/seccomp-tools.rb

@@ -2,7 +2,16 @@
 
 # @author david942j
 
-# Main module.
+# Toolkit for working with seccomp BPF filters.
+#
+# The library entry points are {Asm.asm} to compile assembly into raw BPF, {Disasm.disasm} to turn
+# raw BPF back into readable assembly, {Dumper.dump} to capture the filters a process installs, and
+# {Emulator} to run a filter against a hypothetical syscall.
+#
+# @example
+#   raw = SeccompTools::Asm.asm("return ALLOW\n", arch: :amd64)
+#   SeccompTools::Disasm.disasm(raw, arch: :amd64, display_bpf: false)
+#   #=> "0000: return ALLOW\n"
 module SeccompTools
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seccomp-tools
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.1
 platform: ruby
 authors:
 - david942j
@@ -85,14 +85,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -121,26 +121,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: os
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: racc
   requirement: !ruby/object:Gem::Requirement
@@ -166,9 +146,13 @@ extensions:
 - ext/ptrace/extconf.rb
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - bin/seccomp-tools
+- completions/_seccomp-tools
+- completions/seccomp-tools.bash
+- completions/seccomp-tools.fish
 - ext/ptrace/extconf.rb
 - ext/ptrace/ptrace.c
 - lib/seccomp-tools.rb
@@ -180,24 +164,48 @@ files:
 - lib/seccomp-tools/asm/scanner.rb
 - lib/seccomp-tools/asm/statement.rb
 - lib/seccomp-tools/asm/token.rb
+- lib/seccomp-tools/audit.rb
+- lib/seccomp-tools/audit/catalog.rb
+- lib/seccomp-tools/audit/checks.rb
+- lib/seccomp-tools/audit/checks/arch_unchecked.rb
+- lib/seccomp-tools/audit/checks/dangerous_allow.rb
+- lib/seccomp-tools/audit/checks/orw_chain.rb
+- lib/seccomp-tools/audit/checks/permissive_default.rb
+- lib/seccomp-tools/audit/checks/syscall_alt_gap.rb
+- lib/seccomp-tools/audit/checks/x32_guard.rb
+- lib/seccomp-tools/audit/finding.rb
+- lib/seccomp-tools/audit/policy.rb
+- lib/seccomp-tools/audit/report.rb
 - lib/seccomp-tools/bpf.rb
 - lib/seccomp-tools/cli/asm.rb
+- lib/seccomp-tools/cli/audit.rb
 - lib/seccomp-tools/cli/base.rb
 - lib/seccomp-tools/cli/cli.rb
+- lib/seccomp-tools/cli/completion.rb
 - lib/seccomp-tools/cli/disasm.rb
 - lib/seccomp-tools/cli/dump.rb
+- lib/seccomp-tools/cli/dumpable.rb
 - lib/seccomp-tools/cli/emu.rb
+- lib/seccomp-tools/cli/explain.rb
+- lib/seccomp-tools/cli/filter_input.rb
 - lib/seccomp-tools/const.rb
 - lib/seccomp-tools/consts/sys_arg.rb
 - lib/seccomp-tools/consts/sys_nr/aarch64.rb
 - lib/seccomp-tools/consts/sys_nr/amd64.rb
 - lib/seccomp-tools/consts/sys_nr/i386.rb
+- lib/seccomp-tools/consts/sys_nr/riscv64.rb
 - lib/seccomp-tools/consts/sys_nr/s390x.rb
-- lib/seccomp-tools/disasm/context.rb
 - lib/seccomp-tools/disasm/disasm.rb
 - lib/seccomp-tools/dumper.rb
 - lib/seccomp-tools/emulator.rb
 - lib/seccomp-tools/error.rb
+- lib/seccomp-tools/explain.rb
+- lib/seccomp-tools/explain/analysis.rb
+- lib/seccomp-tools/explain/path_facts.rb
+- lib/seccomp-tools/explain/qword.rb
+- lib/seccomp-tools/explain/renderer.rb
+- lib/seccomp-tools/explain/summary.rb
+- lib/seccomp-tools/explain/verdict.rb
 - lib/seccomp-tools/instruction/alu.rb
 - lib/seccomp-tools/instruction/base.rb
 - lib/seccomp-tools/instruction/instruction.rb
@@ -209,6 +217,10 @@ files:
 - lib/seccomp-tools/instruction/st.rb
 - lib/seccomp-tools/instruction/stx.rb
 - lib/seccomp-tools/logger.rb
+- lib/seccomp-tools/symbolic/constraint.rb
+- lib/seccomp-tools/symbolic/executor.rb
+- lib/seccomp-tools/symbolic/expr.rb
+- lib/seccomp-tools/symbolic/state.rb
 - lib/seccomp-tools/syscall.rb
 - lib/seccomp-tools/templates/asm.amd64.asm
 - lib/seccomp-tools/templates/asm.c

data/lib/seccomp-tools/disasm/context.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module SeccompTools
-  module Disasm
-    # @private
-    #
-    # Context for disassembler to analyze.
-    #
-    # This class maintains:
-    # * if +reg/mem+ can be one of +data[*]+
-    # * if +data[0]+ (i.e. sys_number) is a known value
-    class Context
-      # @private
-      #
-      # Records the type and value.
-      class Value
-        attr_reader :val # @return [Integer]
-
-        # @param [:imm, :data, :mem] rel
-        # @param [Integer?] val
-        def initialize(rel: :imm, val: nil)
-          @rel = rel
-          @val = val
-        end
-
-        # @return [Boolean]
-        def data?
-          @rel == :data
-        end
-
-        # @return [Boolean]
-        def imm?
-          @rel == :imm && @val.is_a?(Integer)
-        end
-
-        # Defines hash function.
-        # @return [Integer]
-        def hash
-          [@rel, @val].hash
-        end
-
-        # Defines +eql?+.
-        #
-        # @param [Context::Value] other
-        # @return [Boolean]
-        def eql?(other)
-          @val == other.val && @rel == other.instance_variable_get(:@rel)
-        end
-      end
-
-      # @return [{Integer, Symbol => Context::Value}] Records reg and mem values.
-      attr_reader :values
-      # @return [Array<Integer?>] Records the known value of data.
-      attr_reader :known_data
-
-      # Instantiate a {Context} object.
-      # @param [{Integer, Symbol => Context::Value?}] values
-      #   Value to be set to +reg/mem+.
-      # @param [Array<Integer?>] known_data
-      #   Records which index of data is known.
-      #   It's used for tracking when the syscall number is known, which can be used to display argument names of the
-      #   syscall.
-      def initialize(values: {}, known_data: [])
-        @values = values
-        16.times { |i| @values[i] ||= Value.new(rel: :mem, val: i) } # make @values always has all keys
-        @values[:a] ||= Value.new
-        @values[:x] ||= Value.new
-        @known_data = known_data
-      end
-
-      # Is used for the ld/ldx instructions.
-      #
-      # @param [#downcase, :a, :x] reg
-      #   Register to be set
-      # @return [void]
-      def load(reg, rel: nil, val: nil)
-        reg = reg.downcase.to_sym
-        values[reg] = if rel == :mem
-                        values[val]
-                      else
-                        Value.new(rel:, val:)
-                      end
-      end
-
-      # Is used for the st/stx instructions.
-      #
-      # @param [Integer] idx
-      #   Index of +mem+ array.
-      # @param [#downcase, :a, :x] reg
-      #   Register.
-      #
-      # @return [void]
-      def store(idx, reg)
-        raise RangeError, "Expect 0 <= idx < 16, got #{idx}." unless idx.between?(0, 15)
-
-        values[idx] = values[reg.downcase.to_sym]
-      end
-
-      # Hints context that current value of register A equals to +val+.
-      #
-      # @param [Integer, :x] val
-      #   An immediate value or the symbol x.
-      # @return [self]
-      #   Returns the object itself.
-      def eql!(val)
-        tap do
-          # only cares when A is fetched from data
-          next unless a.data?
-          next known_data[a.val] = val if val.is_a?(Integer)
-          # A == X, we can handle these cases:
-          # * X is an immi
-          # * X is a known data
-          next unless x.data? || x.imm?
-          next known_data[a.val] = x.val if x.imm?
-
-          known_data[a.val] = known_data[x.val]
-        end
-      end
-
-      # Implements a deep dup.
-      # @return [Context]
-      def dup
-        Context.new(values: values.dup, known_data: known_data.dup)
-      end
-
-      # Register A.
-      # @return [Context::Value]
-      def a
-        values[:a]
-      end
-
-      # Register X.
-      # @return [Context::Value]
-      def x
-        values[:x]
-      end
-
-      # For conveniently get instance variable.
-      # @param [String, Symbol, Integer] key
-      # @return [Context::Value]
-      def [](key)
-        return values[key] if key.is_a?(Integer) # mem
-
-        values[key.downcase.to_sym]
-      end
-
-      # For conveniently set an instance variable.
-      # @param [#downcase, :a, :x] reg
-      #   Can be +'A', 'a', :a, 'X', 'x', :x+.
-      # @param [Value] val
-      #   Value to set.
-      # @return [void]
-      def []=(reg, val)
-        values[reg.downcase.to_sym] = val
-      end
-
-      # For +Set+ to compare two {Context} objects.
-      # @param [Context] other
-      # @return [Boolean]
-      def eql?(other)
-        values.eql?(other.values) && known_data.eql?(other.known_data)
-      end
-
-      # For +Set+ to get the hash value.
-      # @return [Integer]
-      def hash
-        [values, known_data].hash
-      end
-    end
-  end
-end