seccomp-tools 1.6.2 → 1.7.1

data/lib/seccomp-tools/audit/report.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/finding'
+require 'seccomp-tools/util'
+
+module SeccompTools
+  class Audit
+    # The findings for one filter, rendered either as a human report or a JSON-ready hash.
+    class Report
+      # Severity => {Util.colorize} theme for the +[SEVERITY]+ tag.
+      SEVERITY_THEME = { high: :error, medium: :warn, low: :info }.freeze
+
+      # Widest a rendered line may get, so a finding reads without wrapping on a standard terminal.
+      WIDTH = 120
+
+      # @param [String?] source Label for the audited filter.
+      # @param [Array<String>] arches The architectures covered.
+      # @param [Array<Finding>] findings
+      # @param [Boolean] truncated Whether the symbolic walk was cut short.
+      def initialize(source:, arches:, findings:, truncated:)
+        @source = source
+        @arches = arches
+        @findings = findings.sort_by(&:rank)
+        @truncated = truncated
+      end
+
+      # @return [Array<Finding>]
+      attr_reader :findings
+      # @return [Array<String>] The architectures covered.
+      attr_reader :arches
+
+      # The human report.
+      # @return [String]
+      def to_s
+        out = +''
+        out << "Seccomp audit of #{@source}\n" if @source
+        out << "Architectures: #{@arches.join(', ')}\n" unless @arches.empty?
+        # A truncated walk can only hide weaknesses, so it qualifies the whole report rather than
+        # being a finding of its own.
+        out << "WARNING: analysis truncated (filter too large); results may be incomplete.\n" if @truncated
+        return out << "\nNo weaknesses found.\n" if @findings.empty?
+
+        @findings.each { |f| out << render(f) }
+        out
+      end
+
+      # @return [Hash] JSON-ready shape for one filter.
+      def to_h
+        { source: @source, arches: @arches, truncated: @truncated, findings: @findings.map(&:to_h) }
+      end
+
+      private
+
+      def render(finding)
+        tag = Util.colorize("[#{finding.severity.to_s.upcase}]", t: SEVERITY_THEME[finding.severity])
+        arch = finding.arch ? " (#{Util.colorize(finding.arch, t: :arch)})" : ''
+        names = finding.syscalls
+        out = "\n#{tag} #{highlight(finding.title, names)}#{arch}\n"
+        out << paragraph(finding.detail, names, '    ', '    ')
+        out << paragraph(finding.condition, names, '    when: ', '          ') if finding.condition
+        out << paragraph(finding.remediation, names, '    fix:  ', '          ') if finding.remediation
+        out
+      end
+
+      # +text+ wrapped to {WIDTH} columns, its first line prefixed with +first+ and the rest with
+      # +hang+ so they read as one block. Wrapping is measured before coloring, so the invisible
+      # escape codes never count towards the width.
+      # @return [String]
+      def paragraph(text, names, first, hang)
+        lines = []
+        indent = first
+        line = nil
+        text.to_s.split(/\s+/).each do |word|
+          if line.nil?
+            line = word
+          elsif indent.size + line.size + 1 + word.size <= WIDTH
+            line = "#{line} #{word}"
+          else
+            lines << (indent + line)
+            indent = hang
+            line = word
+          end
+        end
+        lines << (indent + line) if line
+        lines.map { |l| "#{highlight(l, names)}\n" }.join
+      end
+
+      # Paints the syscall names a finding is about wherever they appear in +text+, in the same color
+      # disasm gives them. Whole words only, so +read+ leaves +process_vm_readv+ alone.
+      # @return [String]
+      def highlight(text, names)
+        Array(names).uniq.reduce(text) do |painted, name|
+          painted.gsub(/\b#{Regexp.escape(name)}\b/) { Util.colorize(name, t: :syscall) }
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/audit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/audit/checks'
+require 'seccomp-tools/audit/policy'
+require 'seccomp-tools/audit/report'
+require 'seccomp-tools/explain/analysis'
+require 'seccomp-tools/symbolic/executor'
+
+module SeccompTools
+  # Assesses a seccomp filter for weaknesses / escape routes and reports them as a {Audit::Report}.
+  #
+  # It runs the generic {Symbolic::Executor} over the filter (the same walk {Explain} uses), splits
+  # the leaves per architecture with {Explain::Analysis}, and runs each {Checks} rule against the
+  # per-arch {Policy}. Every supported architecture is assessed; architecture-specific quirks (e.g.
+  # amd64's x32 ABI) are registered per arch in {Checks}, never special-cased inline.
+  #
+  # @example
+  #   insts = SeccompTools::Disasm.to_bpf(raw, :amd64).map(&:inst)
+  #   puts SeccompTools::Audit.new(insts, arch: :amd64, source: 'a.out').audit
+  class Audit
+    # @param [Array<Instruction::Base>] instructions
+    #   The filter, as +SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)+.
+    # @param [Symbol] arch
+    #   The architecture the filter is written for, used when it does not itself branch on +arch+.
+    # @param [String?] source
+    #   A label for the filter (e.g. a filename) shown in the report.
+    def initialize(instructions, arch:, source: nil)
+      @instructions = instructions
+      @arch = arch
+      @source = source
+    end
+
+    # Walks the filter, runs every check, and returns the {Report}.
+    # @return [Report]
+    def audit
+      leaves, truncated = Symbolic::Executor.new(@instructions).run
+      analysis = Explain::Analysis.new(leaves)
+      policies = analysis.sections(@arch).map { |section| Policy.new(analysis, section) }
+
+      findings = Checks::FILTER.flat_map { |check| check.call(analysis) }
+      policies.each do |policy|
+        Checks.section_checks(policy.arch_sym).each { |check| findings.concat(check.call(policy)) }
+      end
+
+      Report.new(source: @source, arches: policies.map(&:arch_name), findings:, truncated:)
+    end
+  end
+end

data/lib/seccomp-tools/bpf.rb

@@ -7,7 +7,10 @@ require 'seccomp-tools/const'
 require 'seccomp-tools/instruction/instruction'
 
 module SeccompTools
-  # Define the +struct sock_filter+, while more powerful.
+  # One BPF instruction, i.e. a +struct sock_filter+.
+  #
+  # Beyond the four fields of the C struct, a {BPF} also carries the architecture it belongs to and
+  # its line number, which together allow it to be disassembled into readable assembly.
   class BPF
     # @return [Integer] Line number.
     attr_reader :line
@@ -21,12 +24,13 @@ module SeccompTools
     attr_reader :k
     # @return [Symbol] Architecture.
     attr_reader :arch
-    # @return [Set<Context>] Possible contexts before this instruction.
-    attr_accessor :contexts
+    # @return [Set<SeccompTools::Symbolic::State>] Possible states before this instruction.
+    attr_accessor :states
 
     # Instantiate a {BPF} object.
-    # @param [String] raw
-    #   One +struct sock_filter+ in bytes, should be 8 bytes long.
+    # @param [String, {Symbol => Integer}] raw
+    #   One +struct sock_filter+, either as 8 raw bytes or as a hash of the +:code+, +:jt+, +:jf+
+    #   and +:k+ fields.
     # @param [Symbol] arch
     #   Architecture, for showing constant names in decompile.
     # @param [Integer] line
@@ -47,7 +51,7 @@ module SeccompTools
       end
       @arch = arch
       @line = line
-      @contexts = Set.new
+      @states = Set.new
       @disasm_setting = {
         code: true,
         arg_infer: true
@@ -56,8 +60,11 @@ module SeccompTools
 
     # Pretty display the disassemble result.
     # @param [{Symbol => Boolean}] options
-    #   Set display settings.
+    #   Display settings, merged into the current ones. Supports +:code+, whether to show the raw
+    #   +code+, +jt+, +jf+ and +k+ fields, and +:arg_infer+, whether to annotate the line with the
+    #   inferred syscall argument.
     # @return [String]
+    #   One line of disassembly, without a trailing newline.
     def disasm(**options)
       @disasm_setting.merge!(options)
       if show_code?
@@ -69,12 +76,14 @@ module SeccompTools
       end
     end
 
-    # Whether needs to dump code, jt, jf, k.
+    # Whether the raw +code+, +jt+, +jf+, +k+ fields need to be dumped.
+    # @return [Boolean]
     def show_code?
       @disasm_setting[:code]
     end
 
-    # Whether needs to infer the syscall argument names.
+    # Whether the syscall argument names need to be inferred.
+    # @return [Boolean]
     def show_arg_infer?
       @disasm_setting[:arg_infer]
     end
@@ -88,8 +97,8 @@ module SeccompTools
     end
 
     # Command according to +code+.
-    # @return [Symbol]
-    #   See {Const::BPF::COMMAND} for list of commands.
+    # @return [Symbol?]
+    #   See {Const::BPF::COMMAND} for the list of commands, +nil+ if +code+ is invalid.
     def command
       Const::BPF::COMMAND.invert[code & 7]
     end
@@ -101,15 +110,16 @@ module SeccompTools
       inst.decompile
     end
 
-    # @param [Context] context
-    #   Current context.
+    # Yields every branch that may be taken after executing this instruction.
+    # @param [SeccompTools::Symbolic::State] state
+    #   Current state.
     # @yieldparam [Integer] pc
     #   Program counter after this instruction.
-    # @yieldparam [Context] ctx
-    #   Context after this instruction.
+    # @yieldparam [SeccompTools::Symbolic::State] st
+    #   State after this instruction.
     # @return [void]
-    def branch(context, &)
-      inst.branch(context).each(&)
+    def branch(state, &)
+      inst.branch(state).each(&)
     end
 
     # Corresponding instruction object.

data/lib/seccomp-tools/cli/asm.rb

@@ -12,6 +12,9 @@ module SeccompTools
       # Usage of this command.
       USAGE = "asm - #{SUMMARY}\n\nUsage: seccomp-tools asm IN_FILE [options]".freeze
 
+      # Instantiate an {Asm} object, defaulting the output format to +:inspect+.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:format] = :inspect
@@ -19,10 +22,11 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.') do |o|
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.') do |o|
             option[:ofile] = o
           end
 
@@ -36,7 +40,7 @@ module SeccompTools
         end
       end
 
-      # Handle options.
+      # Assembles the input file and writes the result in the requested format.
       # @return [void]
       def handle
         return unless super

data/lib/seccomp-tools/cli/audit.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require 'seccomp-tools/audit'
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/cli/filter_input'
+require 'seccomp-tools/disasm/disasm'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'audit' command.
+    class Audit < Base
+      include FilterInput
+
+      # Summary of this command.
+      SUMMARY = 'Assess a seccomp filter for weaknesses and escape routes.'
+      # Usage of this command.
+      USAGE = "audit - #{SUMMARY}\n\nUsage: seccomp-tools audit [options] [BPF_FILE|EXEC]".freeze
+
+      # Instantiate an {Audit} object.
+      #
+      # Takes the same arguments as {Base#initialize}.
+      def initialize(*)
+        super
+        option[:format] = :human
+      end
+
+      # Define option parser.
+      # @return [OptionParser]
+      #   The parser of this command's options.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = usage
+          option_filter_source(opt, 'audit')
+          option_arch(opt, 'With an executable or --pid the architecture is auto-detected instead.')
+
+          opt.on('-f', '--format FORMAT', %i[human json], 'Output format, one of <human|json>.',
+                 'Default: human') do |f|
+            option[:format] = f
+          end
+        end
+      end
+
+      # Reads the filter(s) from a BPF file, an executable, or an existing process, then reports the
+      # weaknesses of each.
+      # @return [void]
+      def handle
+        return unless super
+
+        filters = collect_filters
+        return if filters.empty?
+
+        option[:format] == :json ? emit_json(filters) : emit_human(filters)
+      end
+
+      private
+
+      # Prints each filter's report, warning first when several filters stack.
+      def emit_human(filters)
+        if filters.size > 1
+          Logger.warn("#{filters.size} filters are installed; they stack, so a syscall must pass every one " \
+                      '(most restrictive wins). Each is audited separately below.')
+        end
+        each_report(filters) { |report| output { report.to_s } }
+      end
+
+      # Prints one JSON document describing every stacked filter.
+      def emit_json(filters)
+        reports = []
+        each_report(filters) { |report| reports << report.to_h }
+        output { "#{JSON.pretty_generate(stacked_filters: filters.size, reports:)}\n" }
+      end
+
+      # Yields the {Audit::Report} of each filter, labelling stacked filters like +explain+ does.
+      def each_report(filters)
+        filters.each_with_index do |(raw, arch, source), idx|
+          label = filters.size > 1 ? "#{source} (filter ##{idx})" : source
+          insts = SeccompTools::Disasm.to_bpf(raw, arch).map(&:inst)
+          yield SeccompTools::Audit.new(insts, arch:, source: label).audit
+        end
+      end
+    end
+  end
+end

data/lib/seccomp-tools/cli/base.rb

@@ -2,13 +2,19 @@
 
 require 'optparse'
 
+require 'seccomp-tools/logger'
 require 'seccomp-tools/util'
 
 module SeccompTools
   module CLI
     # Base class for handlers.
+    #
+    # Each subcommand is a subclass that defines a +USAGE+ constant and a +parser+, and overrides
+    # {#handle} to do its work.
     class Base
-      # @return [{Symbol => Object}] Options.
+      # @return [{Symbol => Object}]
+      #   Options parsed from the command line. Common keys are +:arch+, +:ifile+, +:ofile+,
+      #   +:format+, +:limit+, +:pid+ and +:verbose+, depending on the subcommand.
       attr_reader :option
       # @return [Array<String>] Arguments array.
       attr_reader :argv
@@ -23,14 +29,29 @@ module SeccompTools
 
       private
 
-      # Handle show help message.
+      # Parses the common options, and shows the help message when asked to.
       # @return [Boolean]
-      #   For decestors to check whether need to continue.
+      #   For descendants to check whether they need to continue. +false+ when the help message
+      #   was shown and there is nothing left to do.
       def handle
-        return CLI.show(parser.help) if argv.empty? || %w[-h --help].any? { |h| argv.include?(h) }
+        return CLI.show(parser.help) if argv.empty? || %w[-h --help].intersect?(argv)
 
         parser.parse!(argv)
-        option[:arch] ||= Util.system_arch
+
+        # Fill in the architecture from the host when --arch was not given. A command that offers
+        # --arch needs a concrete architecture to name syscalls; if the host CPU is one seccomp-tools
+        # does not recognize, auto-detection cannot supply one, so fail with a clear message instead
+        # of letting :unknown reach a syscall-table lookup and raise deep down.
+        return true unless option[:arch].nil?
+
+        arch = Util.system_arch
+        if arch == :unknown && @arch_option_offered
+          Logger.error('Could not detect the host architecture; specify one with ' \
+                       "--arch <#{Util.supported_archs.join('|')}>.")
+          return false
+        end
+
+        option[:arch] = arch
         true
       end
 
@@ -43,6 +64,9 @@ module SeccompTools
       end
 
       # Write data to stdout or file(s).
+      #
+      # When +option[:ofile]+ is set, each call writes to a new file named after it with an
+      # incrementing serial number, see {#file_of}. Colors are disabled while writing to a file.
       # @yieldreturn [String]
       #   The data to be written.
       # @return [void]
@@ -65,7 +89,7 @@ module SeccompTools
       # @param [String] file
       #   Filename.
       # @param [Integer] serial
-      #   serial number, starts from zero.
+      #   Serial number, starts from zero.
       # @return [String]
       #   Result filename.
       # @example
@@ -89,11 +113,30 @@ module SeccompTools
         self.class.const_get(:USAGE)
       end
 
-      def option_arch(opt)
+      # Warns about positional arguments left over in {#argv} after the command has taken what it
+      # needs, e.g. an exec given together with +-c+, or anything after +--pid+. The command still
+      # proceeds.
+      # @return [void]
+      def warn_ignored_arguments
+        return if argv.empty?
+
+        Logger.warn("ignoring unused argument#{'s' if argv.size > 1}: #{argv.join(' ')}")
+      end
+
+      # Registers the common +--arch+ option on +opt+.
+      #
+      # @param [OptionParser] opt
+      #   The parser to add the option to.
+      # @param [Array<String>] extra_desc
+      #   Extra description lines appended after the default ones, for command-specific guidance.
+      # @return [void]
+      def option_arch(opt, *extra_desc)
+        @arch_option_offered = true
         supported = Util.supported_archs
         opt.on('-a', '--arch ARCH', supported, 'Specify architecture.',
                "Supported architectures are <#{supported.join('|')}>.",
-               "Default: #{Util.system_arch}") do |a|
+               'Default: auto-detected from the host machine.',
+               'Set it when the filter targets an architecture other than the host.', *extra_desc) do |a|
           option[:arch] = a
         end
       end

data/lib/seccomp-tools/cli/cli.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require 'seccomp-tools/cli/asm'
+require 'seccomp-tools/cli/audit'
+require 'seccomp-tools/cli/completion'
 require 'seccomp-tools/cli/disasm'
 require 'seccomp-tools/cli/dump'
 require 'seccomp-tools/cli/emu'
+require 'seccomp-tools/cli/explain'
 require 'seccomp-tools/version'
 
 module SeccompTools
@@ -12,9 +15,12 @@ module SeccompTools
     # Handled commands
     COMMANDS = {
       'asm' => SeccompTools::CLI::Asm,
+      'audit' => SeccompTools::CLI::Audit,
+      'completion' => SeccompTools::CLI::Completion,
       'disasm' => SeccompTools::CLI::Disasm,
       'dump' => SeccompTools::CLI::Dump,
-      'emu' => SeccompTools::CLI::Emu
+      'emu' => SeccompTools::CLI::Emu,
+      'explain' => SeccompTools::CLI::Explain
     }.freeze
 
     # Main usage message.
@@ -57,9 +63,9 @@ EOS
       COMMANDS[cmd].new(argv).handle
     end
 
-    # Just write message to stdout.
+    # Writes a message to stdout, followed by a newline.
     # @param [String] msg
-    #   The message.
+    #   The message to be written.
     # @return [void]
     def show(msg)
       puts msg

data/lib/seccomp-tools/cli/completion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'seccomp-tools/cli/base'
+require 'seccomp-tools/logger'
+
+module SeccompTools
+  module CLI
+    # Handle 'completion' command.
+    class Completion < Base
+      # Summary of this command.
+      SUMMARY = 'Print a shell completion script.'
+      # Usage of this command.
+      USAGE = "completion - #{SUMMARY}\n\nUsage: seccomp-tools completion <bash|zsh|fish>".freeze
+
+      # Maps a shell name to the completion script that ships with the gem.
+      SCRIPTS = { 'bash' => 'seccomp-tools.bash', 'zsh' => '_seccomp-tools', 'fish' => 'seccomp-tools.fish' }.freeze
+
+      # Define option parser.
+      # @return [OptionParser]
+      #   The parser of this command's options.
+      def parser
+        @parser ||= OptionParser.new do |opt|
+          opt.banner = usage
+        end
+      end
+
+      # Writes the completion script for the requested shell to stdout.
+      # @return [void]
+      def handle
+        return unless super
+
+        shell = argv.shift
+        file = SCRIPTS[shell]
+        return CLI.show(parser.help) if file.nil?
+
+        output { File.read(File.join(__dir__, '..', '..', '..', 'completions', file)) }
+      end
+    end
+  end
+end

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

@@ -12,6 +12,9 @@ module SeccompTools
       # Usage of this command.
       USAGE = "disasm - #{SUMMARY}\n\nUsage: seccomp-tools disasm BPF_FILE [options]".freeze
 
+      # Instantiate a {Disasm} object, showing raw BPF and inferred arguments by default.
+      #
+      # Takes the same arguments as {Base#initialize}.
       def initialize(*)
         super
         option[:bpf] = true
@@ -20,10 +23,11 @@ module SeccompTools
 
       # Define option parser.
       # @return [OptionParser]
+      #   The parser of this command's options.
       def parser
         @parser ||= OptionParser.new do |opt|
           opt.banner = usage
-          opt.on('-o', '--output FILE', 'Output result into FILE instead of stdout.') do |o|
+          opt.on('-o', '--output FILE', 'Write output to FILE instead of stdout.') do |o|
             option[:ofile] = o
           end
           option_arch(opt)
@@ -35,9 +39,9 @@ module SeccompTools
                  'Default: true') do |f|
                    option[:arg_infer] = f
                  end
-          opt.on('--asm-able', 'Output with this flag is a valid input of "seccomp-tools asm".',
-                 'By default, "seccomp-tools disasm" is in a human-readable format that easy for analysis.',
-                 'Passing this flag can have the output be simplified to a valid input for "seccomp-tools asm".',
+          opt.on('--asm-able', 'Make the output valid input for "seccomp-tools asm".',
+                 'By default, "seccomp-tools disasm" outputs a human-readable format meant for analysis.',
+                 'With this flag the output is simplified so it can be fed back to "seccomp-tools asm".',
                  'This flag implies "--no-bpf --no-arg-infer".',
                  'Default: false') do |_f|
                    option[:bpf] = false
@@ -46,7 +50,7 @@ module SeccompTools
         end
       end
 
-      # Handle options.
+      # Disassembles the input file and writes the result.
       # @return [void]
       def handle
         return unless super