dobby 0.1.0 → 0.1.2

data/lib/dobby/strategy.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Dobby
+  # The Strategy provides base functionality for defining how Dobby takes in
+  # the data it needs to do its job. Each strategy should include this mixin
+  # to ensure compatibility with the rest of the library.
+  #
+  # In particular, the mixin provides a DSL for configuring strategies and
+  # standardizes some strategy behavior (such as #inspect).
+  #
+  # Much of this borrowed from Omniauth::Strategy
+  #   https://github.com/omniauth/omniauth/blob/master/lib/omniauth/strategy.rb
+  #
+  # @abstract Include as a mixin to implement a Strategy compatible with the
+  #   library
+  module Strategy
+    class Options < Hashie::Mash; end
+
+    def self.included(base)
+      Dobby.strategies << base
+
+      base.extend ClassMethods
+      base.class_eval do
+        option :setup, false
+        option :test_mode, false
+      end
+    end
+
+    # Extensible configuration for implementers.
+    module ClassMethods
+      # An inherited set of default options set at the class-level
+      # for each strategy.
+      #
+      # @return [Options]
+      def default_options
+        existing = begin
+                     superclass.default_options
+                   rescue StandardError
+                     {}
+                   end
+        @default_options ||= Dobby::Strategy::Options.new(existing)
+      end
+
+      # This allows for more declarative subclassing of strategies by allowing
+      # default options to be set using a simple configure call.
+      #
+      # @param options [Hash] If supplied, these will be the default options
+      #   (deep-merged into the superclass's default options).
+      # @yield [Options] The options Mash that allows you to set your defaults
+      #   as you'd like.
+      #
+      # @example Using a yield to configure the default options.
+      #
+      #   class MyStrategy
+      #     include Dobby::Strategy
+      #
+      #     configure do |c|
+      #       c.foo = 'bar'
+      #     end
+      #   end
+      #
+      # @example Using a hash to configure the default options.
+      #
+      #   class MyStrategy
+      #     include Dobby::Strategy
+      #     configure foo: 'bar'
+      def configure(options = nil)
+        if block_given?
+          yield default_options
+        else
+          default_options.deep_merge!(options)
+        end
+      end
+
+      # Directly declare a default option for your class. This is a useful from
+      # a documentation perspective as it provides a simple line-by-line analysis
+      # of the kinds of options your strategy provides by default.
+      #
+      # @param name [Symbol] The key of the default option in your configuration hash.
+      # @param value [Object] The value your object defaults to. Nil if not provided.
+      #
+      # @example
+      #
+      #   class MyStrategy
+      #     include Dobby::Strategy
+      #
+      #     option :foo, 'bar'
+      #   end
+      def option(name, value = nil)
+        default_options[name] = value
+      end
+
+      # Sets (and retrieves) option key names for initializer arguments to be
+      # recorded as. This takes care of 90% of the use cases for overriding
+      # the initializer in Dobby Strategies. Dobby::Options will also use
+      # this, via #cli_options, to configure any command line options.
+      def args(args = nil)
+        if args
+          @args = Array(args)
+          return
+        end
+        existing = begin
+                     superclass.args
+                   rescue StandardError
+                     []
+                   end
+        (instance_variable_defined?(:@args) && @args) || existing
+      end
+
+      # By default, all args are automatically built out as k/v CLI options. For
+      # more advanced behavior, override cli_options in the implementing class.
+      # The return of this method is passed directly to Dobby::Options#options
+      def cli_options
+        args.map { |arg| "--#{arg.to_s.tr('_', '-')} VALUE" }
+      end
+    end
+
+    attr_reader :options
+
+    # Initialize the strategy, creating an [Options] hash if the last
+    # argument is a Hash.
+    #
+    # @param args [Hash]
+    #
+    # @yield [Options]
+    def initialize(*args)
+      @options = self.class.default_options.dup
+      options.deep_merge!(args.pop) if args.last.is_a?(Hash)
+      options[:name] ||= self.class.to_s.split('::').last.downcase
+
+      self.class.args.each do |arg|
+        break if args.empty?
+
+        options[arg] = args.shift
+      end
+
+      raise ArgumentError, "Received too many arguments. #{args.inspect}" unless args.empty?
+
+      setup
+
+      yield options if block_given?
+    end
+
+    # Callback placeholder so that 'super' during initialize is unnecessary in
+    # implementing classes. This is the other 10% of the use case for overriding
+    # initialize.
+    def setup; end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    # Access to the Dobby logger, automatically prefixed with the
+    # strategy's name.
+    #
+    # @param level [Symbol] syslog level
+    # @param message [String]
+    #
+    # @example
+    #   log :fatal, 'This is a fatal error.'
+    #   log :error, 'This is an error.'
+    #   log :warn, 'This is a warning.'
+    def log(level, message)
+      Dobby.logger.send(level, "(#{self.class.name}) #{message}")
+    end
+  end
+end

