dbotquery 0.9

data/lib/d_bot_query/commands/sla_statistics_command.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module DBotQuery
+  module Commands
+    # # Service Level Agreement Stats
+    # As part of our vulnerability management program, we need to be able to understand how many
+    # open vulnerabilities there are, as well as how long they’ve been open for. For each severity, we
+    # have a “service level agreement” (SLA) that states the maximum acceptable time for a
+    # vulnerability is allowed to remain unresolved.
+    #
+    # The SLA for each severity is as follows:
+    #
+    # | Type | Days |
+    # |------|------|
+    # | Low | 60|
+    # | Medium | 30|
+    # | High | 15|
+    # | Critical | 5|
+    #
+    # For this subcommand, we should output the number of vulnerabilities that have been open
+    # longer than the SLA allows for, separated by severity.
+    #
+    # ## Inputs
+    # | Command Line Flag | Required? | Description | Example |
+    # | :--- | :--- | :--- | :--- |
+    # | -f/--file | yes | Path to JSON file exported from Dependabot | dependabot.json |
+    # | --time | no | The date/time for which the SLA is being calculated, in ISO8601 format | 2023-01-01T00:00:00Z |
+    #
+    # ### Example commands
+    # * `./your_program sla_stats -f dependabot.json`
+    #   * A count of all findings that exceed the SLA, separated by severity. The current time is used
+    # when calculating age.
+    # * `./your_program sla_stats -f dependabot.json -t 2023-01-01T00:00:00Z`
+    #   * A count of all findings that exceed the SLA, separated by severity. The time specified is
+    # used when calculating age.
+    #
+    # ### Outputs
+    # ```json
+    # {
+    #   "low": $count,
+    #   "medium": $count,
+    #   "high": $count,
+    #   "critical": $count,
+    #   "total": $count
+    # }
+    # ```
+    #
+    # Where `$count` represents the number of findings that exceed the SLA for each severity.
+    class SLAStatisticsCommand < CommandBase
+      def initialize(time: nil)
+        super()
+
+        @time = time || Time.now
+      end
+
+      def perform(input)
+        input.alerts.sla_stats @time
+      end
+    end
+  end
+end

