cvss-suite 4.1.4 → 5.0.0

data/lib/cvss_suite/cvss40/cvss40_calc_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'cvss40_constants_macro_vector_lookup'
 require_relative 'cvss40_constants_max_composed'
 require_relative 'cvss40_constants_max_severity'
@@ -96,6 +98,9 @@ module CvssSuite
       #      1-E:P
       #      2-E:U
 
+      # The `else` fallback intentionally mirrors the 'A' branch pending upstream
+      # clarification (see TODO below).
+      # rubocop:disable-next Lint/DuplicateBranch
       eq5 = case m('E')
             when 'A'
               '0'
@@ -152,7 +157,10 @@ module CvssSuite
       eq1_next_lower_macro = concat_and_stringify(eq1_val + 1, eq2_val, eq3_val, eq4_val, eq5_val, eq6_val)
       eq2_next_lower_macro = concat_and_stringify(eq1_val, eq2_val + 1, eq3_val, eq4_val, eq5_val, eq6_val)
 
-      # eq3 and eq6 are related
+      # eq3 and eq6 are related. Several branches share a body because distinct
+      # (eq3, eq6) states map to the same next-lower macro per the CVSS 4.0 spec;
+      # kept as separate branches to mirror the spec's case table.
+      # rubocop:disable-next Lint/DuplicateBranch
       if eq3_val == 1 && eq6_val == 1
         # 11 --> 21
         eq3eq6_next_lower_macro = concat_and_stringify(eq1_val, eq2_val, eq3_val + 1, eq4_val, eq5_val, eq6_val)
@@ -184,11 +192,7 @@ module CvssSuite
         score_eq3eq6_next_lower_macro_left = LOOKUP[eq3eq6_next_lower_macro_left]
         score_eq3eq6_next_lower_macro_right = LOOKUP[eq3eq6_next_lower_macro_right]
 
-        score_eq3eq6_next_lower_macro = if score_eq3eq6_next_lower_macro_left > score_eq3eq6_next_lower_macro_right
-                                          score_eq3eq6_next_lower_macro_left
-                                        else
-                                          score_eq3eq6_next_lower_macro_right
-                                        end
+        score_eq3eq6_next_lower_macro = [score_eq3eq6_next_lower_macro_left, score_eq3eq6_next_lower_macro_right].max
       else
         score_eq3eq6_next_lower_macro = LOOKUP[eq3eq6_next_lower_macro]
       end
@@ -353,7 +357,7 @@ module CvssSuite
     end
 
     def concat_and_stringify(first, second, third, fourth, fifth, sixth)
-      String.new.concat(first.to_s, second.to_s, third.to_s, fourth.to_s, fifth.to_s, sixth.to_s)
+      "#{first}#{second}#{third}#{fourth}#{fifth}#{sixth}"
     end
 
     def sum_or_nil(values)
@@ -393,7 +397,7 @@ module CvssSuite
     def truncate(string_to_truncate, truncate_to)
       return string_to_truncate.dup unless string_to_truncate.length > truncate_to
 
-      (string_to_truncate[0, truncate_to + 1]).to_s
+      string_to_truncate[0, truncate_to + 1].to_s
     end
   end
 end

data/lib/cvss_suite/cvss40/cvss40_constants_levels.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CvssSuite
   module Cvss40Constants
     # These constants were almost directly ported from the CVSS 4.0 calculator code found at https://github.com/FIRSTdotorg/cvss-v4-calculator/blob/ac71416d935ad2ac87cd107ff87024561ea954a7/app.js#L278C17-L278C18

data/lib/cvss_suite/cvss40/cvss40_constants_macro_vector_lookup.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CvssSuite
   module Cvss40Constants
     # These constants were almost directly ported from the CVSS 4.0 calculator code found at https://github.com/FIRSTdotorg/cvss-v4-calculator/blob/ac71416d935ad2ac87cd107ff87024561ea954a7/cvss_lookup.js#L1

data/lib/cvss_suite/cvss40/cvss40_constants_max_composed.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CvssSuite
   module Cvss40Constants
     # These constants were almost directly ported from the CVSS 4.0 calculator code found at https://github.com/FIRSTdotorg/cvss-v4-calculator/blob/ac71416d935ad2ac87cd107ff87024561ea954a7/max_composed.js#L4