data/lib/dobby/update_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Dobby
+  # A generic response format.
+  class UpdateResponse
+    attr_reader :content
+    # @param changed [Boolean]
+    # @param content [Hash]
+    def initialize(changed, content = nil)
+      @changed = changed
+      @content = content
+    end
+
+    # @return [Boolean]
+    def changed?
+      @changed == true
+    end
+  end
+end

data/lib/dobby/version.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Dobby
+  # Dobby version information.
+  module Version
+    STRING = '0.1.2'
+    MSG = '%<version>s (AptPkg %<aptpkg_version>s Apt %<apt_version>s '\
+          'libapt %<libapt_version>s) running on %<linux_version>s '\
+          '%<ruby_engine>s %<ruby_version>s %<ruby_platform>s'
+
+    def self.version(debug = false)
+      if debug
+        format(MSG, version: STRING, aptpkg_version: Debian::AptPkg::VERSION,
+                    apt_version: Debian::AptPkg::APT_VERSION,
+                    libapt_version: Debian::AptPkg::LIBAPT_PKG_VERSION,
+                    linux_version: Etc.uname[:version],
+                    ruby_engine: RUBY_ENGINE, ruby_version: RUBY_VERSION,
+                    ruby_platform: RUBY_PLATFORM)
+      else
+        STRING
+      end
+    end
+  end
+end

