mend-import-sbom 23.3.1

Import SPDX or CSV SBOM into Mend

Import SBOM

A CLI tool that imports a project inventory into Mend from a SBOM report in the SPDX format or CSV format.

The tool can either upload data directly to Mend, or alternatively, create a Mend Offline Request file that can be uploaded separately using one of the following methods:

• Using the Mend Unified Agent (see Uploading an Offline Request File)
• Via Mend's UI (Admin >> Upload Update Request)
• Using Mend's API (see Uploading Update Requests via the Mend API)

The tool supports input files in either JSON or CSV formats.

---

• Supported Operating Systems
• Prerequisites
• Installation
• Usage
• Configuration Parameters
• Importing SPDX SBOM (JSON)
  • Imported File Structure
  • Execution Examples
• Importing CSV SBOM
  • Imported File Structure
  • Execution Examples

---

Supported Operating Systems

• Linux (Bash): CentOS, Debian, Ubuntu
• Windows (PowerShell): 10, 2012, 2016

Prerequisites

• Python 3.9+
• Mend user with admin permissions

Installation

$ pip install mend-import-sbom

Note: Depending on whether the package was installed as a root user or not, you need to make sure the package installation location was added to the $PATH environment variable.

Usage

Using command-line arguments only:

import_sbom --user-key WS_USERKEY --api-key WS_APIKEY --url $WS_WSS_URL --input $SBOM_FILE_PATH --scope "ProductName//ProjectName" --dir $OUTPUT_DIRECTORY

Using environment variables:

export WS_USERKEY=xxxxxxxxxxx
export WS_APIKEY=xxxxxxxxxxx
export WS_WSS_URL=https://saas.mend.io

import_sbom --input $SBOM_FILE_PATH --scope "ProductName//ProjectName"

Note: Either form is accepted. For the rest of the examples, the latter form would be used

Configuration Parameters

Note: Parameters can be specified as either command-line arguments, environment variables, or a combination of both.

Command-line arguments take precedence over environment variables.

CLI argument	Env. Variable	Type	Required	Description
‑‑help		switch	No	Show help and exit
‑‑user-key	WS_USERKEY	string	Yes	Mend User Key
‑‑api-key	WS_APIKEY	string	Yes	Mend API Key
‑‑url	WS_WSS_URL	string	Yes	Mend Server URL
‑‑input		string	Yes	SBOM report file to import (*.json or *.csv)
‑‑scope	WS_SCOPE	string	No*	Product and Project names to create/update. Expected format: "PRODUCT//PROJECT"
‑‑updateType	WS_UPDATETYPE	string	No	APPEND or OVERRIDE results when importing into an existing project (default: OVERRIDE)
‑‑dir		string	No	Output directory for the update-request.txt file** in Offline mode (default: $PWD)
‑‑offline	WS_OFFLINE	bool	No	Create offline update request file without uploading to Mend (default: false)

* --scope specifies the hierarchy (full or partial) for uploading the SBOM report using product and project identifiers.
Both the product and project can be identified by either names (for creating a new one) or token (for updating an existing one).

• --scope "ProductName//ProjectName" would specify both the product name and project name to create/update.
• --scope "ProjectName" would specify only the project name, and the product name would default to Mend-Imports.
• --scope "ProjectToken" would specify the token of an existing project, and the product name would default to that project's parent product. When specifying a project token, you cannot specify a product name/token.
• If --scope isn't specified, the project name will be taken from the SBOM's name property (for *.json SPDX) or its parent directory (for *.csv).

** See more details about the update-request.txt file and Offline mode in Mend's documentation.

Importing SPDX SBOM (JSON)

Imported File Structure

The SPDX document must correspond to the Composition of an SPDX document specification.

The following table describes the set of properties for each imported library:

Property	Required	Description
name	No	File Name
downloadLocation	No	Download Location
licenseConcluded	No	License Concluded
licenseInfoFromFiles	No	License Info
licenseDeclared	No	License Declared
copyrightText	No	Copyright Text
versionInfo	Yes*	Version Info
packageFileName	Yes*	Package Name
supplier	No	Supplier
originator	No	Originator
sha1	Yes*	SHA1
homepage	No	Home Page

* Each library requires either sha1 or the packageFileName and versionInfo pair.

Execution Examples

Note: In the following examples, $WS_USERKEY, $WS_APIKEY and $WS_WSS_URL are assumed to have been exported as environment variables.

Import SPDX SBOM into a new Mend project

$ import_sbom --scope "$WS_PRODUCTNAME//$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/$WS_PROJECTNAME-sbom.json

Convert SPDX SBOM to an offline update request file for creating a new Mend project under a specific product

$ import_sbom --scope "$WS_PRODUCTNAME//$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/my-project-sbom.json --offline True

Convert SPDX SBOM to an offline update request file for overriding an existing Mend project

$ import_sbom --scope "$WS_PRODUCTNAME//$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/my-project-sbom.json --offline True

$ import_sbom --scope $WS_PROJECTTOKEN --dir $HOME/reports --input $HOME/reports/my-project-sbom.json --offline True

Convert SPDX SBOM to an offline update request file for appending to an existing Mend project

$ import_sbom --scope "$WS_PRODUCTNAME//$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/my-project-sbom.json --offline True --updateType APPEND

$ import_sbom --scope $WS_PROJECTTOKEN --dir $HOME/reports --input $HOME/reports/my-project-sbom.json --offline True --updateType APPEND

Importing CSV SBOM

Imported File Structure

Download CSV Template

Header	Required	Reference
name	No	File Name
downloadLocation	No	Download Location
licenseConcluded	No	License Concluded
licenseInfoFromFiles	No	License Info
licenseDeclared	No	License Declared
copyrightText	No	Copyright Text
versionInfo	Yes*	Version Info
packageFileName	Yes*	Package Name
supplier	No	Supplier
originator	No	Originator
sha1	Yes*	SHA1
homepage	No	Home Page

* Each library requires either sha1 or the packageFileName and versionInfo pair. Other fields can remain empty.

Execution Examples

Note: In the following examples, $WS_USERKEY, $WS_APIKEY and $WS_WSS_URL are assumed to have been exported as environment variables.

Import CSV SBOM into a new Mend project under the default product (Mend-Imports)

$ import_sbom --scope "$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/$WS_PROJECTNAME.csv

Import CSV SBOM, appending to an existing Mend project

$ import_sbom --scope "$WS_PRODUCTNAME//$WS_PROJECTNAME" --dir $HOME/reports --input $HOME/reports/$WS_PROJECTNAME.csv --updateType APPEND 

$ import_sbom --scope $WS_PROJECTTOKEN --dir $HOME/reports --input $HOME/reports/$WS_PROJECTNAME.csv --updateType APPEND