gcve-sbom-analyzer

Overview

GCVE-powered SBOM vulnerability analyzer.

gcve-sbom-analyzer reads a Software Bill of Materials (CycloneDX or SPDX), looks up every component in the GCVE vulnerability database, and reports which components are vulnerable. It ranks what to fix first by known exploitation (CISA KEV), exploit likelihood (EPSS) and severity, and its exit code can gate a CI pipeline.

• Formats: CycloneDX and SPDX 2.x JSON, detected from the file content.
• Components: language packages (Maven, npm, PyPI, Go, Cargo, NuGet…), Debian, Ubuntu, Alpine, Red Hat, Rocky Linux and AlmaLinux packages, and anything identified by a CPE.
• Version-aware: only vulnerabilities affecting the component's version are reported.
• Prioritized: every vulnerability gets a priority tier, from P1 (known exploited) to P4.
• No account or API key: GCVE and OSV are queried anonymously.

Installation

Requires Python 3.12 or later.

pipx install gcve-sbom-analyzer

or, in a virtual environment:

pip install gcve-sbom-analyzer

Quick start

gcve-sbom-analyzer scan bom.json

 GCVE SBOM Analyzer
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 File    : cyclonedx-java.json
 Format  : cyclonedx
 Scanned : 2026-09-29 20:32:06 UTC

 Components scanned : 4
 Vulnerable         : 4
 Clean              : 0

 Vulnerabilities found : 57
     CRITICAL          : 10
     HIGH              : 36
     MEDIUM            : 10
     LOW               : 1

 P1  Known exploited  : 2
 P2  EPSS ≥ 10%       : 8
 P3  Critical or high : 38
 P4  Other            : 9

────────────────────────────────────────────────────────────────────────────────

 jackson-databind  2.9.10  47 vulnerabilities  ·  CRITICAL
 log4j-api         2.14.1  1 vulnerability     ·  MEDIUM
 log4j-core        2.14.1  7 vulnerabilities   ·  CRITICAL
 spring-core       5.3.17  2 vulnerabilities   ·  HIGH

Results come from live GCVE data, so the counts change over time.

Example SBOMs

The examples/ directory holds small SBOMs of known-vulnerable components to try the tool on:

Usage

gcve-sbom-analyzer scan [OPTIONS] SBOM_PATH

Progress and errors go to stderr, so stdout only ever carries the report.

Listing every vulnerability

gcve-sbom-analyzer scan bom.json --detailed --only-vulnerable

 nginx  1.20.0  ·  CVE-2025-23419  MEDIUM    5.3
                ·  CVE-2024-35200  MEDIUM    5.3  unverified
                ·  CVE-2023-44487  HIGH      7.5
                ·  CVE-2022-41742  HIGH      7.1

A vulnerability marked unverified was found for the component's product, but neither its record nor the NVD says whether the component's version is affected. It is kept rather than dropped, and counted like any other.

Ranking what to fix first

gcve-sbom-analyzer scan bom.json --top 5

 #  Tier  CVE             Component                KEV   EPSS  Severity  Score
 1  P1    CVE-2021-44228  log4j-core 2.14.1        ●    99.9%  CRITICAL   10.0
 2  P1    CVE-2021-45046  log4j-core 2.14.1        ●    99.9%  CRITICAL    9.0
 3  P2    CVE-2021-45105  log4j-core 2.14.1             99.9%  MEDIUM      5.9
 4  P2    CVE-2021-44832  log4j-core 2.14.1             97.9%  MEDIUM      6.6
 5  P2    CVE-2020-8840   jackson-databind 2.9.10       26.5%  CRITICAL      —

Each vulnerability falls into the first tier it qualifies for:

Within a tier, vulnerabilities are sorted by EPSS, then severity, then CVSS score. The EPSS column is the probability of exploitation in the next 30 days, rounded down to 0.1%.

JSON output

gcve-sbom-analyzer scan bom.json --json > report.json

The report holds the summary counts (total_vulnerabilities_count, vulnerabilities_by_severity, vulnerabilities_by_priority, known_exploited_count…) and one entry per component under findings. Each entry lists its vulnerabilities with their CVE id, description, CVSS, severity, references, version_status (affected or unknown), KEV entry, EPSS score and priority tier. The JSON layout may still change before version 1.0.

Exit codes and CI

--fail-on only changes the exit code, never what is reported. For example, to fail a pipeline on known-exploited vulnerabilities only:

gcve-sbom-analyzer scan bom.json --fail-on kev

How it works

1. The SBOM is parsed, and each component is identified by its Package URL (PURL) or its CPE.
2. Packages from a known ecosystem are looked up in OSV, which indexes advisories by package and version. OS packages are looked up by source package and distribution release, the way Debian, Ubuntu, Alpine and Red Hat publish their advisories. Components identified by a GitHub repository, through a github PURL or a generic PURL whose vcs_url or download_url qualifier points at GitHub, are looked up by repository and release tag. Each advisory found is then fetched from GCVE, under its CVE id when it has one.
3. Other components, and repositories OSV finds nothing for, are searched in GCVE by vendor and product, taken from their CPE or PURL. The affected version ranges of each CVE record are checked against the component's version, and when a record leaves that undecided, the NVD configurations stored in GCVE settle it where they can.
4. GCVE also supplies each CVE's CISA KEV entry and EPSS score, which set its priority tier.

Every lookup goes to the public db.gcve.eu and api.osv.dev APIs. The scan therefore needs network access, and it sends the names and versions of the SBOM's components to both services.

Known limitations

• JSON input only: SPDX tag-value, YAML and RDF, and CycloneDX XML are not read yet.
• SPDX 2.x only: SPDX 3.0 documents are not supported.
• Slow on large SBOMs: components are looked up one at a time, about 0.2 s each for packages and longer for CPE-identified components with many CVEs. An SBOM of several hundred components takes a few minutes.
• PURLs with no package ecosystem: generic PURLs that point at no GitHub repository, and other PURL types OSV does not index, fall back to the vendor/product search, which often finds nothing for them unless the component also has a CPE. Repositories hosted elsewhere than GitHub (GitLab, Bitbucket) are not looked up by repository yet.
• Unknown release tags: OSV reports nothing for a version matching none of a repository's tags, just as for a version no advisory affects, so such a component falls back to the vendor/product search.
• Red Hat: Red Hat's advisories only cover vulnerabilities it has fixed, so vulnerabilities still unfixed in a RHEL package are not reported.
• Other distributions: SUSE, Wolfi, Chainguard, Amazon Linux, Oracle Linux and Azure Linux packages are not matched to their advisories. For a supported distribution whose release is missing from the PURL or cannot be mapped, advisories from every release are used and the results are marked unverified. Alpine has no such release-less advisories, so those packages fall back to the vendor/product search.
• Trivy source packages: the source package names Trivy records in its own properties are read from CycloneDX SBOMs only, not from SPDX ones.

Contributing

Bug reports, ideas and pull requests are welcome: see the contributing guide.

License

GNU General Public License v3.0 or later.