data/lib/cvss_suite/cvss40/cvss40_constants_max_severity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CvssSuite
   module Cvss40Constants
     # These constants were almost directly ported from the CVSS 4.0 calculator code found at https://github.com/FIRSTdotorg/cvss-v4-calculator/blob/ac71416d935ad2ac87cd107ff87024561ea954a7/max_severity.js#L1

data/lib/cvss_suite/cvss40/cvss40_environmental.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.

data/lib/cvss_suite/cvss40/cvss40_environmental_security.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.

data/lib/cvss_suite/cvss40/cvss40_supplemental.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.

data/lib/cvss_suite/cvss40/cvss40_threat.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.

data/lib/cvss_suite/cvss_31_and_before.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -17,7 +19,7 @@ module CvssSuite
     # Creates a new CVSS vector by a +vector+, for all CVSS versions through 3.1.
     #
     # Raises an exception if it is called on Cvss31AndBefore class.
-    def initialize(vector)
+    def initialize(vector, original = vector)
       raise CvssSuite::Errors::InvalidParentClass, 'Do not instantiate this class!' if instance_of? Cvss31AndBefore
 
       super
@@ -30,7 +32,7 @@ module CvssSuite
         entered_keys = @properties.collect { |p| p[:name] }
         return false if (entered_keys - allowed_abbreviations).size.positive?
 
-        check_metrics_validity
+        metrics_valid?
       else
         false
       end
@@ -54,7 +56,7 @@ module CvssSuite
         @environmental.properties.collect(&:abbreviation)
     end
 
-    def check_metrics_validity
+    def metrics_valid?
       @base.valid? && @temporal&.valid? && @environmental&.valid?
     end
   end

data/lib/cvss_suite/cvss_40_and_later.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -17,7 +19,7 @@ module CvssSuite
     # Creates a new CVSS vector by a +vector+, for all CVSS versions from 4.0.
     #
     # Raises an exception if it is called on Cvss40AndLater class.
-    def initialize(vector)
+    def initialize(vector, original = vector)
       raise CvssSuite::Errors::InvalidParentClass, 'Do not instantiate this class!' if instance_of? Cvss40AndLater
 
       super

data/lib/cvss_suite/cvss_metric.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -53,9 +55,9 @@ module CvssSuite
           p.abbreviation == selected_property[:name] &&
             (p.position&.include?(selected_property[:position]) || p.position.nil?)
         end
-        property&.set_selected_value selected_property[:selected]
+        property&.mark_selected selected_property[:selected]
       end
-      @properties.select(&:non_selected?).each(&:set_default_value)
+      @properties.select(&:non_selected?).each(&:mark_default)
     end
   end
 end

data/lib/cvss_suite/cvss_property.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -69,22 +71,22 @@ module CvssSuite
     end
 
     ##
-    # Sets the selected value by a +value+.
+    # Marks the value with the given +abbreviation+ as selected.
 
-    def set_selected_value(selected_value)
+    def mark_selected(abbreviation)
       values.each do |value|
-        value[:selected] = selected_value.eql?(value[:abbreviation])
+        value[:selected] = abbreviation.eql?(value[:abbreviation])
       end
       @selected_value = values.detect { |value| value[:selected] }
       return unless @selected_value.nil?
 
-      @selected_value = { abbreviation: selected_value }
+      @selected_value = { abbreviation: abbreviation }
     end
 
     ##
-    # Sets the default value.
+    # Marks the default value (X / ND) as selected.
 
-    def set_default_value
+    def mark_default
       values.each do |value|
         value[:selected] = value[:abbreviation].eql?('X')
         value[:selected] ||= value[:abbreviation].eql?('ND')

data/lib/cvss_suite/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -5,21 +7,85 @@
 
 module CvssSuite
   ##
-  # This will define classed errors to be expected
+  # Included by every error this gem raises, so one rescue catches them all:
+  #
+  #   rescue CvssSuite::Error => e
+  #
+  # A module rather than a base class, so the concrete errors keep the ancestors
+  # callers already rescue: InvalidVector stays a RuntimeError, and the argument
+  # errors stay ArgumentErrors. f7e9866 moved them off a shared base class in
+  # 2018 for exactly that compatibility, and this does not take it back.
+  module Error; end
+
+  ##
+  # The concrete errors this gem raises. Each one includes Error above.
   module Errors
     ##
