mend-import-sbom 23.11.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.

---

• Import SBOM
  • Supported Operating Systems
  • Prerequisites
  • Installation
  • Usage
  • 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
‑‑version		switch	No	Show current version 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	SBOM	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)
‑‑multilang	WS_MULTILANG	bool	No**	In case no SHA1 searching library by All known package types (default: true)
‑‑proxy	HTTP_PROXY	string	No	Proxy host including port, with or without protocol prefix and optionally credentials. Expected formats:myproxy.host.com:1234,http://myproxy.host.com:1234,http://user:[e-mail]:1234
‑‑proxyUsername	HTTP_PROXY_USERNAME	string	No	Proxy username, if needed and if not included in the proxy host.
‑‑proxyPassword	HTTP_PROXY_PASSWORD	string	No	Proxy password, if needed and if not included in the proxy host.

* --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.

** If --multilang is False script will try to find relevant package name in the Creator field. If such a candidate is found just it will be used for searching libraries.

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.

Note: If sha1 isn't provided for a particular library, the tool will attempt to search that library by its name and version in Mend's index, which will result in longer execution times.

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.

Note: If sha1 isn't provided for a particular library, the tool will attempt to search that library by its name and version in Mend's index, which will result in longer execution times.

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