Skip to content

Import Specifications#

This page explains the common specifications for how the information contained in an SBOM file is imported into FutureVuls (or not imported) when you import an SBOM file.

For the format-specific parsing specifications of CycloneDX and SPDX, refer to "CycloneDX Import Specifications" and "SPDX Import Specifications".

Import Process Flow#

SBOM files are imported roughly in the following flow. FutureVuls reads the list of components (software) from the SBOM file, determines the software type from each component's identifiers (PURL / CPE), and then registers them in FutureVuls as OS information, OS packages, and dependency libraries.

flowchart LR
    subgraph S1["1. Read"]
        A["SBOM file<br>Component list"]
    end
    subgraph S2["2. Type determination"]
        C{"Evaluate identifiers"}
    end
    subgraph S3["3. Software type"]
        D["OS package (os)<br>*Server SBOM, or application SBOM added to an SBOM server"]
        E["Language library (library)"]
        F["private"]
        G["Not registered"]
    end
    subgraph S4["4. Registration"]
        Z["Registered in FutureVuls"]
    end
    A --> C
    C -->|"OS package ecosystem PURL"| D
    C -->|"Language ecosystem PURL"| E
    C -->|"Other PURL / CPE / name only"| F
    C -->|"No identifiers"| G
    D --> Z
    E --> Z
    F --> Z

One OS per SBOM

FutureVuls assumes that one SBOM file corresponds to one OS. If a single SBOM contains information for multiple operating systems, an import error will occur.

Component Type Determination#

The software type under which a component is registered and the priority of its information depend on the identifiers it contains (PURL / CPE). To understand how vulnerability detection is performed against the registered information, refer to "Behavior When Both CPE and PURL Are Assigned".

The determination gives top priority to the PURL; if there is no PURL, the CPE or name is used.

Identifiers the component has Registered type Remarks
PURL (OS package ecosystem) os (OS package) Server SBOMs, or application SBOMs added to an SBOM server (see OS Packages Included in Application SBOMs). rpm / deb / apk, etc.
PURL (language ecosystem) library (language library) npm / maven / pypi, etc.
PURL (any other ecosystem) private
No PURL + has a CPE private Registered with the CPE information
No PURL or CPE + has a name private Registered with the name and version (if there is no version, it is registered as unknown)
None of PURL, CPE, or name ー Not registered due to lack of required information

Components that have both a PURL and a CPE are registered with both identifiers assigned.

Why PURL (Package URL) is Recommended

CPE (Common Platform Enumeration) carries a risk of false positives in vulnerability detection for OS packages and OSS libraries (details).

PURL, on the other hand, allows for precise identification based on the package manager's ecosystem, improving the accuracy of vulnerability detection. Therefore, FutureVuls prioritizes importing components that have a PURL.

Software with neither a PURL nor a CPE assigned will not be subject to vulnerability detection unless a CPE or PURL is manually assigned after the SBOM import (see CPE/PURL Assignment).

Supported Ecosystems (PURL Type)#

