cvss-score-calculator

A Pi skill for calculating CVSS v4.0 vulnerability scores with the cvss Python library (Red Hat Product Security).

Scoring is performed by the pinned library, wrapped by a CLI that validates inputs, reports severity and metric groups, distinguishes user-supplied facts from worst-case defaults, and asks for missing required metrics instead of inventing them.

Install

Requires Python 3 on the machine where Pi runs. Network access (PyPI) is needed once for the pinned install; afterwards the skill also works fully offline via the bundled library source.

pi install npm:cvss-score-calculator

Or from a git repository or local checkout:

pi install git:<repository-url>
pi install ./cvss-score-calculator

Optional one-time setup (isolated virtual environment with the hash-verified cvss==3.6 from PyPI); after an npm install the package lives under Pi's npm directory:

bash ~/.pi/agent/npm/node_modules/cvss-score-calculator/skills/cvss-score-calculator/scripts/setup.sh

What's included

skills/cvss-score-calculator/
├── SKILL.md                  # skill instructions loaded by Pi
├── references/               # CVSS v4.0 metric reference, defaults, caveats
├── scripts/                  # setup.sh, run.sh, cvss_score.py CLI
├── tests/                    # 35 automated tests (stdlib unittest)
├── requirements.txt          # pinned, hash-verified cvss==3.6
├── LICENSES/                 # LGPL-3.0 and GPL-3.0 texts
├── THIRD_PARTY_NOTICES.md    # provenance, license verification, replacement guide
└── third_party/cvss-3.6/     # vendored, unmodified upstream library (LGPLv3+)

The skill also works with other agents that support the Agent Skills specification: copy the skills/cvss-score-calculator/ directory into the agent's skills location.

Usage

Agents invoke the CLI through the wrapper (uses the virtual environment when present, otherwise falls back to the bundled library source). Paths below are relative to the skill directory:

cd skills/cvss-score-calculator

# Score a supplied vector
scripts/run.sh scripts/cvss_score.py score \
  "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:H/SI:H/SA:N"
# Score: 9.9  (Critical)

# Build a vector from metrics, then score it
scripts/run.sh scripts/cvss_score.py build \
  AV=N AC=L AT=N PR=N UI=N VC=N VI=L VA=N SC=N SI=N SA:N E=U

# Validate only (no score) / list metric values / machine-readable output
scripts/run.sh scripts/cvss_score.py validate "CVSS:4.0/AV:N/AC:L"
scripts/run.sh scripts/cvss_score.py describe AV
scripts/run.sh scripts/cvss_score.py score "CVSS:4.0/..." --json

Example output:

CVSS v4.0 assessment
  Vector (supplied):  CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/E:U
  Vector (canonical): CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/E:U
  Score:              5.2  (Medium)
  Red Hat notation:   5.2/CVSS:4.0/AV:N/AC:L/AT:P/PR:N/UI:P/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N/E:U
  Metric groups used: Base, Threat
  Nomenclature:       CVSS-BT
  Metrics supplied:   12
  Defaults assumed (NOT supplied by the user):
    - CR -> High (H) [assumed worst case, not supplied by user]
    - IR -> High (H) [assumed worst case, not supplied by user]
    - AR -> High (H) [assumed worst case, not supplied by user]
    - MAV/MAC/MAT/MPR/MUI/MVC/MVI/MVA/MSC/MSI/MSA -> inherit the corresponding Base metric values [assumed, not supplied by user]
  Metric explanation (supplied metrics only):
    - AV=N - Attack Vector: Network (supplied)
    ...

Exit codes: 0 success, 1 invalid input (malformed vector, invalid or duplicate metric, missing required metrics — listed with allowed values — or unsupported CVSS version), 2 dependency failure, 3 usage error.

Tests

npm test          # or: bash skills/cvss-score-calculator/tests/run_tests.sh

35 stdlib-unittest tests cover the 19 authoritative score/vector pairs from FIRST's official CVSS v4.0 examples, severity boundary scores (0.0/0.1/3.9/4.0/6.9/7.0/8.9/9.0/10.0), all metric groups (CVSS-B/-BT/-BE/-BTE, Supplemental), defaults/assumptions, the specification's invalid-vector examples, and the CLI end-to-end. No network access or extra packages are needed.

Verified capabilities and limitations

• The shipped library (cvss 3.6) reproduces all 19 score/vector pairs from FIRST's official v4.0 examples exactly, with severities per specification Table 22; full CVSS-B/BT/BE/BTE scoring including Environmental modified metrics.
• Supplemental metrics (S, AU, R, V, RE, U) are validated and reported but do not affect the score, per the specification.
• CVSS v2/v3.x are supported by the library but intentionally out of scope: only CVSS:4.0/ vectors are accepted.
• Field ordering is not enforced on input; a canonical ordered vector is returned.

License

• Skill and package code: MIT (skills/cvss-score-calculator/LICENSE).
• Vendored cvss library: LGPL-3.0-or-later (Red Hat; cvss4.py is additionally BSD-licensed per its file header by FIRST.ORG/Red Hat), with LGPL-3.0 and GPL-3.0 texts included in LICENSES/.
• Full provenance, license verification for the exact shipped version, the modification log, and instructions for replacing the library with an interface-compatible modified version are in skills/cvss-score-calculator/THIRD_PARTY_NOTICES.md.

Security note

The skill instructs the agent to run the bundled Python scripts. Review the source (skills/cvss-score-calculator/scripts/) before installing, as you should for any third-party package.