data/lib/d_bot_query/commands/summary_command.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module DBotQuery
+  module Commands
+    # # Summary
+    #
+    # This subcommand takes a JSON export from Dependabot and returns the number of findings in
+    # the file. This command should take an optional “state” parameter so that the only vulnerabilities
+    # that are counted are the ones that match its value (e.g. open, fixed, dismissed)
+    #
+    # ## Inputs
+    #
+    # | Command Line Flag | Required | Description | Example |
+    # |:--- | :--- | :--- | :--- |
+    # | -f/--file | yes | The path to the JSON file to be processed | dependabot.json |
+    # | --state | no | The state of the vulnerability to be counted | open, fixed, dismissed |
+    # | --severity | no | The severity of the vulnerability to be counted | critical, high, medium, low |
+    #
+    # ## Example commands
+    #
+    # * `./your_program summary -f dependabot.json`
+    #   * Count of all findings in dependabot.json
+    # * `./your_program summary -f dependabot.json --state dismissed`
+    #   * Count of all dismissed findings in dependabot.json
+    # * `./your_program summary -f dependabot.json --state open --severity critical`
+    #  * Count of all open critical vulnerabilities
+    #
+    # ## Outputs
+    #
+    # ```json
+    # {“count”: $count}
+    # ```
+    #
+    # Where `$count` represents the count of findings in the JSON file. If --state or --severity are specified,
+    # the count should only include the findings whose
+    class SummaryCommand < CommandBase
+      attr_reader :state, :severity
+
+      def initialize(state: nil, severity: nil)
+        super()
+        @state = state
+        @severity = severity
+      end
+
+      def perform(input)
+        input.alerts.summary @state, @severity
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/alert.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A singular dependency alert
+    class Alert < Base
+      attribute :number, :integer
+      alias_attribute :id, :number
+      delegate :severity, to: :security_vulnerability
+
+      attribute :repository, Repository
+      attribute :dependency, Dependency
+      attribute :security_advisory, SecurityAdvisory
+      attribute :security_vulnerability, SecurityVulnerability
+
+      attribute :created_at, :datetime
+      attribute :updated_at, :datetime
+      attribute :dismissed_at, :datetime
+      attribute :fixed_at, :datetime
+      attribute :auto_dismissed_at, :datetime
+      attribute :state, :symbol
+      attribute :url, :url
+      attribute :html_url, :url
+      attribute :dismissed_by, :string
+      attribute :dismissed_comment, :string
+      attribute :dismissed_reason, :string
+
+      def days_open(as_of)
+        as_of = as_of&.to_date || Time.now.to_date
+        create_date = created_at.to_date
+        if (fix_date = fixed_at)
+          fix_date = fix_date.to_date
+          fix_date < as_of ? (fix_date - create_date).to_i : (as_of - create_date).to_i
+        else
+          (as_of - create_date).to_i
+        end
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/alert_collection.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Namespace containing models for DBotQuery when used solely
+# as an API.
+module DBotQuery
+  module Models
+    # Class representing a collection of alerts.  This is usually the
+    # result of deserializing JSON data.
+    class AlertCollection
+      include Enumerable
+
+      delegate :each, to: :@alerts
+
+      def initialize(alerts)
+        @alerts = alerts.map do |alert|
+          case alert
+          when Hash
+            Alert.new(alert)
+          when Alert
+            alert
+          else
+            raise ArgumentError, "Input of type #{alert.class} cannot be converted to Alert\n#{alert.inspect}"
+          end
+        end
+      end
+
+      def package_search(package_name)
+        where_package(package_name).map { |alert| alert.repository.full_name }.uniq
+      end
+
+      def sla_violations(as_of = nil)
+        # Here we select only those which are in violation of the SLA.
+
+        @alerts.select do |finding|
+          finding.days_open(as_of) > SLA_DEFINITION[finding.severity]
+        end
+      end
+
+      def repo_sla_stats(as_of)
+        violation_map = sla_violations(as_of)
+
+        # And finally group by the repo
+        violation_map.group_by(&:repository).to_h do |repo, findings|
+          sum_repo(repo, findings)
+        end.with_indifferent_access
+      end
+
+      def sla_stats(as_of)
+        by_severity = sla_violations(as_of).group_by(&:severity).transform_values(&:size)
+        # Because this is just a generalization of the RepoSLAStatisticsCommand, we can gather those results
+        # and combine them into a single hash
+        base = SLA_DEFINITION.to_h { |severity, _days| [severity, 0] }
+        base.merge! by_severity
+        totals = { total: base.values.sum } #: { total: Integer }
+        base.merge(totals).with_indifferent_access
+      end
+
+      def summary(state, severity)
+        findings = severity_filter(severity).state_filter(state)
+        { count: findings.count }
+      end
+
+      def sum_repo(repo, findings)
+        by_level = findings.select { |alert| alert.repository == repo }.group_by(&:severity)
+        by_level = SLA_DEFINITION.to_h { |key, _count| [key, 0] }.merge(by_level.transform_values(&:count))
+
+        [repo.to_s, { **by_level, total: by_level.values.sum }]
+      end
+
+      def select(&)
+        self.class.new(@alerts.select(&))
+      end
+
+      def severity_filter(severity)
+        severity ? select { |alert| alert.security_advisory.severity == severity.to_sym } : self
+      end
+
+      def state_filter(state)
+        state ? select { |alert| alert.state == state.to_sym } : self
+      end
+
+      def where_package(package_name)
+        select do |alert|
+          alert.dependency.package == package_name
+        end
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/base.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # Generic base class for models.  Provides common functionality for all models.
+    # This includes additional scalar type support.
+    class Base
+      # Provides additional scalar type support for casting to symbols
+      class SymbolType < ActiveModel::Type::Value
+        def cast(value)
+          return nil if value.nil?
+
+          value.to_sym
+        end
+
+        def serialize(value)
+          value&.to_s
+        end
+      end
+
+      # Provides additional scalar type support for casting to URLs (including those with templates)
+      class URLType < ActiveModel::Type::Value
+        def cast(value)
+          return nil if value.nil?
+
+          Addressable::Template.new value
+        end
+
+        def serialize(value)
+          value.pattern.to_s
+        end
+      end
+
+      # Provides additional scalar type support for casting to arrays of objects (with the target class)
+      class ObjectArray < ActiveModel::Type::Value
+        attr_reader :target_class
+
+        # Initialize with the specific class you want the array to hold
+        def initialize(of:)
+          @target_class = of
+          super()
+        end
+
+        # Casts raw input data (e.g. an array of hashes) into an array of objects
+        def cast(value)
+          return [] if value.blank?
+
+          # Ensure it's handled like an array
+          Array(value).map do |item|
+            materialize item
+          end
+        end
+
+        def serialize(value)
+          value.map(&:to_h)
+        end
+
+        private
+
+        def materialize(item)
+          case item
+          when Hash
+            target_class.new(item)
+          when target_class
+            item
+          else
+            raise "Unexpected data (not of target_type #{target_class} or a Hash)"
+          end
+        end
+      end
+
+      ActiveModel::Type.register(:symbol, SymbolType)
+      ActiveModel::Type.register(:url, URLType)
+      ActiveModel::Type.register(:array, ObjectArray)
+
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      include ActiveModel::Validations
+      include ActiveModel::Serialization
+
+      # As the models can be modified and re-serialized, we permit the changing of the data.
+      def self.mutable?
+        true
+      end
+
+      # Run the validations on the model
+      def self.assert_valid_value(value)
+        case value
+        when self
+          raise 'value is not valid' unless value.valid?
+        when Hash
+          invalid = validate_hash_attributes(value)
+          raise "#{self} has invalid hash attributes #{invalid.to_a.to_sentence}" unless invalid.empty?
+        else
+          false
+        end
+      end
+
+      # Permit the creation of a model from a hash
+      def self.cast(input_hash)
+        new input_hash
+      end
+
+      def to_h
+        attributes.to_h do |key, value|
+          type_for = self.class.type_for_attribute key
+          result = type_for.respond_to?(:serialize) ? type_for.serialize(value) : value
+          [key, result]
+        end
+      end
+
+      # Helper to define multiple attributes of a specific type
+      def self.attributes(type, *attributes)
+        suffix = type.to_s.downcase
+        attributes.each do |attribute|
+          self.attribute :"#{attribute}_#{suffix}", type
+        end
+      end
+
+      def self.validate_hash_attributes(hash)
+        attributes = attribute_names.to_set
+        keys = hash.keys.to_set(&:to_s)
+        invalid_keys = attributes - keys
+        keys <= attributes ? [] : invalid_keys.to_a
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/cvss.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # CVSS vector and score (Common Vulnerability Scoring System)
+    class CVSS < Base
+      attribute :vector_string, :string
+      attribute :score, :float
+    end
+  end
+end