-    # The base error class to be inherited by more specific classes
-    class CvssError < StandardError
-      attr_accessor :message
+    # Raised for a vector this gem cannot parse, and by every score reader on a
+    # vector +valid?+ has rejected.
+    class InvalidVector < RuntimeError
+      include Error
+
+      # Caps the vector echoed back, so arbitrary input cannot push arbitrary
+      # length into an exception message and from there into a log. It caps
+      # what is echoed, not the message: escaping expands it, and 200 NUL bytes
+      # inspect to roughly 1.2 KB. Bounded either way, just not at 200.
+      #
+      # A CVSS 4.0 vector carrying every metric the specification defines, each
+      # at its longest option, is 178 characters, so a real vector is always
+      # repeated back whole.
+      MAX_REPORTED_LENGTH = 200
+
+      UNINSPECTABLE = '(an object that could not be inspected)'
+      private_constant :MAX_REPORTED_LENGTH, :UNINSPECTABLE
+
+      ##
+      # Builds the error for the +vector+ that was rejected, naming it in the
+      # message. Takes the raw input rather than a string, so a caller who
+      # passed nil or an Integer is told that, instead of being shown '""'.
+      def self.for(vector)
+        new("Vector is not valid: #{describe(vector)}")
+      end
+
+      # Strings are trimmed before inspect, not after, so the escaping is never
+      # cut mid-sequence and the closing quote survives -- and a huge input is
+      # not escaped in full only to be thrown away.
+      #
+      # CvssSuite.new accepts any object, so #inspect here runs on something the
+      # gem never validated. A broken one must not become the exception raised
+      # in place of the one it was helping to describe.
+      def self.describe(vector)
+        return trim(vector).inspect if vector.is_a?(String)
 
-      def initialize(message)
-        @message = message
-        super
+        described = vector.inspect
+        # Tested for String rather than trimmed blind: Array and Hash answer
+        # #length and #[] too, so duck-typing here would let an #inspect that
+        # returns a collection walk straight past MAX_REPORTED_LENGTH.
+        described.is_a?(String) ? trim(described) : UNINSPECTABLE
+        # SystemStackError is not a StandardError, and a self-recursive #inspect
+        # raises exactly that.
+      rescue StandardError, SystemStackError
+        UNINSPECTABLE
       end
+
+      def self.trim(text)
+        return text if text.length <= MAX_REPORTED_LENGTH
+
+        "#{text[0, MAX_REPORTED_LENGTH]}..."
+      end
+      private_class_method :describe, :trim
     end
 
-    class InvalidVector < RuntimeError; end
+    ##
+    # Raised when an abstract class is instantiated directly.
+    class InvalidParentClass < ArgumentError
+      include Error
+    end
 
-    class InvalidParentClass < ArgumentError; end
+    ##
+    # Raised for a CVSS version this gem does not implement.
+    class UnsupportedVersion < ArgumentError
+      include Error
+    end
   end
 end

data/lib/cvss_suite/helpers/cvss31_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -10,6 +12,10 @@ module CvssSuite
     ##
     # Since CVSS 3 all float values are rounded up, therefore this method is used
     # instead of the mathematically correct method round().
+    # This is the exact Roundup from CVSS v3.1 Appendix A, which works on integer
+    # arithmetic (x100000) to avoid the floating-point edge cases that plain
+    # ceil(1) hits -- the reason v3.1 replaced v3.0's rounding.
+    # https://www.first.org/cvss/v3.1/specification-document
     def self.round_up(float)
       output = (float * 100_000).round
       if (output % 10_000).zero?

data/lib/cvss_suite/helpers/cvss3_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -17,6 +19,8 @@ module CvssSuite
     ##
     # Since CVSS 3 the Privilege Required score depends on the selected value of the Scope metric.
     # This method takes a +Privilege+ +Required+ and a +Scope+ metric and returns the newly calculated score.