data/lib/dobby/vuln_source/abstract_vuln_source.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Dobby
+  module VulnSource
+    # @abstract Subclass and override {#update} and #{clean} to implement a
+    # custom Database source.
+    class AbstractVulnSource
+      include Dobby::Strategy
+
+      # Retrieve a source database (if necessary) and parse it.
+      #
+      # @return [UpdateResponse]
+      def update
+        raise NotImplementedError
+      end
+
+      # Instruct a strategy to clean up after itself, removing any files it
+      # may have created.
+      #
+      # @return [void]
+      def clean
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/dobby/vuln_source/debian.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Dobby
+  module VulnSource
+    # Vulnerability database source for Debian systems. This uses the JSON file
+    # provided by the Debian Security Tracker as its' remote source.
+    class Debian < AbstractVulnSource
+      DEFAULT_RELEASE = 'jessie'
+
+      args %i[releases cve_url_prefix dst_json_uri dst_local_file]
+
+      option :test_mode, false
+      option :releases, [DEFAULT_RELEASE]
+
+      option :dst_json_uri, 'https://security-tracker.debian.org/tracker/data/json'
+      option :cve_url_prefix, 'https://security-tracker.debian.org/tracker/'
+
+      # rubocop:disable Layout/AlignArray
+      def self.cli_options
+        [
+          ['--releases ONE,TWO',    'Limit the packages returned by a VulnSource to',
+                                    'these releases. Default varies with selected',
+                                    'VulnSource.'],
+          ['--dst-json-uri URI',    'VulnSource::Debian -- specify a URI to the',
+                                    "Debian Security Tracker's JSON file."],
+          ['--dst-local-file PATH', 'VulnSource::Debian -- If provided, read from',
+                                    'the specified file instead of requesting the',
+                                    'DST json file from a remote.'],
+          ['--cve-url-prefix URI',  'URI prefix used for building CVE links.']
+        ]
+      end
+      # rubocop:enable Layout/AlignArray
+
+      # Map of DST-provided urgencies to a common severity format
+      URGENCY_MAP = Hash.new(Severity::Unknown).merge(
+        'not-yet-assigned' => Severity::Unknown,
+        'end-of-life'      => Severity::Negligible,
+        'unimportant'      => Severity::Negligible,
+        'low'              => Severity::Low,
+        'low*'             => Severity::Low,
+        'low**'            => Severity::Low,
+        'medium'           => Severity::Medium,
+        'medium*'          => Severity::Medium,
+        'medium**'         => Severity::Medium,
+        'high'             => Severity::High,
+        'high*'            => Severity::High,
+        'high**'           => Severity::Critical
+      )
+
+      # Unable to retrieve or load a dobby database
+      class NoDataError < Error; end
+
+      # Received a non-200 response from the Security Tracker
+      class BadResponseError < Error
+        attr_accessor :curl
+
+        def initialize(curl)
+          url = curl.url
+          url_path_only = url =~ /\A([^?]*)\?/ ? Regexp.last_match(1) : url
+          super("Bad response code (#{curl.response_code.to_i} for #{url_path_only})")
+          @curl = curl
+        end
+
+        # @return [Hash{resp_code=>Integer, url=>String, resp=>String}]
+        def context
+          { resp_code: @curl.response_code, url: @curl.url, resp: @curl.body_str }
+        end
+      end
+      ###
+
+      # Initialize callback.
+      def setup
+        @last_hash = nil
+      end
+
+      # Provide an UpdateResponse sourced from the Debian Security Tracker's
+      # JSON. If the SHA256 of the returned JSON matches the last attempt,
+      # UpdateResponse.changed? will be false. Otherwise, UpdateResponse.content
+      # will be a Hash{package_name=>Array<Defect>}
+      #
+      # @return [UpdateResponse]
+      def update
+        data = fetch_from_remote(options.dst_json_uri)
+
+        hash = Digest::SHA256.hexdigest(data)
+        return UpdateResponse.new(false) if hash == @last_hash
+
+        debian_vulns = Oj.load(data)
+
+        vuln_entries = Hash.new { |h, k| h[k] = [] }
+        debian_vulns.each do |package, vulns|
+          vulns.each do |identifier, vuln|
+            # If a permanent ID has not been assigned to the vuln, skip it
+            next unless identifier.start_with?('CVE-', 'OVE-')
+
+            severity = Severity::Unknown
+            fixed_versions = []
+
+            vuln['releases'].each do |release, info|
+              next unless options.releases.include?(release)
+
+              version = choose_version(info['fixed_version'], info['status'])
+              next unless version
+
+              # For a given Defect, it may have differing severities across
+              # different Debian releases. Set the severity of the Defect to
+              # the highest value.
+              new_severity = URGENCY_MAP[info['urgency']]
+              severity = new_severity if severity < new_severity
+
+              fixed_versions << Package.new(
+                name: package,
+                version: version,
+                release: release
+              )
+            end
+
+            vuln_entries[package] << Defect.new(
+              identifier: identifier,
+              description: vuln['description'],
+              severity: severity,
+              fixed_in: fixed_versions,
+              link: options.cve_url_prefix + identifier
+            )
+          end
+        end
+        @last_hash = hash
+        UpdateResponse.new(true, vuln_entries)
+      end
+
+      # Given a 'fixed in' version and a defect status, determine what version
+      # represents the status for comparison.
+      #
+      # @param fixed [String] version that the vuln src says a defect is fixed in
+      # @param status [String] the current status of the defect
+      #
+      # @return [String] version string
+      def choose_version(fixed, status)
+        return unless status
+        return Package::MIN_VERSION if fixed == '0'
+        return Package::MAX_VERSION if status == 'open'
+        return fixed if status == 'resolved'
+
+        nil
+      end
+
+      # Retrieve the DST json file
+      #
+      # @param url [String]
+      #
+      # @return [String]
+      #
+      # @raise [BadResponseError] if url returns something other than 200
+      # @raise [NoDataError] if url returns no data
+      def fetch_from_remote(url)
+        return File.read(options.dst_local_file) if options.dst_local_file
+
+        curl = Curl::Easy.perform(url)
+        raise BadResponseError, curl unless curl.response_code.to_i == 200
+        raise NoDataError unless curl.body_str
+
+        curl.body_str
+      end
+    end
+  end
+end