data/lib/d_bot_query/models/cwe.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    class CWE < Base
+    end
+  end
+end

data/lib/d_bot_query/models/data_file.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # Data file.  Reads and parses JSON data.
+    class DataFile
+      attr_reader :alerts, :data
+
+      def initialize(data)
+        JSON::Validator.validate!(DBotQuery.schema, data)
+        @data = data
+        @alerts = AlertCollection.new(data)
+      end
+
+      def self.load(json_data)
+        from_data json_data
+      end
+
+      def self.load_file(file_path)
+        from_data file_path, loader_method: :load_file
+      end
+
+      def self.from_data(data, loader_method: :load)
+        new JSON.send(loader_method, data, freeze: true)
+      rescue JSON::ParserError => e
+        raise DBotQuery::Error, "File #{data} is not valid JSON: #{e.message}"
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/dependency.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A single dependency.  Describes the package that has or had a vulnerability that triggered the alert.
+    class Dependency < Base
+      attribute :package, Package
+      attribute :manifest_path
+      attribute :scope
+    end
+  end
+end

data/lib/d_bot_query/models/package.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A singular package (such as a npm package, a gem, or a pip for python) that is the target of a dependency
+    # relationship from a repository.  This is the code that would have a vulnerability.
+    class Package < Base
+      attribute :name, :string
+      attribute :ecosystem, :string
+
+      def ==(other)
+        case other
+        when Package
+          name == other.name && ecosystem == other.ecosystem
+        when String
+          name == other
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/reference.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A reference.  This is a link to some information such as a CVE or a security advisory's URL.
+    class Reference < Base
+      attribute :url, :url
+      alias_attribute :id, :url
+    end
+  end
+end

