dobby 0.1.0 → 0.1.2

data/lib/dobby/package_source/abstract_package_source.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dobby
+  module PackageSource
+    # @abstract Subclass and override {#parse} to implement a custom Package
+    #   source.
+    class AbstractPackageSource
+      include Dobby::Strategy
+
+      # All logic for creating an Array<Package>]
+      # @return [Array<Package>]
+      def parse
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/dobby/package_source/dpkg_status_file.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Dobby
+  module PackageSource
+    # Defines a strategy for creating a {Package} array from /var/lib/dpkg/status
+    # or a similarly formatted file.
+    class DpkgStatusFile < AbstractPackageSource
+      args %i[file_path dist release]
+
+      option :file_path, '/var/lib/dpkg/status'
+      option :dist, 'Debian'
+      option :release, Dpkg.code_name
+
+      # A Dpkg section has unexpected formatting
+      class DpkgFormatError < Error; end
+
+      # rubocop:disable Layout/AlignArray
+      def self.cli_options
+        [
+          ['--release NAME', 'Release code name for package definitions.',
+                             'Defaults to the code name of the current system.'],
+          ['--dist DIST', 'The full name of the distribution for package definitions.',
+                          'Defaults to "Debian".']
+        ]
+      end
+      # rubocop:enable Layout/AlignArray
+
+      # @return [Array<Package>]
+      def parse
+        packages = []
+        File.read(options.file_path).split("\n\n").each do |section|
+          begin
+            packages << package_from_section(section)
+          rescue Package::FieldRequiredError => e
+            # If the Version field is missing, this is probably a virtual
+            # or meta-package (e.g. little-table-dev) - Skip it. Name and
+            # release should never be missing, so reraise the error in those
+            # cases.
+            next if e.field == 'version'
+
+            raise
+          end
+        end
+        packages
+      end
+
+      private
+
+      # @param section [String]
+      # @return [Package]
+      # @raise [FormatError]
+      def package_from_section(section)
+        pkg = {}
+        field = nil
+
+        section.each_line do |line|
+          line.chomp!
+          if /^\s/ =~ line
+            raise FormatError, "Unexpected whitespace at start of line: '#{line}'" unless field
+
+            pkg[field] += "\n" + line
+          elsif /(^\S+):\s*(.*)/ =~ line
+            field = Regexp.last_match(1).capitalize
+            if pkg.key?(field)
+              raise FormatError, "Unexpected duplicate field '#{field}' in line '#{line}'"
+            end
+
+            value = Regexp.last_match(2).strip
+            value = value.split[0] if field == 'Source'
+            pkg[field] = value
+          end
+        end
+        Package.new(
+          name: pkg['Package'],
+          version: pkg['Version'],
+          dist: options.dist,
+          release: options.release,
+          arch: pkg['Architecture'],
+          source: pkg['Source'],
+          multiarch: pkg['Multi-Arch']
+        )
+      end
+    end
+  end
+end

