cvss-suite 4.1.4 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3efb3fc75b7c4cc0428b409767c3abc83c2efa00b0dce57597c933fd2e233f3
-  data.tar.gz: ec150b5056b70c831088d49028c69e846dff6194e4043dde7fe5d31235c18613
+  metadata.gz: 38b3fbdc1354c4d34347faa2978c7049ed17e29ee0ed918c0ef0005a10bd9122
+  data.tar.gz: 6891802700da8fb10e65a1cb9ed46c6715cad8358961c7b903d3d68087d6f1e1
 SHA512:
-  metadata.gz: 49532a6b6954c2b12734990897134beec7c8ccbadb2420111dc7c32a4858ed7a03a691226e879144f75fbdd1dc6f4e67351907d3e2f11606db8235d829394fbe
-  data.tar.gz: 6ffd130cc5107b9aeec32eb37601ef50c8c55001fe20553e46c2b82f353e72b15f4ce089f2c75959d5f9e51df63db5ea3f8795410261549cedf4f3c5fd41b798
+  metadata.gz: 9efc55c3235da09d62c3e31853075961e48b8ce1fe25e2eef32da0f3858a618571e1dc3f66e5589825001c7a1b6e79db7e80276fb1575138efe71ded4360d689
+  data.tar.gz: 9ee51323adbef6afc920dd8c44327b8e91772721ebbc3e81aacc723c7634b7868782e9dac0ca098550be1094657f9adb14b881f7d9e8d7bf1d64c9d1c5f2b60f

data/{CHANGES.md → CHANGELOG.md}

