<div align="center">

CVSS Skills

Professional CVSS v3.0 / v3.1 Toolkit — Parse, Score, Validate, Compare & Build Vulnerability Vectors

🌐 Website: scagogogo.github.io/cvss-skills — Full documentation, tutorials, API reference

Languages: English | 简体中文

</div>

For AI agents: This README is structured for machine consumption. Jump to Integration Methods for install commands, CLI Commands for the command surface, and Pre-built Binaries for exact download URLs per OS/arch. The website at <https://scagogogo.github.io/cvss-skills/> mirrors this content.

🤖 Overview

CVSS Skills is a single, well-tested toolkit for the Common Vulnerability Scoring System (CVSS) v3.0 / v3.1. It solves the painful parts of working with CVSS vectors programmatically: error-prone parsing, version-specific scoring formulas, manual comparison, and scattered validation.

It is delivered through 4 integration methods:

flowchart LR
    subgraph Methods["Integration Methods"]
        direction TB
        S["🤖 Skills<br/>Claude Code"]
        SDK["📦 Go SDK<br/>go get"]
        CLI["💻 CLI<br/>pre-built"]
        MCP["🔌 MCP Server<br/>AI agents"]
    end

    S -->|natural language| U(["User"])
    SDK -->|library| A(["App"])
    CLI -->|scripts| B(["Batch"])
    MCP -->|protocol| C(["Agent"])

    classDef m fill:#e6f4ff,stroke:#1677ff,color:#003a8c
    classDef u fill:#f6ffed,stroke:#52c41a,color:#135200
    class S,SDK,CLI,MCP m
    class U,A,B,C u

Repository facts

Module path	github.com/scagogogo/cvss-skills
Language	Go (≥ 1.18)
License	MIT
CLI binary name	cvss
CLI entry point	cmd/cvss-cli/
Release artifacts	30+ packages (6 OS × multi-arch) via GoReleaser
Latest release
Website	<https://scagogogo.github.io/cvss-skills/>

🏛️ Architecture

Every integration surface is a thin layer over the same well-tested Go core — nothing re-implements scoring:

flowchart TB
    subgraph Surfaces["Integration Surfaces"]
        direction LR
        Skills["🤖 Claude Code Skills"]
        MCP["🔌 MCP Server"]
        CLI["💻 CLI (cvss)"]
        SDK["📦 Go SDK"]
    end
    subgraph Core["Core Packages"]
        direction LR
        Parser["pkg/parser"]
        CVSS["pkg/cvss"]
        Vector["pkg/vector"]
    end
    Skills --> CLI
    MCP --> CLI
    CLI --> Parser
    SDK --> Parser --> Vector --> CVSS --> Result(["Score · Severity · JSON"])

The canonical pipeline — from a raw vector string to a score and severity:

flowchart LR
    A["CVSS:3.1/AV:N/..."] --> B{Parse}
    B -->|error| E1["error<br/>(invalid magic head,<br/>malformed vector, …)"]
    B -->|ok| C["Cvss3x struct"]
    C --> D{Validate}
    D -->|missing metric| E2["ValidationErrors"]
    D -->|complete| F["Calculator"]
    F --> G["Overall score<br/>(base / temporal /<br/>environmental, as present)"]
    G --> H["GetSeverity()"]
    H --> K(["9.8 · Critical"])

✨ Feature Map

mindmap
  root((CVSS Skills))
    Parsing
      v3.0 / v3.1 vectors
      Relaxed parsing
      ParseAndScore
      Builder API
      FromMap
    Scoring
      Base / Temporal / Environmental
      Severity ratings
      Per-metric breakdown
    Validation
      Structural checks
      ValidationErrors
      IsComplete
      MissingMetrics
    Comparison
      Diff
      Merge
      Equal / SameSeverity
    Distance
      Euclidean
      Manhattan
      Hamming
      Jaccard
    Serialization
      JSON
      Text
      CSV I/O
      Batch
    Advanced
      Sensitivity analysis
      Score range
      Version-aware
      Presets
      Mock generators

🚀 Quick Start

1. Skills (Claude Code) — One Command