data/lib/dobby/runner.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Dobby
+  class Runner
+    attr_reader :errors, :aborting
+    alias aborting? aborting
+
+    def initialize(options)
+      @options = options
+      @errors = []
+      @aborting = false
+    end
+
+    def run(paths)
+      target_files = resolve_paths(paths)
+      return list_files(target_files) if @options[:list_target_files]
+
+      load_vuln_source(@options[:vuln_source])
+      load_package_source(@options[:package_source])
+      load_scanner
+      inspect_files(target_files)
+    end
+
+    private
+
+    def inspect_files(files)
+      inspected = []
+
+      formatter_set.started(files)
+
+      each_inspected_file(files) { |file| inspected << file }
+    ensure
+      formatter_set.finished(inspected.freeze)
+      formatter_set.close_output_files
+    end
+
+    def resolve_paths(target_files)
+      target_files.map { |f| File.expand_path(f) }.freeze
+    end
+
+    def each_inspected_file(files)
+      files.reduce(true) do |passed, file|
+        break false if aborting?
+
+        results = process_file(file)
+
+        yield file
+
+        if results.any?
+          break false if @options[:fail_fast]
+
+          next false
+        end
+
+        passed
+      end
+    end
+
+    def formatter_set
+      @formatter_set ||= begin
+        set = Formatter::FormatterSet.new(@options)
+        pairs = @options[:formatters] || [['simple', @options[:output_path]]]
+        pairs.each do |formatter_key, output_path|
+          set.add_formatter(formatter_key, output_path)
+        end
+        set
+      end
+    end
+
+    def load_package_source(selected)
+      selected ||= 'dpkg'
+      @package_source = package_source_loader(selected)
+    end
+
+    def load_vuln_source(selected)
+      selected ||= 'debian'
+      @vuln_source = vuln_source_loader(selected)
+    end
+
+    def load_scanner
+      vuln_source = @vuln_source.new(@options)
+      @database = Dobby::Database.new(vuln_source)
+      @scanner = Scanner.new(nil, @database)
+    end
+
+    def process_file(file = nil)
+      formatter_set.file_started(file)
+      source = @package_source.new(@options.merge(file_path: file))
+      packages = source.parse
+      results = run_scanner(packages)
+      formatter_set.file_finished(file, results)
+      results
+    end
+
+    def run_scanner(packages)
+      @scanner.packages = packages
+      @scanner.scan(defect_filter: Scanner::DEFECT_FILTER_FIXED)
+    end
+
+    def fuzzy_source_name(key, sources)
+      sources.keys.select { |k| k.start_with?(key) }
+    end
+
+    def builtin_package_source_class(specified)
+      matching = fuzzy_source_name(specified, Builtins::PACKAGE_SOURCES)
+
+      raise %(No package source for "#{specified}") if matching.empty?
+      raise %(Ambiguous package source for "#{specified}") if matching.size > 1
+
+      Builtins::PACKAGE_SOURCES[matching.first]
+    end
+
+    def builtin_vuln_source_class(specified)
+      matching = fuzzy_source_name(specified, Builtins::VULN_SOURCES)
+
+      raise %(No vulnerability source for "#{specified}") if matching.empty?
+      raise %(Ambiguous vulnerability source for "#{specified}") if matching.size > 1
+
+      Builtins::VULN_SOURCES[matching.first]
+    end
+
+    def vuln_source_loader(specifier)
+      case specifier
+      when Class
+        specifier
+      when /\A[A-Z]/
+        custom_class(specifier)
+      else
+        builtin_vuln_source_class(specifier)
+      end
+    end
+
+    def package_source_loader(specifier)
+      case specifier
+      when Class
+        specifier
+      when /\A[A-Z]/
+        custom_class(specifier)
+      else
+        builtin_package_source_class(specifier)
+      end
+    end
+
+    def custom_class(name)
+      constant_names = name.split('::')
+      constant_names.shift if constant_names.first.empty?
+      constant_names.reduce(Object) do |namespace, constant_name|
+        namespace.const_get(constant_name, false)
+      end
+    end
+  end
+end