@@ -1,10 +1,37 @@
-> [!WARNING]
-> Starting with version 5.0.0, changes are no longer documented in this file. Please see the [Releases page](../../releases) for the changelog going forward.
-
 # Change Log
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+From 5.0.0 onwards, entries are generated at release time from the pull requests
+merged since the previous release, and mirror the notes on the
+[Releases page](https://github.com/0llirocks/cvss-suite/releases).
+
+## 5.0.0 (2026-09-06)
+
+## What's Changed
+* Require Ruby >= 3.3 and modernize toolchain (v5 baseline) by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/62
+* Bump actions/checkout from 5 to 7 by @dependabot[bot] in https://github.com/0llirocks/cvss-suite/pull/63
+* Update simplecov requirement from ~> 0.22 to ~> 1.0 by @dependabot[bot] in https://github.com/0llirocks/cvss-suite/pull/65
+* RuboCop 1.88 cleanup + frozen string literals (v5) by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/64
+* deps: remove the bigdecimal upper bound by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/67
+* feat: expose base_score on CVSS 4.0 for NVD/GHSA comparison by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/69
+* build: package only runtime files in the gem by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/70
+* docs: cite the CVSS spec formula behind each scoring calculation by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/71
+* Update simplecov requirement from ~> 0.22 to ~> 1.0 by @dependabot[bot] in https://github.com/0llirocks/cvss-suite/pull/66
+* feat: add CvssSuite.metrics for static metric introspection by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/68
+* feat!: add CvssSuite.parse and make the parsing internals private by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/72
+* docs: rewrite the README, and fix the scoring bug that writing it exposed by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/73
+* ci: automate the changelog and release with release-please by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/75
+* refactor: keep the metric lookup tables private by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/77
+* refactor!: give every error one rescuable ancestor by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/78
+* feat: name the rejected vector when one is not valid by @SeanLF in https://github.com/0llirocks/cvss-suite/pull/79
+
+## New Contributors
+* @SeanLF made their first contribution in https://github.com/0llirocks/cvss-suite/pull/62
+* @dependabot[bot] made their first contribution in https://github.com/0llirocks/cvss-suite/pull/63
+
+**Full Changelog**: https://github.com/0llirocks/cvss-suite/compare/v4.1.4...v5.0.0
+
 ## [4.1.4] - 2026-07-05
 
 ### Fixes

data/LICENSE.md

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 
 Copyright (c) 2016-2022 Siemens AG\
-Copyright (c) 2022-2024 0llirocks
+Copyright (c) 2022-2026 0llirocks
 
 Author: 0llirocks <https://github.com/0llirocks>
 
@@ -15,6 +15,7 @@ Contributors:
 - Adam Hess <https://github.com/HParker>
 - Jason Garber <https://github.com/jgarber>
 - Sachin Sandhu <https://github.com/sachin-sandhu>
+- Sean Floyd <https://github.com/SeanLF>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.md

@@ -1,138 +1,119 @@
 # CvssSuite for Ruby
 
-[![Gem Version](http://img.shields.io/gem/v/cvss-suite.svg)](https://rubygems.org/gems/cvss-suite)
-[![Ruby Version](https://img.shields.io/badge/Ruby-2.6-brightgreen.svg)](https://rubygems.org/gems/cvss-suite)
-[![Cvss Support](https://img.shields.io/badge/CVSS-v2-brightgreen.svg)](https://www.first.org/cvss/v2/guide)
-[![Cvss Support](https://img.shields.io/badge/CVSS-v3.0-brightgreen.svg)](https://www.first.org/cvss/v3.0/user-guide)
-[![Cvss Support](https://img.shields.io/badge/CVSS-v3.1-brightgreen.svg)](https://www.first.org/cvss/v3.1/user-guide)
-[![Cvss Support](https://img.shields.io/badge/CVSS-v4.0-brightgreen.svg)](https://www.first.org/cvss/v4.0/user-guide)
-[![RSpec](https://github.com/0llirocks/cvss-suite/workflows/RSpec/badge.svg)](https://github.com/0llirocks/cvss-suite/actions)
+Score a CVSS vector string, and read back every metric in it.
 
-This Ruby gem helps you to process the vector of the [**Common Vulnerability Scoring System**](https://www.first.org/cvss/specification-document).
-Besides calculating the Base, Temporal and Environmental Score, you are able to extract the selected option.
+CvssSuite turns a vector string into scores and severity, and lets you ask which option each metric
+selected. It handles four CVSS versions behind one interface, so code that ingests advisories from
+more than one era does not need a branch per specification version.
+
+The parsed vector stays addressable, which is what you need to render a vector back to a user, drive
+an input form, or explain a score rather than just report it.
 
 > [!IMPORTANT]
 > This project could need some new maintainer(s). I am having less time and motivation to support this gem. Support for v4 was only possible with the help of the community and I am sure I will not implement any v4.x or v5.x support by myself. Since this gem is used in some projects I will not step down without any kind of support. If you are interested in CVSS and ruby, feel free to work on upcoming issues and let me ([@Ollirocks](https://github.com/0llirocks)) know if you are willing to become a maintainer. As of today there are only a very few issues each year but each new version of CVSS results in quite a lot of work. I am fine with staying the owner of this project until someone is willing to take over completely. I will not vanish from GitHub once and or all :smile: The same applies to the ruby gems account, I am willing to push new versions to rubygems.org until someone trustworthy is found to take over.
 
-## Installation
-
-Add this line to your application's Gemfile:
+## Example
 
 ```ruby
-gem 'cvss-suite'
-```
+require 'cvss_suite'
 
-Since the naming of this gem is not following the naming convention you can also add the following line to automatically require the gem:
+cvss = CvssSuite.parse('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N')
 
-```ruby
-gem 'cvss-suite', require: 'cvss_suite'
+cvss.version                                    # => 4.0
+cvss.overall_score                              # => 9.3
+cvss.severity                                   # => 'Critical'
+cvss.base.attack_vector.name                    # => 'Attack Vector'
+cvss.base.attack_vector.selected_value[:name]   # => 'Network'
 ```
 
-And then execute:
-
-    $ bundle
+`CvssSuite.new` is the non-raising counterpart, unchanged since 4.x: it returns an object whose
+`valid?` reports the problem instead. CVSS 2 and 3.x also expose `base_score`, `temporal_score` and
+`environmental_score`. See [Usage](https://github.com/0llirocks/cvss-suite/blob/master/docs/usage.md)
+for both.
 
-Or install it yourself as:
+## What you get
 
-    $ gem install cvss-suite
+- **Four specification versions, one API.** CVSS [2](https://www.first.org/cvss/v2/guide),
+  [3.0](https://www.first.org/cvss/v3.0/user-guide), [3.1](https://www.first.org/cvss/v3.1/user-guide)
+  and [4.0](https://www.first.org/cvss/v4.0/user-guide), including 4.0 macro-vector scoring.
+  `CvssSuite.parse` picks the version off the vector string.
+- **Metrics stay readable.** Every metric exposes its name, its permitted options, and which option
+  the vector selected. `CvssSuite.metrics` returns the same schema without a vector, for building
+  input forms.
+- **One runtime dependency.** `bigdecimal`, to keep arithmetic off binary floats.
+- **Over 80,000 examples** in the test suite, run against the oldest supported Ruby, current
+  stable, and head.
+- **Ruby 3.3+**, MIT licensed.
 
-## Version 3.x
+## Install
 
-If you are still using CvssSuite 3.x please refer to the [specific branch](https://github.com/0llirocks/cvss-suite/tree/3.x) for documentation and changelog.
-
-## Version 2.x
-
-If you are still using CvssSuite 2.x please refer to the [specific branch](https://github.com/0llirocks/cvss-suite/tree/2.x) for documentation and changelog.
-    
-## Version 1.x
-
-If you are still using CvssSuite 1.x please refer to the [specific branch](https://github.com/0llirocks/cvss-suite/tree/1.x) for documentation and changelog.
-
-## Usage
+Add the gem to your Gemfile. The gem is named `cvss-suite` but loads as `cvss_suite`, so tell
+Bundler which file to load:
 
 ```ruby
-require 'cvss_suite'
-
-cvss4 = CvssSuite.new('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N')
-
-vector = cvss4.vector       # 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N'
-version = cvss4.version     # 4.0
-valid = cvss4.valid?        # true
-severity = cvss4.severity   # 'Critical'
-
-cvss31 = CvssSuite.new('CVSS:3.1/AV:P/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:H/E:H/RL:U/RC:U')
-
-vector = cvss31.vector     # 'CVSS:3.1/AV:P/AC:H/PR:L/UI:R/S:U/C:L/I:L/A:H/E:H/RL:U/RC:U'
-version = cvss31.version   # 3.1
-valid = cvss31.valid?      # true
-severity = cvss31.severity # 'Medium'
-
-cvss3 = CvssSuite.new('CVSS:3.0/AV:L/AC:H/PR:L/UI:R/S:C/C:L/I:L/A:L/CR:L/IR:M/AR:H/MAV:N/MAC:H/MPR:N/MUI:R/MS:U/MC:N/MI:L/MA:H')
-
-vector = cvss3.vector       # 'CVSS:3.0/AV:L/AC:H/PR:L/UI:R/S:C/C:L/I:L/A:L/CR:L/IR:M/AR:H/MAV:N/MAC:H/MPR:N/MUI:R/MS:U/MC:N/MI:L/MA:H'
-version = cvss3.version     # 3.0
-valid = cvss3.valid?        # true
-severity = cvss3.severity   # 'High'
+gem 'cvss-suite', require: 'cvss_suite'
+```
 
-cvss = CvssSuite.new('AV:A/AC:M/Au:S/C:P/I:P/A:P/E:POC/RL:TF/RC:UC/CDP:L/TD:M/CR:M/IR:M/AR:M')
+Then:
 
-vector = cvss.vector       # 'AV:A/AC:M/Au:S/C:P/I:P/A:P/E:POC/RL:TF/RC:UC/CDP:L/TD:M/CR:M/IR:M/AR:M'
-version = cvss.version     # 2
-valid = cvss.valid?        # true
-severity = cvss.severity   # 'Low'
+```console
+$ bundle install
+```
 
-# Scores
-score = cvss4.overall_score                         # 9.3, cvss4 only has overall score
-base_score = cvss.base_score                        # 4.9
-temporal_score = cvss.temporal_score                # 3.6
-environmental_score = cvss.environmental_score      # 3.2
-overall_score = cvss.overall_score                  # 3.2
+Or without Bundler:
 
-# Available options
-access_vector = cvss.base.access_vector.name                # 'Access Vector'
-remediation_level = cvss.temporal.remediation_level.name    # 'Remediation Level'
+```console
+$ gem install cvss-suite
+```
 
-access_vector.values.each do |value|
-    value[:name]           # 'Local', 'Adjacent Network', 'Network'
-    value[:abbreviation]   # 'L', 'A', 'N'
-    value[:selected]       # false, true, false
-end
+## Documentation
 
-# Selected options
-cvss.base.access_vector.selected_value[:name]          # Adjacent Network
-cvss.temporal.remediation_level.selected_value[:name]  # Temporary Fix
+- **[Usage](https://github.com/0llirocks/cvss-suite/blob/master/docs/usage.md)** covers every score,
+  reading and enumerating metrics, and how invalid vectors behave.
+- **[Upgrading to 5.x](https://github.com/0llirocks/cvss-suite/blob/master/docs/upgrading-to-5.md)**
+  lists the breaking changes and the migration for each.
+- **[API reference](https://www.rubydoc.info/gems/cvss-suite)** on RubyDoc.
 
-# Exceptions
+Using an older major? Documentation and changelog live on the
+[3.x](https://github.com/0llirocks/cvss-suite/tree/3.x),
+[2.x](https://github.com/0llirocks/cvss-suite/tree/2.x) and
+[1.x](https://github.com/0llirocks/cvss-suite/tree/1.x) branches.
 
-cvss = CvssSuite.new('random_string')  # invalid vector
-valid = cvss.valid?     # false
-version = cvss.version  # will throw CvssSuite::Errors::InvalidVector: Vector is not valid!
-cvss.base_score         # will throw CvssSuite::Errors::InvalidVector: Vector is not valid!
+## Known issues
 
-cvss = CvssSuite.new(1337)  # invalid vector
-valid = cvss.valid?     # false
-version = cvss.version  # will throw CvssSuite::Errors::InvalidVector: Vector is not valid!
-cvss.base_score         # will throw CvssSuite::Errors::InvalidVector: Vector is not valid!
+Other implementations can produce scores differing by +/- 0.1, because floating-point arithmetic
+differs between languages and hardware platforms.
 
-CvssSuite.new()         # will throw a ArgumentError
+## Changelog
 
-cvss = CvssSuite.new('AV:N/AC:P/C:P/AV:U/RL:OF/RC:C')   # invalid vector, authentication is missing
-version = cvss.version  # 2
-valid = cvss.valid?     # false
-cvss.base_score         # will throw CvssSuite::Errors::InvalidVector: Vector is not valid!
-```
+Releases are recorded in
+[CHANGELOG.md](https://github.com/0llirocks/cvss-suite/blob/master/CHANGELOG.md), which ships inside
+the gem. The [Releases page](https://github.com/0llirocks/cvss-suite/releases) mirrors it.
 
-## Known Issues
+## Contributing
 
-There is a possibility of implementations generating different scores (+/- 0,1) due to small floating-point inaccuracies. This can happen due to differences in floating point arithmetic between different languages and hardware platforms.
+Bug reports and pull requests are welcome at
+[github.com/0llirocks/cvss-suite](https://github.com/0llirocks/cvss-suite). This project is intended
+to be a safe, welcoming space for collaboration.
 
-## Changelog
+Pull requests are squashed, so the title you write becomes the commit message and picks the next
+version. Title it as a [conventional commit](https://www.conventionalcommits.org):
 
-[Click here to see all changes.](https://github.com/0llirocks/cvss-suite/blob/master/CHANGES.md)
+| Title starts with | Releases |
+| --- | --- |
+| any type with a `!`, such as `feat!:` or `refactor!:` | a major |
+| `feat:` | a minor |
+| any other accepted type: `fix:`, `docs:`, `test:`, `refactor:`, `style:`, `perf:`, `chore:`, `build:`, `ci:`, `revert:` | a patch |
+| a title the check rejects | nothing at all |
 
-## Contributing
+Note there is no such thing as a merge that ships nothing quietly: every accepted type releases at
+least a patch. A title the automation cannot parse is skipped silently instead, which is what the
+check exists to catch, while the title is still easy to fix. Your change is credited in the changelog
+whichever prefix it carries -- the prefix only decides the version.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/0llirocks/cvss-suite. This project is intended to be a safe, welcoming space for collaboration.
+The description becomes the body of that commit, so write it for someone reading `git log` in two
+years. For a breaking change, add a `BREAKING CHANGE:` line saying what a user has to change.
 
 ## References
+
 [CvssSuite for .NET](https://cvsssuite.0lli.rocks)

data/docs/upgrading-to-5.md

@@ -0,0 +1,117 @@
+# Upgrading to 5.x
+
+Most callers need no change. `CvssSuite.new` and every score for a valid vector behave as they did
+in 4.x. What follows is the exceptions.
+
+## Ruby 3.3 is the minimum
+
+5.x requires Ruby 3.3 or newer. 4.1.4 ran on Ruby 2.6 and newer.
+
+## Invalid vectors no longer score
+
+In 4.x, only `base_score` checked that the vector was valid before computing. `temporal_score` and
+`environmental_score` did not, so a vector that `valid?` had already rejected could still hand back
+a plausible-looking number:
+
+```ruby
+cvss = CvssSuite.new('AV:A/AC:H/Au:M/C:C/I:C/A:C/ZZ:Q')   # ZZ is not a CVSS 2 metric
+
+cvss.valid?               # => false, in both 4.x and 5.x
+cvss.environmental_score  # 4.x: 6.2
+                          # 5.x: raises CvssSuite::Errors::InvalidVector
+```
+
+`overall_score` on the `InvalidCvss` returned for unrecognized input used to raise `NoMethodError`
+rather than `InvalidVector`. It now raises `InvalidVector` like every other reader.
+
+If you were rescuing `TypeError` or `NoMethodError` around these calls, rescue
+`CvssSuite::Errors::InvalidVector` instead. If you were checking `valid?` first, nothing changes.
+
+## Three module methods are now private
+
+`CvssSuite.version`, `CvssSuite.prepare_vector` and `CvssSuite.prepare_cvss2_vector` were public,
+but only because `CvssSuite.new` needed them. They read module-level state that `CvssSuite.new`
+writes, so their return value depended on whichever vector was parsed last, anywhere in the
+process. Calling them directly could not be relied on, and now raises `NoMethodError`.
+
+To get the CVSS version of a vector, ask the vector:
+
+```ruby
+# Before (raises NoMethodError as of 5.x)
+CvssSuite.new('CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H')
+CvssSuite.version   # 3.1, but only until anything else parses a vector
+
+# After
+CvssSuite.new('CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H').version   # => 3.1
+```
+
+`CvssSuite.version` was never the gem version; that is `CvssSuite::VERSION`, unchanged.
+
+There is no replacement for `prepare_vector` and `prepare_cvss2_vector`. They strip the `CVSS:x.x/`
+prefix, or the surrounding parentheses of a CVSS 2 vector, before the vector reaches the parser, and
+that is now an implementation detail of `CvssSuite.new`.
+
+## `InvalidVector` messages now name the vector
+
+The message was the bare `Vector is not valid!` regardless of input. It now says which vector:
+
+```ruby
+CvssSuite.parse('CVSS:3.0/')
+# 4.x: CvssSuite::Errors::InvalidVector: Vector is not valid!
+# 5.x: CvssSuite::Errors::InvalidVector: Vector is not valid: "CVSS:3.0/"
+```
+
+Nothing about the class, or about when it is raised, has changed. Only match on the message if you
+have to, and match a prefix rather than the whole string: the vector is repeated back through
+`inspect`, and input longer than 200 characters is trimmed with a trailing `...`.
+
+The vector named is the one you passed, not the parsed form — so a CVSS 2 vector in parentheses is
+reported with its parentheses, and a non-string reads as itself (`CvssSuite.new(1337)` reports
+`1337`, not `""`).
+
+## `Errors::CvssError` is gone, replaced by `CvssSuite::Error`
+
+`CvssSuite::Errors::CvssError` was documented as "the base error class to be inherited by more
+specific classes", but nothing inherited it and the gem never raised it, so `rescue
+CvssSuite::Errors::CvssError` caught nothing. It has been removed. In its place, every error the gem
+raises includes the module `CvssSuite::Error`:
+
+```ruby
+begin
+  CvssSuite.metrics(version)   # raises UnsupportedVersion
+  CvssSuite.parse(vector)      # raises InvalidVector
+rescue CvssSuite::Error => e   # one rescue for either
+end
+```
+
+The concrete classes and their ancestors are unchanged: `InvalidVector` is still a `RuntimeError`,
+`InvalidParentClass` and `UnsupportedVersion` are still `ArgumentError`s, and every `rescue` naming
+those keeps working. This matters more in 5.x than it did in 4.x, because `CvssSuite.parse` makes an
+exception the expected way to hear about a bad vector.
+
+You need to change something only if you referenced `CvssError` yourself — raising it, subclassing
+it, or rescuing it. Rescuing it caught nothing, so deleting that `rescue` is the fix. Note
+`CvssSuite::Error` is a module, so `raise CvssSuite::Error` is a `TypeError`; raise one of the
+classes under `CvssSuite::Errors` instead.
+
+## `CvssSuite.parse` is new
+
+`CvssSuite.parse` raises `CvssSuite::Errors::InvalidVector` on input it cannot parse, where
+`CvssSuite.new` returns an object that reports the problem only through `valid?` and the scores.
+This is additive; `CvssSuite.new` is unchanged. See
+[Parsing a vector](usage.md#parsing-a-vector).
+
+```ruby
+# 4.x, still works
+cvss = CvssSuite.new(untrusted_input)
+return render_error unless cvss.valid?
+
+# 5.x, when a bad vector is a bug rather than an input
+cvss = CvssSuite.parse(vector_from_our_own_database)
+```
+
+## What did not change
+
+Scores for valid vectors are unchanged across all four CVSS versions. `CvssSuite.new` still never
+raises, and still returns the same object for the same input. Metric names, permitted options and
+selected options are unchanged.

data/docs/usage.md

@@ -0,0 +1,234 @@
+# Usage
+
+Every score, every metric, and what invalid vectors do.
+
+## Parsing a vector
+
+`CvssSuite.parse` and `CvssSuite.new` return the same object for a valid vector. They differ on
+input they cannot parse; pick the failure mode you want.
+
+**`CvssSuite.parse` raises immediately** on any bad input:
+
+```ruby
+CvssSuite.parse('CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H').base_score
+# => 9.8
+CvssSuite.parse('CVSS:3.0/')
+# => raises CvssSuite::Errors::InvalidVector: Vector is not valid: "CVSS:3.0/"
+```
+
+**`CvssSuite.new` never raises.** It hands back an object whose `valid?` is `false` and defers the
+error to whatever eventually reads a score. What that object is depends on whether the vector's
+prefix was recognized:
+
+| `CvssSuite.new(...)` | returns | `valid?` | `version` | `base_score` |
+| --- | --- | --- | --- | --- |
+| `'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'` | `Cvss31` | `true` | `3.1` | `9.8` |
+| `'CVSS:3.0/'` | `Cvss3` | `false` | `3.0` | raises `Errors::InvalidVector` |
+| `'AV:N/AC:L'` | `Cvss2` | `false` | `2` | raises `Errors::InvalidVector` |
+| `'random_string'` | `InvalidCvss` | `false` | raises `Errors::InvalidVector` | raises `Errors::InvalidVector` |
+| `1337` | `InvalidCvss` | `false` | raises `Errors::InvalidVector` | raises `Errors::InvalidVector` |
+
+Note rows two and three: a recognized prefix with an unusable body still comes back as a real
+version class.
+
+Use `CvssSuite.new` when an invalid vector is an expected input you intend to branch on:
+
+```ruby
+cvss = CvssSuite.new(untrusted_input)
+return render_error unless cvss.valid?
+```
+
+Use `CvssSuite.parse` when an invalid vector is a bug. The object `CvssSuite.new` returns stays
+quiet until something asks it for a number, so a caller who forgets `valid?` meets the exception far
+from the input that caused it. Or never, if that read sits behind a conditional.
+
+Both raise `ArgumentError` when called with no argument.
+
+CVSS 2 vectors are accepted with or without surrounding parentheses. Otherwise the string must begin
+with the vector: anything before the `CVSS:x.x/` prefix, or before a CVSS 2 vector's first metric,
+makes it unparseable.
+
+## Scores
+
+CVSS 2, 3.0 and 3.1 expose the three sub-scores plus an overall score:
+
+```ruby
+cvss = CvssSuite.parse('AV:A/AC:M/Au:S/C:P/I:P/A:P/E:POC/RL:TF/RC:UC/CDP:L/TD:M/CR:M/IR:M/AR:M')
+
+cvss.base_score            # => 4.9
+cvss.temporal_score        # => 3.6
+cvss.environmental_score   # => 3.2
+cvss.overall_score         # => 3.2
+```
+
+`overall_score` is the most specific score the vector provides:
+
+- the environmental score, if environmental metrics were given
+- otherwise the temporal score, if temporal metrics were given
+- otherwise the base score
+
+CVSS 4.0 defines a single score. `overall_score` is that score, and `base_score` is exposed
+alongside it so a 4.0 vector can be compared against the base score that NVD and GHSA publish:
+
+```ruby
+cvss = CvssSuite.parse('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N')
+
+cvss.overall_score   # => 9.3
+cvss.base_score      # => 9.3
+```
+
+## Severity
+
+`severity` maps a score onto the qualitative rating from the specification. The two rating scales
+differ, and so does the score each one reads:
+
+| | scale | reads |
+| --- | --- | --- |
+| CVSS 3.0, 3.1, 4.0 | None, Low, Medium, High, Critical | `overall_score` |
+| CVSS 2 | Low, Medium, High | `base_score` |
+
+CVSS 2 predates the Critical band and rates on the base score, so a CVSS 2 vector can report a severity
+that looks inconsistent with its own `overall_score`:
+
+```ruby
+cvss = CvssSuite.parse('AV:A/AC:M/Au:S/C:P/I:P/A:P/E:POC/RL:TF/RC:UC/CDP:L/TD:M/CR:M/IR:M/AR:M')
+
+cvss.base_score      # => 4.9
+cvss.overall_score   # => 3.2
+cvss.severity        # => 'Medium', rated on the 4.9 base score
+```
+
+## Reading metrics
+
+A parsed vector exposes its metric groups. Every version has `base`. CVSS 2 and 3.x add `temporal`
+and `environmental`. CVSS 4.0 has `threat`, `environmental`, `environmental_security` and
+`supplemental`. Each metric answers its human-readable name, all permitted options, and the option
+this vector selected.
+
+```ruby
+cvss = CvssSuite.parse('AV:A/AC:M/Au:S/C:P/I:P/A:P/E:POC/RL:TF/RC:UC/CDP:L/TD:M/CR:M/IR:M/AR:M')
+
+access_vector = cvss.base.access_vector
+
+access_vector.name                     # => 'Access Vector'
+access_vector.selected_value[:name]    # => 'Adjacent Network'
+
+access_vector.values
+# => [{ name: 'Network',          abbreviation: 'N', weight: 1.0,   selected: false },
+#     { name: 'Adjacent Network', abbreviation: 'A', weight: 0.646, selected: true  },
+#     { name: 'Local',            abbreviation: 'L', weight: 0.395, selected: false }]
+
+cvss.temporal.remediation_level.name                   # => 'Remediation Level'
+cvss.temporal.remediation_level.selected_value[:name]  # => 'Temporary Fix'
+```
+
+On CVSS 2 and 3.x, `weight` is the numeric coefficient the specification assigns to that option. The
+score is computed from it; it is exposed so you can show your working. CVSS 4.0 options carry no
+`weight`, because 4.0 scores through a macro-vector lookup rather than per-option coefficients.
+
+The original vector string is available too:
+
+```ruby
+CvssSuite.parse('CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N').vector
+# => 'CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N'
+```
+
+One asymmetry: a CVSS 2 vector given in parentheses comes back without them.
+`CvssSuite.parse('(AV:N/AC:L/Au:N/C:N/I:N/A:C)').vector` returns
+`'AV:N/AC:L/Au:N/C:N/I:N/A:C'`.
+
+To enumerate every metric in a group rather than naming one, use `properties`:
+
+```ruby
+cvss.base.properties.map(&:abbreviation)
+# => ['AV', 'AC', 'Au', 'C', 'I', 'A']
+```
+
+## Metrics without a vector
+
+`CvssSuite.metrics` returns the schema for a CVSS version without parsing anything, which is what
+you want when building an input form or validating against the specification rather than against a
+particular vector:
+
+```ruby
+schema = CvssSuite.metrics(3.1)
+
+schema.map { |group| group[:group] }
+# => ['Base', 'Temporal', 'Environmental']
+
+schema.first[:metrics].first
+# => { name: 'Attack Vector',
+#      abbreviation: 'AV',
+#      options: [{ name: 'Network',  abbreviation: 'N', default: false },
+#                { name: 'Adjacent', abbreviation: 'A', default: false },
+#                { name: 'Local',    abbreviation: 'L', default: false },
+#                { name: 'Physical', abbreviation: 'P', default: false }] }
+```
+
+Optional metrics flag their Not Defined option as the default, so a form can preselect it:
+
+```ruby
+temporal = CvssSuite.metrics(3.1).find { |group| group[:group] == 'Temporal' }
+temporal[:metrics].first[:name]                                          # => 'Exploit Code Maturity'
+temporal[:metrics].first[:options].select { |o| o[:default] }.map { |o| o[:abbreviation] }
+# => ['X']
+```
+
+It accepts `2`, `3.0`, `3.1` and `4.0`, the string equivalents of each, and the value a parsed
+vector reports from `version`. Anything else raises `CvssSuite::Errors::UnsupportedVersion`, which
+descends from `ArgumentError`.
+
+## Exceptions
+
+Reading a score or a version off an invalid vector raises `CvssSuite::Errors::InvalidVector`:
+
+```ruby
+cvss = CvssSuite.new('random_string')
+
+cvss.valid?       # => false
+cvss.version      # => raises CvssSuite::Errors::InvalidVector: Vector is not valid: "random_string"
+cvss.base_score   # => raises CvssSuite::Errors::InvalidVector: Vector is not valid: "random_string"
+```
+
+The message names the vector, so an exception surfacing well away from wherever the vector came from
+still says which one it was. It is the vector you passed, not the parsed form, so a CVSS 2 vector in
+parentheses keeps them. Input longer than 200 characters is trimmed with a trailing `...`; a CVSS 4.0
+vector carrying every metric the specification defines, each at its longest option, is 178, so real
+vectors are repeated back whole.
+
+A vector whose prefix was recognized but whose body is unusable still answers `version`, and only
+reports the problem through `valid?` and the scores:
+
+```ruby
+cvss = CvssSuite.new('AV:N/AC:P/C:P/AV:U/RL:OF/RC:C')   # authentication is missing
+
+cvss.version      # => 2
+cvss.valid?       # => false
+cvss.base_score   # => raises CvssSuite::Errors::InvalidVector: Vector is not valid: "AV:N/AC:P/C:P/AV:U/RL:OF/RC:C"
+```
+
+Every score reader behaves the same way. On CVSS 2 and 3.x that is `base_score`, `temporal_score`,
+`environmental_score`, `overall_score` and `severity`. CVSS 4.0 folds threat and environmental
+metrics into its single score, so it defines only `base_score`, `overall_score` and `severity`;
+calling `temporal_score` or `environmental_score` on a 4.0 vector raises `NoMethodError` whether or
+not the vector is valid.
+
+The metric groups themselves are not guarded. `cvss.base`, `cvss.temporal` and `cvss.environmental`
+hand back live objects on an invalid vector, and their `score` will compute from it. Read scores
+through the methods above rather than through the metric groups.
+
+Every error class lives under `CvssSuite::Errors`, and every one of them includes `CvssSuite::Error`.
+Rescue that to catch anything this gem raises without naming the classes one by one:
+
+```ruby
+begin
+  schema = CvssSuite.metrics(params[:version])   # raises UnsupportedVersion
+  cvss   = CvssSuite.parse(params[:vector])      # raises InvalidVector
+rescue CvssSuite::Error => e
+  render_error(e.message)
+end
+```
+
+`CvssSuite::Error` is a module, not a base class, so the concrete errors keep the ancestors you may
+already be rescuing: `InvalidVector` descends from `RuntimeError`, so a bare `rescue => e` still
+catches it, and `UnsupportedVersion` and `InvalidParentClass` descend from `ArgumentError`.