data/lib/dobby/vuln_source/ubuntu.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module Dobby
+  module VulnSource
+    # Vulnerability source for Ubuntu systems. This class uses the Ubuntu CVE
+    # Tracker as its' remote source by checking out the bazaar repository.
+    #
+    # @note This requires bazaar to be installed at /usr/bin/bzar unless
+    #   configured with a different path via the bzr option.
+    class Ubuntu < AbstractVulnSource
+      DEFAULT_RELEASE = 'xenial'
+      args %i[releases cve_url_prefix bzr_bin bzr_repo tracker_repo]
+
+      option :test_mode, false
+      option :releases, [DEFAULT_RELEASE]
+
+      option :bzr_bin, '/usr/bin/bzr'
+      option :cve_url_prefix, 'http://people.ubuntu.com/~ubuntu-security/cve/'
+      option :tracker_repo, 'https://launchpad.net/ubuntu-cve-tracker'
+
+      # rubocop:disable Layout/AlignArray
+      def self.cli_options
+        [
+          ['--releases ONE,TWO',   'Limit the packages returned by a VulnSource to',
+                                   'these releases. Default vaires with selected',
+                                   'VulnSource.'],
+          ['--bzr-bin PATH',       'VulnSource::Ubuntu - Path to the "bzr" binary.'],
+          # ['--bzr-repo PATH',      'Path to the Ubuntu Security bazaar repo on the',
+          #                          'local system.'],
+          ['--tracker-repo URI',   'VulnSource::Ubuntu - Path to the security tracker',
+                                   'bazaar repository remote.'],
+          ['--cve-url-prefix URL', 'URI prefix used for building CVE links.']
+        ]
+      end
+
+      # rubocop:enable Layout/AlignArray
+      # Map of Canonical-provided urgencies to a common severity format
+      URGENCY_MAP = Hash.new(Severity::Unknown).merge(
+        'untriaged'  => Severity::Unknown,
+        'negligible' => Severity::Negligible,
+        'low'        => Severity::Low,
+        'medium'     => Severity::Medium,
+        'high'       => Severity::High,
+        'critical'   => Severity::Critical
+      )
+
+      # An array of defect states that we are interested in. Skips e.g. ignored/DNE
+      RELEVANT_STATUSES = %w[needed active deferred not-affected released].freeze
+
+      # Line prefixes which indicate the end of a defect description
+      DESC_STOP_FIELDS = %w[
+        Ubuntu-Description:
+        Priority:
+        Discovered-By:
+        Notes:
+        Bugs:
+        Assigned-to:
+      ].freeze
+
+      # A hash with DeepMerge
+      class VulnerabilityHash < Hash
+        include Hashie::Extensions::DeepMerge
+      end
+
+      def setup
+        @last_revno = nil
+      end
+
+      # Provide an UpdateReponse sourced from Canoncial's Ubuntu CVE Tracker
+      # repository. This is a bazaar repository, and thus this strategy depends
+      # on the bzr binary being available. The strategy will avoid descending
+      # the repository if the repo's revno matches a previous revno.
+      #
+      # @return [UpdateResponse]
+      def update
+        branch_or_pull
+        revno = bzr_revno
+        return UpdateResponse.new(false) if revno == @last_revno
+
+        vuln_entries = VulnerabilityHash.new
+        modified_entries.each do |file|
+          data = parse_ubuntu_cve_file(File.readlines(file))
+          vuln_entries.deep_merge!(data)
+        end
+        @last_revno = revno
+        UpdateResponse.new(true, vuln_entries)
+      end
+
+      # Delete the bzr repository
+      def clean
+        Dir.rmdir(options.local_repo_path)
+      end
+
+      private
+
+      # Determine whether the repo needs to be branched (because it doesn't
+      # exist) or pulled (because it already exists), and then do that.
+      #
+      # @return [Boolean]
+      def branch_or_pull
+        if Dir.exist?(options.local_repo_path)
+          pull(options.local_repo_path)
+        else
+          branch(options.local_repo_path)
+        end
+      end
+
+      def branch(path)
+        FileUtils.mkdir_p path
+        Dir.chdir(path) do
+          return system(options.bzr_bin.to_s, 'branch', '--use-existing-dir',
+                        options.tracker_repo.to_s, '.')
+        end
+      end
+
+      def pull(path)
+        Dir.chdir(path) do
+          return system(options.bzr_bin.to_s, 'pull', '--overwrite')
+        end
+      end
+
+      # Retrieve bazaar revision number
+      #
+      # @return [String]
+      def bzr_revno
+        stdout, = Open3.capture2(options.bzr_bin, 'revno', options.local_repo_path)
+        stdout.strip
+      end
+
+      # Returns a list of all interesting files in the bazaar repository.
+      #
+      # @note The library cannot currently support differential updates :(
+      #
+      # @return [Array<String>]
+      def modified_entries
+        search = File.join(options.local_repo_path, '{active,retired}', '**', 'CVE*')
+        Dir.glob(search)
+      end
+
+      def parse_ubuntu_cve_file(file_lines)
+        entries = Hash.new { |h, k| h[k] = {} }
+        fixed_versions = Hash.new { |h, k| h[k] = [] }
+        severity = Severity::Unknown
+
+        identifier = description = link = nil
+        more = false
+
+        file_lines.each do |line|
+          line.chomp!
+          next if line.start_with?('#') || line.empty?
+
+          if line.start_with?('Candidate:')
+            identifier = line.split[1]
+            link = options.cve_url_prefix + identifier
+            next
+          elsif line.start_with?('Priority:')
+            severity = URGENCY_MAP[line.split[1]]
+            next
+          elsif line.start_with?('Description:')
+            more = true
+            check = line.split(' ', 2)
+            description = check[1] if check.count > 1
+            next
+          elsif more
+            if line.start_with?(*DESC_STOP_FIELDS)
+              description.strip!
+              more = false
+            else
+              description = description + ' ' + line.strip
+            end
+            next
+          end
+
+          # Separate release, package status and version information out of a
+          # defect detail line.
+          #
+          # Example line -
+          #   xenial_linux: released (4.4.0-81.104)
+
+          # rubocop:disable Metrics/LineLength
+          next unless /(?<release>.*)_(?<package>.*): (?<status>[^\s]*)( \(+(?<note>[^()]*)\)+)?/ =~ line
+          # rubocop:enable Metrics/LineLength
+
+          next unless RELEVANT_STATUSES.include?(status)
+
+          release = release.split('/')[0]
+          next unless options.releases.include?(release)
+
+          version = choose_version(note, status)
+          fixed_versions[package] << Package.new(
+            name: package,
+            version: version,
+            release: release
+          )
+        end
+
+        fixed_versions.each do |package, versions|
+          entries[package] = Defect.new(
+            identifier: identifier,
+            description: description,
+            severity: severity,
+            fixed_in: versions,
+            link: link
+          )
+        end
+        entries
+      end
+
+      # Given a 'fixed in' version and a defect status, determine what version
+      # represents the status for comparison.
+      #
+      # If status is released, this simply returns the fixed argument.
+      # If status is not-affected, {Package::MIN_VERSION} is returned.
+      # If status is some other value, {Package::MAX_VERSION} is returned and the
+      #   defect is considered to apply to all versions.
+      #
+      # @param fixed [String] version that the vuln src says a defect is fixed in
+      # @param status [String] the current status of the defect
+      #
+      # @return [String] version string
+      def choose_version(fixed, status)
+        return fixed if status == 'released'
+        return Package::MIN_VERSION if status == 'not-affected'
+
+        Package::MAX_VERSION
+      end
+    end
+  end
+end