data/lib/dobby/scanner.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Dobby
+  # Compares a {Database} and {Array<Package>} to discover what defects
+  #   affect a system.
+  class Scanner
+    attr_reader :database, :packages, :results
+
+    FLAG_FILTER_ALL         = :all
+    FLAG_FILTER_ALLOWED     = :allowed
+    FLAG_FILTER_WHITELISTED = :whitelisted
+    FLAG_FILTER_DEFAULT     = :default
+
+    DEFECT_FILTER_DEFAULT   = :default
+    DEFECT_FILTER_FIXED     = :only_fixed
+
+    VERSION_FILTER_TARGET   = :target
+    VERSION_FILTER_DEFAULT  = :default
+
+    # @param packages [Array<Package>]
+    # @param database [Database]
+    def initialize(packages, database)
+      @packages = packages
+      @database = database
+
+      @results = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Whenever the package set the scanner is configured with change,
+    # the stored results will be wiped.
+    def packages=(arr)
+      @results.clear
+      @packages = arr
+    end
+
+    # Determine which packages are affected by which defects.
+    #
+    # @option [Symbol] :defect_filter {DEFECT_FILTER_DEFAULT}
+    #   - {DEFECT_FILTER_DEFAULT}
+    #       Apply no special filters to defects in the database
+    #   - {DEFECT_FILTER_FIXED}
+    #       Only include defects that have a fix available
+    # @option [Symbol] :flag_filter {FLAG_FILTER_DEFAULT}
+    #   - {FLAG_FILTER_ALL}
+    #       Apply no filter at all to the results
+    #   - {FLAG_FILTER_DEFAULT}
+    #       Ignore results marked with any flag
+    #   - {FLAG_FILTER_ALLOWED}
+    #       Include only results flagged allowed
+    #   - {FLAG_FILTER_WHITELISTED}
+    #       Include only results flagged whitelisted
+    # @option [Symbol] :version_filter {VERSION_FILTER_DEFAULT}
+    #   - {VERSION_FILTER_DEFAULT}
+    #       For a given package and defect, ensure that the release of the defect's
+    #       fix versions match the package and that the version of the package
+    #       is less than the fix version
+    #   - {VERSION_FILTER_TARGET}
+    #       See {#scan_by_target} for more information on how this complex filter behaves.
+    #
+    # Order of filter processing, from first to last:
+    #   1. Flag
+    #   2. Defect
+    #   3. Version
+    def scan(defect_filter: DEFECT_FILTER_DEFAULT,
+             flag_filter: FLAG_FILTER_DEFAULT,
+             version_filter: VERSION_FILTER_DEFAULT)
+      @results.clear
+      packages.each do |package|
+        scan_results = scan_one(package: package,
+                                defect_filter: defect_filter,
+                                flag_filter: flag_filter,
+                                version_filter: version_filter)
+        @results.merge! scan_results
+      end
+      results
+    end
+
+    # For a given package, determine which packages affect it, if any.
+    def scan_one(package:,
+                 defect_filter: DEFECT_FILTER_DEFAULT,
+                 flag_filter: FLAG_FILTER_DEFAULT,
+                 version_filter: VERSION_FILTER_DEFAULT)
+      res = Hash.new { |h, k| h[k] = [] }
+      database.defects_for(package).each do |defect|
+        next if defect.filtered?(filter: defect_filter, flag_filter: flag_filter)
+
+        defect.fixed_in.each do |v|
+          next if package.filtered?(v, version_filter)
+
+          res[package] << defect
+        end
+      end
+      res
+    end
+
+    # Determine which defects are resolved by upgrading to a target version.
+    #
+    # Given:
+    #   - A Package at version 1 and a target version of 3
+    #   - A Defect, D1, with a fix version of 2
+    #   - A Defect, D2, with a fix version of 3
+    #   - A Defect, D3, with a fix version of 4
+    #
+    # Returns D1 and D2, but not D3.
+    #
+    # This is a use-specific wrapper around {#scan}
+    #
+    # @note Packages that do not have a target version set are skipped.
+    def scan_by_target
+      scan(defect_filter: DEFECT_FILTER_FIXED,
+           flag_filter: FLAG_FILTER_DEFAULT,
+           version_filter: VERSION_FILTER_TARGET)
+    end
+
+    # For a specific package, determine which defects are resolved by upgrading
+    # to its' target version.
+    #
+    # This is a use-specific wrapper around {scan_one}
+    #
+    # @param [Package]
+    def scan_one_by_target(package)
+      scan_one(package: package,
+               defect_filter: DEFECT_FILTER_FIXED,
+               flag_filter: FLAG_FILTER_DEFAULT,
+               version_filter: VERSION_FILTER_TARGET)
+    end
+  end
+end

data/lib/dobby/severity.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Dobby
+  # Standardized definitions for severity categories
+  module Severity
+    # Implements a custom <=> method so that severities can be sorted as
+    # we see fit. In particular, these objects sort based on their index
+    # in the {SEVERITIES} array.
+    class Severity
+      attr_reader :value
+      def initialize(value)
+        @value = value
+      end
+
+      def to_s
+        @value
+      end
+
+      def ==(other)
+        value == other.value
+      end
+
+      def <=>(other)
+        return 0 if other == self
+        return 1 if SEVERITIES.index(self) < SEVERITIES.index(other)
+
+        -1
+      end
+
+      def <(other)
+        SEVERITIES.index(self) < SEVERITIES.index(other)
+      end
+    end
+
+    # A defect which has not yet been assigned a priority or we do not have
+    # a translation for.
+    Unknown = Severity.new('Unknown')
+
+    # Technically a security issue, but has no real damage, extremely strict
+    # requirements, or other constraints that nullify impact.
+    Negligible = Severity.new('Negligible')
+
+    # Security problem, but difficult to exploit, requires user assistance
+    # or does very little damage.
+    Low = Severity.new('Low')
+
+    # "Real" security problem that is generally exploitable.
+    Medium = Severity.new('Medium')
+
+    # Real "problem", that is generally exploitable in a default configuration.
+    High = Severity.new('High')
+
+    # The world is on fire, send help!
+    Critical = Severity.new('Critical')
+
+    # All severities in an ordered list
+    SEVERITIES = [
+      Unknown,
+      Negligible,
+      Low,
+      Medium,
+      High,
+      Critical
+    ].freeze
+  end
+end