Whether a component is an OS package or a language library is determined by the PURL type (ecosystem).

  • OS packages (registered as os): rpm / deb / apk / alpm / win (Windows). dpkg and yum are also registered as os (treated as deb and rpm, respectively).
  • Language libraries (registered as library): npm (Node.js) / maven and gradle (Java) / pypi (Python) / conda (Conda) / gem (Ruby) / golang (Go) / composer (PHP) / cargo (Rust) / nuget (C#) / conan (C/C++) / cocoapods (CocoaPods) / swift (Swift) / hex (Erlang) / pub (Dart)

FutureVuls uses Trivy for language library detection, and the library ecosystems are selected from the range supported by Trivy.

Components with a PURL from any other ecosystem (such as generic) are registered as private. private components are not subject to PURL-based vulnerability detection.

Registered type and vulnerability detection scope are different

  • OS packages are subject to vulnerability detection when the OS of the SBOM is included in the Supported Environments of FutureVuls. For example, alpm (Arch Linux) is registered as os but is not detected because Arch Linux is not a supported OS. If the OS of the SBOM itself is unsupported, the import fails unless you enable "Ignore OS information" to import it without OS packages.
  • Language libraries are subject to detection for ecosystems that Trivy supports for vulnerability scanning. For example, conda is registered as library but is not detected because Trivy does not scan it for vulnerabilities.

For details, see "Supported Environments > Application Dependency Libraries".

Imported Information#

OS Information (Server SBOMs Only)#

The OS information contained in the SBOM file is registered as the server's OS only when the file is uploaded as a server SBOM (if there is no OS information, it is registered as Pseudo). We recommend including both the OS name and version (e.g., Ubuntu 20.04, CentOS 7). Note that an import error will occur if multiple sets of OS information are included.

Windows KB Information#

From server SBOMs generated by Vuls, FutureVuls can import applied and unapplied KBs based on the Windows Release and kernel version. FutureVuls uses the imported KBs in Windows scans to determine whether vulnerabilities have been fixed. For where KBs are output in an exported SBOM, see "Exporting an SBOM for a Single Server".

OS Package Information#

This is information about software managed by the OS package manager (RPM, deb, apk, etc.), and is displayed in Server Details > Software tab with the type os. It is subject to vulnerability detection when uploaded as a server SBOM. OS packages included in an application SBOM are subject to detection only when the SBOM is added to an SBOM server (see OS Packages Included in Application SBOMs).

An import error will occur if multiple types of OS packages are mixed (e.g., rpm and deb), or if OS package information is present but OS information is not included (except for application SBOMs added to an SBOM server). If OS information is missing, you can enable "Ignore OS information" to import the SBOM without OS packages.

OS Packages Included in Application SBOMs#

OS packages included in an application SBOM that you add to an SBOM server (a server created from a server SBOM) are subject to vulnerability detection in the same way as the OS packages of the server SBOM. You can use this, for example, to register packages added later to a base device's SBOM as a separate SBOM. This applies only to SBOM servers whose OS has been identified.

  • If the application SBOM does not contain OS information, its OS packages are imported as packages of the destination server's OS
  • A server can have only one version of each OS package with a given name. If you import or update an SBOM that contains an OS package with the same name as, but a different version from, an OS package in another SBOM on the server, an error occurs. The error message shows the conflicting package and the name of the other SBOM
  • Imported contents are reflected in the detection results after the next day's scheduled scan or after a manual scan

Dependency Library (Application) Information#

This is information about libraries managed by language-specific package managers (Java, Python, Node.js, Go, etc.). It is imported for both server SBOMs and application SBOMs, and is displayed in Server Details > Software tab with the type library.

Dependency libraries are grouped into applications per language ecosystem or per manifest file (pom.xml, package-lock.json, etc.) — how they are grouped depends on the tool that generated the SBOM. Note that lock files and manifest files themselves are not registered as libraries; only the dependencies listed within them are registered.

License Information#

The license information of components described in the SBOM is imported and can be viewed in Software Details > OSS License. When multiple licenses are specified, they are displayed as an SPDX license expression using AND / OR / WITH. Note that license names that appear invalid (empty strings, extremely long strings, or strings containing copyright notices or boilerplate text, etc.) are not imported.

Importing SBOMs Whose OS Cannot Be Determined#

An SBOM that contains OS packages (rpm / deb / apk, etc.) cannot be imported unless the OS can be determined. If you enable "Ignore OS information" in the import dialog (ignoreOS: true in the FutureVuls API), you can import only the components other than OS packages.

  • This applies to SBOMs that contain OS packages but no OS information, and SBOMs for an OS not listed in the Supported Environments
  • For SBOMs whose OS can be determined, OS packages are imported as before even if it is enabled
  • OS packages that were not imported are not registered, so they are not subject to vulnerability detection
  • If you import the SBOM as a server SBOM, the server's OS becomes Pseudo

Information That Is Not Imported#

Vulnerability Information#

Vulnerability information listed within the SBOM file is not imported.

FutureVuls performs its own re-matching process based on the imported component information (PURL or CPE) using its latest vulnerability database. This allows for the discovery of new vulnerabilities that were not detected at the time the SBOM was created.

Troubleshooting#

Here are the main causes and solutions when an SBOM file import fails.

If an Error Occurs During File Registration#

Cause Details / Solution
Missing generator tool information The SBOM does not contain information about the tool that generated it.
→ Regenerate the SBOM so that the tool information is output in metadata.tools (CycloneDX) or creationInfo.creators (SPDX). For a manually created SBOM, enter manual as the tool name (see Generation Tools).
OS information mismatch Registration will fail if "OS package information (e.g., rpm)" is included but the OS family and version cannot be determined (an application SBOM added to an SBOM server whose OS has been identified can be imported without OS information).
→ Regenerate the SBOM including OS information (CycloneDX: a component whose type is operating-system; SPDX: a package whose primaryPackagePurpose is OPERATING-SYSTEM), or add the OS information to the SBOM. To import the SBOM without its OS packages, enable "Ignore OS information" and try again.
Duplicate OS information A single SBOM contains information for multiple operating systems.
→ Correct it to a single-OS configuration.
Mixed package formats Different types of OS packages (e.g., apk and deb) are mixed.
→ Ensure that only one type is included.
Unsupported OS The detected OS is not supported by FutureVuls.
→ Check the Supported Environments. To import the SBOM without its OS packages, enable "Ignore OS information" and try again.
Unsupported format The file is in a format other than CycloneDX / SPDX, or an unsupported version (such as SPDX v3).
→ Output the file in a format and version listed in the Supported Environments.
File cannot be parsed The file is corrupted or does not follow the structure defined by the CycloneDX / SPDX specification.
→ Check that the file is not corrupted and that it conforms to the specification.
Duplicate application names The SBOM contains multiple applications with the same name.
→ Fix the SBOM so that application names are unique.
OS packages with the same name but different versions The SBOM contains an OS package with the same name as, but a different version from, an OS package in another SBOM on the server.
→ If you updated a package of the base, fix the server SBOM; if a package overlaps with an added one, first remove it from the application SBOM, and then import again.

If the Import Succeeds but Information Is Missing#

  • Missing OS/package information: Did you register it as an "application SBOM"? In application SBOMs, OS information is ignored, and OS packages are subject to detection only when the SBOM is added to an SBOM server.
  • Vulnerabilities are not displayed: Vulnerability information within the SBOM is not used; vulnerabilities will be detected by FutureVuls during the next scan. If you want the results reflected immediately, run a manual scan from the server details page. Also, components that have neither a PURL nor a CPE are not subject to automatic vulnerability detection, so manually assign a CPE or PURL to them.