CvssSuite for Ruby

Score a CVSS vector string, and read back every metric in it.

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) 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 😄 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.

Example

require 'cvss_suite'

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.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'

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 for both.

What you get

• Four specification versions, one API. CVSS 2, 3.0, 3.1 and 4.0, 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.

Install

Add the gem to your Gemfile. The gem is named cvss-suite but loads as cvss_suite, so tell Bundler which file to load:

gem 'cvss-suite', require: 'cvss_suite'

Then:

$ bundle install

Or without Bundler:

$ gem install cvss-suite

Documentation

• Usage covers every score, reading and enumerating metrics, and how invalid vectors behave.
• Upgrading to 5.x lists the breaking changes and the migration for each.
• API reference on RubyDoc.

Using an older major? Documentation and changelog live on the 3.x, 2.x and 1.x branches.

Known issues

Other implementations can produce scores differing by +/- 0.1, because floating-point arithmetic differs between languages and hardware platforms.

Changelog

Releases are recorded in CHANGELOG.md, which ships inside the gem. The Releases page mirrors it.

Contributing

Bug reports and pull requests are welcome at github.com/0llirocks/cvss-suite. This project is intended to be a safe, welcoming space for collaboration.

Pull requests are squashed, so the title you write becomes the commit message and picks the next version. Title it as a conventional commit:

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

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.

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