data/lib/d_bot_query/models/repository.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A repository, or source of a dependency, that is the code that is dependent and vulnerable due to a package
+    # on which it depends having a security vulnerability.
+    class Repository < Base
+      attribute :id, :integer
+      attribute :name, :string
+      attribute :full_name, :string
+      attribute :owner, :string
+      attribute :node_id, :string
+      attribute :private, :boolean
+      attribute :url, :url
+      attribute :description, :string
+      attribute :fork, :boolean
+      attribute :created_at, :datetime
+      attribute :updated_at, :datetime
+      attributes :url, :teams, :notifications, :deployments, :labels, :releases, :milestones, :pulls
+      attributes :url, :issues, :downloads, :compare, :merges, :contents, :issue_comment
+      attributes :url, :subscription, :trees, :languages, :stargazers, :contributors, :subscribers
+      attributes :url, :git_refs, :git_tags, :tags, :blobs, :events, :branches, :assignees, :hooks
+      attributes :url, :issue_events, :html, :forks, :collaborators, :keys, :archive, :comments
+      attributes :url, :statuses, :git_commits, :commits
+
+      def ==(other)
+        case other
+        when Repository
+          full_name == other.full_name
+        when String
+          full_name == other
+        else
+          false
+        end
+      end
+
+      def to_s
+        full_name
+      end
+    end
+  end
+end

data/lib/d_bot_query/models/security_advisory.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # The backing security advisory that triggered the alert
+    class SecurityAdvisory < Base
+      attribute :ghsa_id, :string
+      attribute :cve_id, :string
+      attribute :summary, :string
+      attribute :description, :string
+      attribute :severity, :symbol
+      attribute :published_at, :datetime
+      attribute :updated_at, :datetime
+      attribute :withdrawn_at, :datetime
+      attribute :identifiers, :array, of: VulnerabilityIdentifier
+      attribute :references, :array, of: Reference
+      attribute :vulnerabilities, :array, of: SecurityVulnerability
+      attribute :cvss, CVSS
+      attribute :cwes, :array, of: CWE
+    end
+  end
+end

data/lib/d_bot_query/models/security_vulnerability.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A security vulnerability that is discovered in a package.  This occurs in a package and has various information
+    # such as the package name, severity, published date, updated date, HTML URL, vulnerable version range,
+    # and first patched version.  It also has any information such as the references to the bulletin.
+    class SecurityVulnerability < Base
+      attribute :id, :integer
+      attribute :package, :string
+      attribute :severity, :symbol
+      attribute :published_at, :datetime
+      attribute :updated_at, :datetime
+      attribute :html_url, :url
+      attribute :vulnerable_version_range, :string
+      attribute :first_patched_version, :string
+    end
+  end
+end