claude mcp add --scope user cvss-skills -- https://github.com/scagogogo/cvss-skills

This enables 10 CVSS skills inside Claude Code — each a markdown instruction file under .claude/skills/ that tells Claude which cvss CLI command to run: cvss-parse, cvss-score, cvss-validate, cvss-construct, cvss-compare, cvss-metrics, cvss-serialize, cvss-advanced, cvss-extract, cvss-install. Ask in natural language ("score this vector: …" or "extract CVSS from this Trivy report") and Claude picks the right skill automatically.

<details> <summary>Manual installation</summary>

Add to your project's .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "cvss-skills": {
      "type": "github",
      "url": "https://github.com/scagogogo/cvss-skills"
    }
  }
}

</details>

2. Go SDK — Full-Featured Library

go get github.com/scagogogo/cvss-skills@latest

package main

import (
    "fmt"
    "log"

    "github.com/scagogogo/cvss-skills/pkg/parser"
)

func main() {
    // One-step parse and score
    cv, score, severity, err := parser.ParseAndScore(
        "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Score: %.1f (%s)\n", score, severity) // Score: 9.8 (Critical)
    _ = cv
}

3. CLI — Pre-built Binary or go install

# Install a pre-built binary (auto-detects OS/arch, resolves latest version)
os=$(uname -s | tr '[:upper:]' '[:lower:]'); arch=$(uname -m)
case "$arch" in arm64) arch=aarch64 ;; amd64) arch=x86_64 ;; esac
ver=$(curl -sL https://api.github.com/repos/scagogogo/cvss-skills/releases/latest | sed -nE 's/.*"tag_name":\s*"v?([^"]+)".*/\1/p')
curl -sL "https://github.com/scagogogo/cvss-skills/releases/download/v${ver}/cvss-skills_${ver}_${os}_${arch}.tar.gz" | tar xz
sudo mv cvss /usr/local/bin/

# Or install with Go
go install github.com/scagogogo/cvss-skills/cmd/cvss-cli@latest

# Use
cvss score "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
# Output: 9.8 (Critical)

4. MCP — AI Agent Integration

Connect this repository as an MCP server from any MCP-compatible client to use CVSS tools through the standard Model Context Protocol.

📦 Pre-built Binaries

Every release ships 30+ packages built by GoReleaser via GitHub Actions. Archive naming:

cvss-skills_<version>_<os>_<arch>[v<arm>].<tar.gz|zip>

URL template (replace <version>, e.g. 0.1.0):

https://github.com/scagogogo/cvss-skills/releases/download/v<version>/cvss-skills_<version>_<os>_<arch>.<ext>

Each release also ships checksums.txt (SHA256). Full matrix and verification steps: see the Downloads page.

<details> <summary>Build from source</summary>

git clone https://github.com/scagogogo/cvss-skills.git
cd cvss-skills
go build -o cvss ./cmd/cvss-cli/
# or: make build

</details>

🧮 CVSS Vector Structure

A CVSS vector consists of up to 3 layers of metrics:

flowchart LR
    Prefix["CVSS:3.1<br/>version prefix"] --> Base

    subgraph Base["Base — required (8 metrics)"]
        direction LR
        AV["AV<br/>Attack Vector"]
        AC["AC<br/>Complexity"]
        PR["PR<br/>Privileges"]
        UI["UI<br/>User Inter."]
        S["S<br/>Scope"]
        C["C<br/>Confidential."]
        I["I<br/>Integrity"]
        A["A<br/>Availability"]
    end

    subgraph Temporal["Temporal — optional"]
        direction LR
        E["E<br/>Exploit"]
        RL["RL<br/>Remediation"]
        RC["RC<br/>Report Conf."]
    end

    subgraph Env["Environmental — optional"]
        direction LR
        CR["CR/IR/AR<br/>Requirements"]
        M["MAV…MA<br/>Modified base"]
    end

    Base --> Temporal --> Env

    classDef base fill:#e6f4ff,stroke:#1677ff,color:#003a8c
    classDef temp fill:#fffbe6,stroke:#faad14,color:#874d00
    classDef env fill:#f9f0ff,stroke:#722ed1,color:#391085
    class AV,AC,PR,UI,S,C,I,A base
    class E,RL,RC temp
    class CR,M env

🎚️ Severity Scale

flowchart LR
    Score(["Base Score 0.0–10.0"]) --> D{Band?}
    D -->|"= 0.0"| N["None"]
    D -->|"0.1–3.9"| L["Low"]
    D -->|"4.0–6.9"| M["Medium"]
    D -->|"7.0–8.9"| H["High"]
    D -->|"9.0–10.0"| Cr["Critical"]

    classDef none fill:#f0f0f0,stroke:#8c8c8c,color:#262626
    classDef low fill:#f6ffed,stroke:#52c41a,color:#135200
    classDef med fill:#fffbe6,stroke:#faad14,color:#874d00
    classDef high fill:#fff7e6,stroke:#fa8c16,color:#873800
    classDef crit fill:#fff1f0,stroke:#ff4d4f,color:#a8071a
    class N none
    class L low
    class M med
    class H high
    class Cr crit

📚 Go SDK Examples

Parse and Calculate

cvssVector, err := parser.ParseString("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H")
if err != nil {
    log.Fatalf("Parse failed: %v", err)
}

calculator := cvss.NewCalculator(cvssVector)
score, _ := calculator.Calculate()
fmt.Printf("CVSS Score: %.1f\n", score)              // 9.8
fmt.Printf("Severity: %s\n", cvss.GetSeverity(score)) // Critical

Builder API

cv := cvss.NewBuilder().Version(3, 1).
    AV('N').AC('L').PR('N').UI('N').S('U').
    C('H').I('H').A('H').MustBuild()

score, _ := cvss.NewCalculator(cv).Calculate()
fmt.Printf("Score: %.1f\n", score) // 9.8

Structured Validation

err := cv.Validate()
if ve, ok := err.(cvss.ValidationErrors); ok {
    fmt.Printf("Missing: %v\n", ve.MissingMetrics())
}

Diff and Merge

diffs := cv1.Diff(cv2)
for _, d := range diffs {
    fmt.Printf("%s: %s vs %s\n", d.Metric, d.V1, d.V2)
}

merged := cv1.Merge(cv2WithTemporal)

Distance Calculation

dc := cvss.NewDistanceCalculator(cv1, cv2)
fmt.Printf("Euclidean: %.2f\n", dc.EuclideanDistance())
fmt.Printf("Manhattan: %.2f\n", dc.ManhattanDistance())
fmt.Printf("Jaccard: %.2f\n", dc.JaccardSimilarity())

Score Breakdown

calc := cvss.NewCalculator(cv)
breakdown, _ := calc.GetScoreBreakdown()
for _, m := range breakdown.AllMetrics() {
    fmt.Printf("%s:%s = %.2f\n", m.ShortName, m.Value, m.Score)
}

Convenience Methods

cv.IsComplete()         // true if all 8 base metrics set
cv.Is31()               // true if CVSS v3.1
cv.HasTemporalMetrics() // true if temporal metrics present
cv.HasEnvironmentalMetrics() // true if environmental metrics present
cv.MissingMetrics()     // list of missing metric names
cv.Clone()              // deep copy
cv.BaseOnly()           // clone without temporal/environmental
cv.Equal(other)         // exact metric comparison
cv.EqualScore(other)    // score-based comparison
cv.SameSeverity(other)  // severity-based comparison

💻 CLI Commands

30+ commands. All support --format json for structured output. Run cvss --help for the full list.

📖 Documentation

Website: <https://scagogogo.github.io/cvss-skills/>

• Integration Methods — compare the 4 ways to use CVSS Skills
• CLI Reference — all 30+ commands
• Downloads — pre-built binary matrix
• API Reference — complete Go SDK API docs
• Examples & Tutorials — practical usage
• Quick Start Guide — get started in 5 minutes
• Chinese Documentation — 简体中文

🤝 Contributing

We welcome contributions, issue reports, and suggestions!

• GitHub Issues — report issues or suggestions
• Contributing Guide — how to contribute code

License

MIT License — see the LICENSE file for details.

Acknowledgments

• CVSS v3.1 Specification
• CVSS v3.0 Specification