+    # Per the PrivilegesRequired metric table, when Scope is Changed the weights
+    # become PR:Low = 0.68 and PR:High = 0.50 (vs 0.62 / 0.27 when Unchanged).
     def self.privileges_required_score(privileges_required, scope)
       changed = scope.selected_value[:name] == 'Changed'
       privilege_score = privileges_required.score

data/lib/cvss_suite/invalid_cvss.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -9,8 +11,16 @@ module CvssSuite
   class InvalidCvss < Cvss
     # rubocop:disable Lint/MissingSuper
     ##
-    # Creates a new invalid CVSS vector.
-    def initialize; end
+    # Creates a new invalid CVSS vector, remembering the +vector+ that was
+    # rejected so the error it raises can name it. Cannot call super: that
+    # parses the vector, which is the thing that already failed.
+    #
+    # Deliberately not stored as @vector: #vector reads that through to_s, and
+    # .new accepts any object, so an object with a hostile to_s would turn a
+    # total reader into one that raises.
+    def initialize(vector = nil)
+      @rejected = vector
+    end
     # rubocop:enable Lint/MissingSuper
 
     ##
@@ -42,5 +52,19 @@ module CvssSuite
     def environmental_score
       check_validity
     end
+
+    ##
+    # Since this is an invalid CVSS vector, it always throws an exception.
+    def overall_score
+      check_validity
+    end
+
+    private
+
+    # The raw input. .new accepts anything, so nil has to read as nil and 1337
+    # as 1337 rather than both arriving in the message as an empty string.
+    def rejected_vector
+      @rejected
+    end
   end
 end

data/lib/cvss_suite/version.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
 # See the LICENSE.md file in the top-level directory.
 
 module CvssSuite
-  VERSION = '4.1.4'.freeze
+  VERSION = '5.0.0'
 end

data/lib/cvss_suite.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # CVSS-Suite, a Ruby gem to manage the CVSS vector
 #
 # This work is licensed under the terms of the MIT license.
@@ -14,6 +16,11 @@ require 'cvss_suite/invalid_cvss'
 ##
 # Module of this gem.
 module CvssSuite
+  # Exempt from the seal below, which covers only what has never shipped. Age is
+  # not the reason -- 5.0.0 privatizes three module methods that were public in
+  # 4.1.4 -- it stays because prefix-to-version lets a caller sniff a vector's
+  # version without constructing one. Sealing it means editing the three
+  # Cvss*#vector readers too: they use the qualified form, which a seal rejects.
   CVSS_VECTOR_BEGINNINGS = [
     { string: 'AV:', version: 2 },
     { string: '(AV:', version: 2 },
@@ -22,32 +29,94 @@ module CvssSuite
     { string: 'CVSS:4.0/', version: 4.0 }
   ].freeze
 
+  # The metric groups that make up each CVSS version, in vector order. Keyed by
+  # the same version values as CVSS_VECTOR_BEGINNINGS and Cvss#version, so
+  # CvssSuite.metrics(instance.version) works for every version.
+  METRIC_GROUPS = {
+    2 => [['Base', Cvss2Base], ['Temporal', Cvss2Temporal], ['Environmental', Cvss2Environmental]],
+    3.0 => [['Base', Cvss3Base], ['Temporal', Cvss3Temporal], ['Environmental', Cvss3Environmental]],
+    3.1 => [['Base', Cvss31Base], ['Temporal', Cvss31Temporal], ['Environmental', Cvss31Environmental]],
+    4.0 => [['Base', Cvss40Base], ['Threat', Cvss40Threat], ['Environmental', Cvss40Environmental],
+            ['Environmental Security Requirements', Cvss40EnvironmentalSecurity], ['Supplemental', Cvss40Supplemental]]
+  }.freeze
+
+  # Accepted version identifiers mapped to their canonical METRIC_GROUPS key, so
+  # both the canonical value (2, 3.0, ...) and the human-friendly string
+  # ('2', '2.0', '3.1', ...) resolve to the same schema.
+  VERSION_ALIASES = {
+    2 => 2, 2.0 => 2, '2' => 2, '2.0' => 2,
+    3.0 => 3.0, '3.0' => 3.0,
+    3.1 => 3.1, '3.1' => 3.1,
+    4.0 => 4.0, '4.0' => 4.0
+  }.freeze
+
+  # Both tables exist to answer .metrics, which is the supported way to reach
+  # them. Sealed before they ship in a release, while it still breaks nobody.
+  private_constant :METRIC_GROUPS, :VERSION_ALIASES
+
   ##
   # Returns a CVSS class by a +vector+.
   def self.new(vector)