data/lib/d_bot_query/models/vulnerability_identifier.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DBotQuery
+  module Models
+    # A singular identifier for a vulnerability to correlate across multiple repos.  These identifiers are stable
+    # over type and could include a CVE, GHSA, or another unique stable identifier.  One vulnerability often has
+    # many identifiers (as there are multiple authorities for tracking such).
+    class VulnerabilityIdentifier < Base
+      attribute :value, :string
+      attribute :type, :string
+      alias_attribute :id, :value
+    end
+  end
+end

data/lib/d_bot_query/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module DBotQuery
+  VERSION = '0.9'
+end

data/lib/dbotquery.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'json'
+require 'thor'
+require 'time'
+require 'date'
+require 'uri'
+require 'json-schema'
+require 'active_model'
+require 'active_support/all'
+require 'addressable/template'
+require_relative 'd_bot_query/version'
+
+# # Dependabot Data Viewer
+#
+# ## Assignment
+#
+# Dependabot is GitHub’s product for surfacing information about vulnerable dependencies.
+# GitHub maintains a database of known vulnerabilities mapped to specific versions of specific
+# dependencies, and Dependabot compares this to your package manifest (`package.json`,
+# `Gemfile.lock`, etc.).
+#
+# GitHub makes this data available in the web interface, but we want to send this data to be
+# processed elsewhere so non-engineers who don’t have access to GitHub can also see our
+# vulnerabilities. To do this, we want you to write a command line utility that takes an exported
+# JSON file from Dependabot and prints out some basic reports, also in JSON format. The
+# command line tool will not need to talk to GitHub directly. All it needs to do is take the
+# exported Dependabot JSON file as input, some configuration options, and return a JSON
+# document. Please feel free to consult GitHub’s documentation on this file.
+#
+module DBotQuery
+  # This is a generic wrapper error for those error types raised specifically by this gem.
+  class Error < StandardError; end
+
+  SCHEMA_PATH = File.join(File.dirname(__FILE__), 'schema.json')
+
+  SCHEMA = JSON.parse(File.read(SCHEMA_PATH))
+
+  autoload :CLI, 'd_bot_query/cli'
+
+  SLA_DEFINITION = {
+    low: 60,
+    medium: 30,
+    high: 15,
+    critical: 5
+  }.freeze
+
+  # Module that contains the abstract base class for all commands, as well as the implementations.  These
+  # are separated in this way to allow for easier testing and maintenance.
+  module Commands
+    autoload :CommandBase, 'd_bot_query/commands/command_base'
+    autoload :PackageSearchCommand, 'd_bot_query/commands/package_search_command'
+    autoload :SummaryCommand, 'd_bot_query/commands/summary_command'
+    autoload :RepoSLAStatisticsCommand, 'd_bot_query/commands/repo_sla_statistics_command'
+    autoload :SLAStatisticsCommand, 'd_bot_query/commands/sla_statistics_command'
+  end
+
+  # Collection of models used by the DBotQuery library providing API access to data files and their contents.
+  module Models
+    autoload :DataFile, 'd_bot_query/models/data_file'
+    autoload :Base, 'd_bot_query/models/base'
+    autoload :AlertCollection, 'd_bot_query/models/alert_collection'
+    autoload :Alert, 'd_bot_query/models/alert'
+    autoload :Dependency, 'd_bot_query/models/dependency'
+    autoload :Package, 'd_bot_query/models/package'
+    autoload :Repository, 'd_bot_query/models/repository'
+    autoload :SecurityAdvisory, 'd_bot_query/models/security_advisory'
+    autoload :SecurityVulnerability, 'd_bot_query/models/security_vulnerability'
+    autoload :VulnerabilityIdentifier, 'd_bot_query/models/vulnerability_identifier'
+    autoload :Reference, 'd_bot_query/models/reference'
+    autoload :CVSS, 'd_bot_query/models/cvss'
+    autoload :CWE, 'd_bot_query/models/cwe'
+  end
+
+  def self.schema
+    SCHEMA
+  end
+end