cvss-to-3.1 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cab20d1b1295245d4bde938ea5baf30025279c7c7e9df65f2b779a863027d03
+  data.tar.gz: 22a198a5eb2c4db6449d0500c3e737c57abcdf632503e00bbd85cbe4c4a07a77
+SHA512:
+  metadata.gz: 70b39e5c20802ea48af34880c5021a07092bb3df3fcb391f84de59849ecde766fb0d8aed44312f077f5c16bc94a80bd537015d0f347b58474b1d955f9febadee
+  data.tar.gz: 46e513232e7c5eda64e7de8dd60eab879987c112d763719a8d2d3ed41568fbd06bb80edd925074c6de56f35e09c6eb88aa0f7f281f52e09e0720bd7b159d4759

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-09-04
+
+First public release
+
+## [0.0.1] - 2026-04-14
+
+Internal version

data/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, runZero, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,111 @@
+# cvss-to-3.1
+
+A small Ruby gem that normalizes CVSS vectors from mixed versions into a CVSS 3.1 object.
+
+It accepts CVSS 2.0, 3.0, 3.1, and 4.0 input and returns a scored `CvssSuite::Cvss31` object so downstream systems can compare and store values in one format.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cvss-to-3.1'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install cvss-to-3.1
+```
+
+## Usage
+
+```ruby
+require 'cvss_to_31'
+
+result = CvssTo31.convert('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H')
+
+result.version.to_s # => "3.1"
+result.vector       # => "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
+result.base_score   # => 10.0
+```
+
+The API accepts either a vector string or a `CvssSuite` object:
+
+```ruby
+v2 = CvssSuite.new('AV:N/AC:L/Au:N/C:C/I:C/A:C')
+CvssTo31.convert(v2)
+```
+
+## Supported Conversion Logic
+
+### CVSS 3.1 -> 3.1
+
+Passthrough. A valid 3.1 vector/object is returned unchanged.
+
+### CVSS 3.0 -> 3.1
+
+Lossless version re-stamp (`CVSS:3.0` -> `CVSS:3.1`) with metrics preserved.
+
+### CVSS 2.0 -> 3.1
+
+CVSS 2.0 lacks some fields required by 3.1, so this conversion is approximate.
+
+| CVSS 2.0 metric | CVSS 2.0 value | CVSS 3.1 metric | CVSS 3.1 value | Rationale |
+|---|---|---|---|---|
+| AV | N / A / L | AV | N / A / L | Direct equivalents |
+| AC | L / M | AC | L | Low/Medium collapse to Low (worst-case: maximizes score) |
+| AC | H | AC | H | High complexity stays High |
+| Au | N | PR | N | No authentication required |
+| Au | S / M | PR | H | Any authentication requirement maps to High privileges |
+| C / I / A | N | C / I / A | N | No impact |
+| C / I / A | P | C / I / A | L | Partial impact maps to Low |
+| C / I / A | C | C / I / A | H | Complete impact maps to High |
+| (none) | - | UI | N | No CVSS 2.0 equivalent |
+| (none) | - | S | U | No CVSS 2.0 equivalent |
+
+### CVSS 4.0 -> 3.1
+
+CVSS 4.0 includes metrics not present in 3.1 and vice versa. The gem applies the following normalization:
+
+| CVSS 4.0 metric | CVSS 4.0 value | CVSS 3.1 metric | CVSS 3.1 value | Rationale |
+|---|---|---|---|---|
+| AV | N / A / L / P | AV | N / A / L / P | Direct mapping |
+| AC | L / H | AC | L / H | Direct mapping |
+| PR | N / L / H | PR | N / L / H | Direct mapping |
+| UI | N | UI | N | Direct mapping |
+| UI | A / P | UI | R | Active/Passive collapse to Required |
+| VC / VI / VA | N / L / H | C / I / A | N / L / H | Victim impacts map to CIA |
+| SC / SI / SA | any L or H present | S | C | Any subsequent impact implies Scope Changed |
+| SC / SI / SA | all N | S | U | No subsequent impact implies Scope Unchanged |
+
+## Errors
+
+`CvssTo31.convert` raises:
+
+- `CvssTo31::Error` for invalid vectors
+- `CvssTo31::UnsupportedVersionError` for unsupported CVSS versions
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+Build the gem:
+
+```bash
+gem build cvss-to-3.1.gemspec
+```
+
+## License
+
+Licensed under the BSD 2-Clause License. See LICENSE.

data/lib/cvss_to_31/converter.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'cvss_suite'
+require_relative 'error'
+
+module CvssTo31
+  # Converts any supported CVSS vector to a CVSS 3.1 {CvssSuite} object.
+  #
+  # Supported source versions:
+  # - 2.0  (approximate — see notes below)
+  # - 3.0  (lossless re-stamp of the version component)
+  # - 3.1  (passthrough)
+  # - 4.0  (down-conversion — see notes below)
+  #
+  # == CVSS 2.0 → 3.1 mapping notes
+  #
+  # CVSS v2 lacks several metrics that v3.1 requires, so this conversion is
+  # necessarily approximate.  The mapping applied is:
+  #
+  # | v2 metric | v2 value | v3.1 metric | v3.1 value | Rationale |
+  # |-----------|----------|-------------|------------|-----------|
+  # | AV        | N/A/L    | AV          | N/A/L      | Direct equivalents |
+  # | AC        | L/M      | AC          | L          | Low/Medium collapse to Low (worst-case: maximises score) |
+  # | AC        | H        | AC          | H          | High complexity stays High |
+  # | Au        | N        | PR          | N          | No authentication required |
+  # | Au        | S/M      | PR          | H          | Any authentication ≈ high privilege required |
+  # | C/I/A     | N        | C/I/A       | N          | No impact |
+  # | C/I/A     | P        | C/I/A       | L          | Partial impact ≈ Low |
+  # | C/I/A     | C        | C/I/A       | H          | Complete impact ≈ High |
+  # | (none)    | —        | UI          | N          | No v2 equivalent; defaults to None |
+  # | (none)    | —        | S           | U          | No v2 equivalent; defaults to Unchanged |
+  #
+  # == CVSS 4.0 → 3.1 mapping notes
+  #
+  # The down-conversion maps Base metrics directly where names match, collapses
+  # the v4.0 User Interaction values (Active/Passive → Required, None → None),
+  # and infers Scope from the three Subsequent Impact metrics (SC/SI/SA: any
+  # High or Low value → Changed; all None → Unchanged).  Victim/Consumer Impact
+  # metrics (VC/VI/VA) are used for the v3.1 C/I/A values.
+  class Converter
+
+    # CVSS 4.0 vectors can be the longest valid form because they include base,
+    # threat, environmental, and supplemental fields. Even a full environmental
+    # 4.0 vector remains well under 512 characters, so this should be fine to
+    # prevent DoS effects by offering stupid long vectors.
+    MAX_INPUT_LENGTH = 512
+
+    # No shell escapes or SQL escapes or any of that nonsense.
+    ALLOWED_CVSS_CHARACTER_PATTERN = /\A[A-Za-z0-9.:\/]+\z/
+
+    class << self
+      # Convert a CVSS vector to CVSS 3.1.
+      #
+      # @param input [String, CvssSuite::Cvss] A CVSS vector string or an
+      #   existing {CvssSuite} object.
+      # @return [CvssSuite::Cvss31] A valid CVSS 3.1 object.
+      # @raise [CvssTo31::Error] If the vector is invalid.
+      # @raise [CvssTo31::UnsupportedVersionError] If the CVSS version is not
+      #   one of 2.0, 3.0, 3.1, or 4.0.
+      def convert(input)
+        vector = validate_input(input)
+        cvss = input.is_a?(String) ? CvssSuite.new(vector) : input
+
+        unless cvss.respond_to?(:valid?) && cvss.valid?
+          raise Error, "Invalid CVSS vector: #{vector}"
+        end
+
+        case cvss.version.to_s
+        when "3.1" then cvss
+        when "3.0" then from_3_0(cvss)
+        when "4.0" then from_4_0(cvss)
+        when "2"   then from_2_0(cvss)
+        else
+          raise UnsupportedVersionError, "Unsupported CVSS version: #{cvss.version}"
+        end
+      end
+
+      private
+
+      def validate_input(input)
+        case input
+        when String
+          validate_vector_string(input)
+        when CvssSuite::Cvss
+          validate_vector_string(input.vector)
+        else
+          raise Error, "Invalid input type: expected String or CvssSuite::Cvss, got #{input.class}"
+        end
+      end
+
+      def validate_vector_string(vector)
+        unless vector.is_a?(String)
+          raise Error, 'Invalid CVSS input: expected a String value'
+        end
+
+        if vector.length > MAX_INPUT_LENGTH
+          raise Error, "Invalid CVSS input: value too long (#{vector.length} > #{MAX_INPUT_LENGTH})"
+        end
+
+        unless vector.match?(ALLOWED_CVSS_CHARACTER_PATTERN)
+          raise Error, 'Invalid CVSS input: only letters, numbers, periods, colons, and slashes are allowed'
+        end
+
+        vector
+      end
+
+      def from_3_0(cvss)
+        CvssSuite.new(cvss.vector.sub("CVSS:3.0", "CVSS:3.1"))
+      end
+
+      def from_4_0(cvss)
+        m     = parse_vector(cvss.vector)
+        ui    = case m["UI"]; when "A", "P" then "R"; else "N"; end
+        scope = [m["SC"], m["SI"], m["SA"]].any? { |v| v =~ /[HL]/ } ? "C" : "U"
+
+        CvssSuite.new(
+          "CVSS:3.1/AV:#{m["AV"]}/AC:#{m["AC"]}/PR:#{m["PR"]}" \
+          "/UI:#{ui}/S:#{scope}/C:#{m["VC"]}/I:#{m["VI"]}/A:#{m["VA"]}"
+        )
+      end
+
+      def from_2_0(cvss)
+        m = parse_vector(cvss.vector)
+
+        CvssSuite.new(
+          "CVSS:3.1/AV:#{m["AV"]}/AC:#{map_v2_ac(m["AC"])}/PR:#{map_v2_au(m["Au"])}" \
+          "/UI:N/S:U/C:#{map_v2_impact(m["C"])}/I:#{map_v2_impact(m["I"])}/A:#{map_v2_impact(m["A"])}"
+        )
+      end
+
+      # Split a CVSS vector string into a metric hash.
+      # Works for all versions; the leading "CVSS:X.Y" token is stored under
+      # the key "CVSS" and is harmlessly ignored during metric lookups.
+      def parse_vector(vector)
+        vector.split('/').each_with_object({}) do |part, h|
+          key, val = part.split(':', 2)
+          h[key] = val
+        end
+      end
+
+      # CVSS v2 AC: L/M → L (worst-case: collapse medium to low so the score is maximised); H → H
+      def map_v2_ac(ac)
+        case ac
+        when "L", "M" then "L"
+        when "H"      then "H"
+        else raise Error, "Unknown CVSS v2 AC value: #{ac}"
+        end
+      end
+
+      # CVSS v2 Au → v3.1 PR: N → N; S or M → H (any auth requirement = high privilege)
+      def map_v2_au(au)
+        case au
+        when "S", "M" then "H"
+        when "N"       then "N"
+        else raise Error, "Unknown CVSS v2 Au value: #{au}"
+        end
+      end
+
+      # CVSS v2 C/I/A impact: N → N, P → L, C → H
+      def map_v2_impact(val)
+        case val
+        when "N" then "N"
+        when "P" then "L"
+        when "C" then "H"
+        else raise Error, "Unknown CVSS v2 impact value: #{val}"
+        end
+      end
+    end
+  end
+end

data/lib/cvss_to_31/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CvssTo31
+  # Raised when a CVSS vector string is malformed or fails cvss-suite validation.
+  class Error < StandardError; end
+
+  # Raised when the CVSS version of the input cannot be converted to 3.1
+  # (e.g. an unrecognised future version).
+  class UnsupportedVersionError < Error; end
+end

data/lib/cvss_to_31/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CvssTo31
+  VERSION = "1.0.0"
+end

data/lib/cvss_to_31.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'cvss_to_31/version'
+require_relative 'cvss_to_31/error'
+require_relative 'cvss_to_31/converter'
+
+# Top-level namespace for the cvss-to-3.1 gem.
+#
+# Converts any supported CVSS vector (v2.0, v3.0, v3.1, or v4.0) to a
+# normalised CVSS 3.1 {CvssSuite} object.
+#
+# @example Convert a CVSS 4.0 vector
+#   result = CvssTo31.convert("CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:H")
+#   result.base_score   #=> 10.0
+#   result.vector       #=> "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H"
+#
+# @example Convert a CVSS 2.0 vector
+#   result = CvssTo31.convert("AV:N/AC:L/Au:N/C:C/I:C/A:C")
+#   result.base_score   #=> 9.8
+#   result.vector       #=> "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
+module CvssTo31
+  # Convert a CVSS vector string or {CvssSuite} object to CVSS 3.1.
+  #
+  # @param input [String, CvssSuite::Cvss] CVSS vector or existing object.
+  # @return [CvssSuite::Cvss31] A valid, scored CVSS 3.1 object.
+  # @raise [CvssTo31::Error] On invalid input.
+  # @raise [CvssTo31::UnsupportedVersionError] On an unrecognised CVSS version.
+  def self.convert(input)
+    Converter.convert(input)
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: cvss-to-3.1
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tod Beardsley
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cvss-suite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: |
+  A small, focused gem that normalises CVSS vectors from any version
+  (2.0, 3.0, 3.1, or 4.0) to a CVSS 3.1 CvssSuite object.  Useful
+  whenever a tool must compare or store scores across a live CVE feed
+  that mixes CVSS versions.
+email:
+- todb@runzero.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/cvss_to_31.rb
+- lib/cvss_to_31/converter.rb
+- lib/cvss_to_31/error.rb
+- lib/cvss_to_31/version.rb
+homepage: https://github.com/runZeroInc/cvss-to-3.1
+licenses:
+- BSD-2-Clause
+metadata:
+  source_code_uri: https://github.com/runZeroInc/cvss-to-3.1
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Convert any CVSS vector (v2, v3.0, v4.0) to a normalised CVSS 3.1 score
+test_files: []