-    return InvalidCvss.new unless vector.is_a? String
+    return InvalidCvss.new(vector) unless vector.is_a? String
 
-    @vector_string = if vector.frozen?
-                       vector.dup
-                     else
-                       vector
-                     end
+    # Always a copy, not only when frozen: the string is kept for the lifetime
+    # of the returned object to name it in errors, and a caller who mutates
+    # theirs afterwards would otherwise change what we report having rejected.
+    @vector_string = vector.dup
 
+    # version is a discrete value parsed from the vector and matched against exact
+    # literals, not the result of float arithmetic, so these comparisons are reliable.
+    # rubocop:disable-next Lint/FloatComparison
     case version
     when 2
-      Cvss2.new(prepare_vector(@vector_string))
+      Cvss2.new(prepare_vector(@vector_string), @vector_string)
     when 3.0
-      Cvss3.new(prepare_vector(@vector_string))
+      Cvss3.new(prepare_vector(@vector_string), @vector_string)
     when 3.1
-      Cvss31.new(prepare_vector(@vector_string))
+      Cvss31.new(prepare_vector(@vector_string), @vector_string)
     when 4.0
-      Cvss40.new(prepare_vector(@vector_string))
+      Cvss40.new(prepare_vector(@vector_string), @vector_string)
     else
-      InvalidCvss.new
+      InvalidCvss.new(@vector_string)
     end
   end
 
-  private
+  ##
+  # Returns a CVSS class by a +vector+, raising CvssSuite::Errors::InvalidVector
+  # if the vector cannot be parsed.
+  #
+  # Prefer this over .new when a bad vector is a bug rather than an expected
+  # input: .new answers with an InvalidCvss sentinel that only reports the
+  # problem once a score is asked for, so a caller who forgets +valid?+ carries a
+  # broken vector until something far from the parse blows up.
+  def self.parse(vector)
+    cvss = new(vector)
+    raise Errors::InvalidVector.for(vector) unless cvss.valid?
+
+    cvss
+  end
+
+  ##
+  # Returns the static schema of metrics and their options for a CVSS +version+
+  # (2, 3.0, 3.1 or 4.0; the equivalent strings are accepted too) without
+  # constructing a vector. Each metric lists its options with the +default+
+  # option flagged, so a caller can build input forms directly. Closes #8.
+  def self.metrics(version)
+    groups = METRIC_GROUPS[VERSION_ALIASES[version]]
+    raise Errors::UnsupportedVersion, "Unsupported CVSS version: #{version.inspect}" if groups.nil?
+
+    groups.map { |label, metric_class| { group: label, metrics: metric_schema(metric_class) } }
+  end
+
+  def self.metric_schema(metric_class)
+    metric_class.new([]).properties.map do |property|
+      options = property.values.map do |value|
+        { name: value[:name], abbreviation: value[:abbreviation], default: value.fetch(:selected, false) }
+      end
+      { name: property.name, abbreviation: property.abbreviation, options: options }
+    end
+  end
+  private_class_method :metric_schema
 
   def self.version
     CVSS_VECTOR_BEGINNINGS.each do |beginning|
@@ -60,7 +129,7 @@ module CvssSuite
 
     return prepare_cvss2_vector(vector) if version == 2
 
-    version_string = CVSS_VECTOR_BEGINNINGS.detect { |v| v[:version] == version } [:string]
+    version_string = CVSS_VECTOR_BEGINNINGS.detect { |v| v[:version] == version }[:string]
     start_of_vector = vector.index(version_string)
 
     if start_of_vector.nil?
@@ -88,4 +157,8 @@ module CvssSuite
       vector[start_of_vector..]
     end
   end
+
+  # Parsing internals. They read module state set by .new, so calling them
+  # directly was never meaningful; they were public only because .new needs them.
+  private_class_method :version, :prepare_vector, :prepare_cvss2_vector
 end