[![Logo](https://resources.mend.io/mend-sig/logo/mend-dark-logo-horizontal.png)](https://www.mend.io/)
[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)
[![CI](https://github.com/whitesource-ps/ws-sbom-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/whitesource-ps/ws-sbom-generator/actions/workflows/ci.yml)
[![Python 3.8](https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Blue_Python_3.8_Shield_Badge.svg/76px-Blue_Python_3.8_Shield_Badge.svg.png)](https://www.python.org/downloads/release/python-380/)
[![GitHub release](https://img.shields.io/github/v/release/whitesource-ps/ws-sbom-generator)](https://github.com/whitesource-ps/ws-sbom-generator/releases/latest)
# Mend SBOM Generator
This tool generates SBOM reports in either [SPDX](https://spdx.org) or [CycloneDX](https://cyclonedx.org/) formats, for specified projects.
The tool can be executed either via [CLI](#sbom-generator-cli) or as a [Docker container](#sbom-generator-docker-container).
>**Note:** This tool utilizes a forked package of [spdx-tools](https://github.com/spdx/tools).
<br/>
# SBOM Generator CLI
## Supported Operating Systems
- **Linux (Bash):** CentOS, Debian, Ubuntu, RedHat
- **Windows (PowerShell):** 10, 2012, 2016
## Prerequisites
- Python 3.8 or later
- Mend user with admin permissions
>**Note:**
>The specified user (`-u, --userKey`) must be associated with a group assigned as either Organization Administrators (for generating report for all projects in the organization) or Product Administrators. For the latter, `--tokenType` must be specified (see [Command-Line Arguments](#command-line-arguments)).
## Installation
1. Install the PyPI package `ws-sbom-generator`
```
pip install ws-sbom-generator
```
> **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.
1. Update the [creation info](https://spdx.github.io/spdx-spec/v2-draft/document-creation-information/#68-creator-field) as needed in the [resource/sbom_extra.json](./ws_sbom_generator/resources/sbom_extra.json) file:
```json
{
"namespace": "http://CreatorWebsite/pathToSpdx/DocumentName-UUID",
"org_email": "org@domain.com",
"person": "First Last",
"person_email": "first.last@domain.com"
}
```
## Usage
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type $FORMAT --out $HOME/reports --extra resources/sbom_extra.json
```
### Command-Line Arguments
| Parameter | Type | Required | Description |
|:----------|:----:|:--------:|:------------|
| **‑h, ‑‑help** | switch | No | Show help and exit |
| **‑a, ‑‑wsUrl** | string | Yes | Mend server URL |
| **‑u, ‑‑userKey** | string | Yes | Mend User Key |
| **‑k, ‑‑token** | string | Yes | Mend API Key or Product token |
| **‑y, ‑‑tokenType** | string | No* | [`organization`\|`product`*] (default: `organization`) |
| **‑t, ‑‑type** | string | No* | Report format [`json`\|`tv`\|`rdf`\|`xml`\|`yaml`\|`cdx`\*\|`all`\*] (default: `tv`) |
| **‑s, ‑‑scope** | string | No | Product or Project token to generate the report(s) for. When specifying a Product token, one report will be generated for each project under that product. If not specified, one report will be generated for each project in your organization. |
| **‑o, ‑‑out** | string | No | Output directory (default: `$PWD`) |
| **‑on, ‑‑outfile** | string | No* | Output file name* (default: `Mend {PROJECT_NAME} SBOM report-{FORMAT}`) |
| **‑lt, ‑‑licensetext** | bool | No | Include full license text for all libraries* (default: `False`) |
| **‑th, ‑‑threads** | int | No | Number of threads to run in parallel for report generation (default: `10`) |
| **‑e, ‑‑extra** | string | No* | Path to a json file containing the [creation info](https://spdx.github.io/spdx-spec/v2-draft/document-creation-information/#68-creator-field) to be included in the report (default: `$PWD/resources/sbom_extra.json` |
>**Notes:**
>\* Token type (`--tokenType product`) is required in case the specified `userKey` is associated with a group with Product Administrators permissions.
>\* Report type (`--type`) `cdx` will generate a JSON file in [CycloneDX v1.4](https://cyclonedx.org/docs/1.4/json/) format.
>\* Report type (`--type`) `all` will generate one file in each format for each specified project.
>\* Output file name (`--outfile`) is only supported for a single project scope.
>\* Full license texts will be taken by default from the [SPDX License List](https://spdx.org/licenses/). If a given license does not exist there, the tool will attempt to take it from Mend's database.
>\* By default, the tool will use the placeholders in the [resource/sbom_extra.json](./ws_sbom_generator/resources/sbom_extra.json) file.
### Execution Examples
Generating `tv` formatted SBOM report for a specific project
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PROJECTTOKEN --out $HOME/reports --extra sbom_extra.json
```
Generating `tv` formatted SBOM report for all projects of a specified product
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PRODUCTTOKEN --out $HOME/reports --extra sbom_extra.json
```
Generating `json` formatted SBOM report for all projects in the organization
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type json --out $HOME/reports
```
Generating `json` formatted SBOM report for all projects in the organization, including full license text
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type json --out $HOME/reports --licensetext True
```
Generating `xml` formatted SBOM report for a single project (executed by a product administrator)
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_PRODUCTTOKEN --tokenType product --scope $WS_PROJECTTOKEN --type xml --out $HOME/reports --extra sbom_extra.json
```
Generating `json` formatted SBOM report for a single project, specifying file name
```shell
ws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PROJECTTOKEN --type json --out $HOME/reports --extra sbom_extra.json --outfile my-project-sbom.json
```
<br/>
# SBOM Generator Docker Container
## Supported Operating Systems
- **Linux:** CentOS, Debian, Ubuntu, RedHat
- **Windows:** 10, 2012, 2016
## Prerequisites
- Docker version 20 or later
- Mend user with admin permissions
>**Note:**
>The specified user (`-u, --userKey`) must be associated with a group assigned as either Organization Administrators (for generating report for all projects in the organization) or Product Administrators. For the latter, `--tokenType` must be specified (see [Command-Line Arguments](#command-line-arguments)).
## Installation
```shell
docker pull whitesourcetools/ws-sbom-generator:latest
```
## Usage
```shell
docker run --name ws-sbom-generator \
-v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom-generator/resources \
-v $HOME/reports:/opt/ws-sbom-generator/sbom-generator/output \
-e WS_URL=$WS_WSS_URL \
-e WS_USER_KEY=$WS_USERKEY \
-e WS_TOKEN=$WS_APIKEY \
-e WS_REPORT_TYPE=<REPORT_TYPE> \
whitesourcetools/ws-sbom-generator
```
### Execution Examples
Running as organization administrator, generating `json` formatted SBOM reports for all projects, default extra args
```shell
docker run --name ws-sbom-generator \
-v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \
-v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \
-e WS_URL=$WS_WSS_URL \
-e WS_USER_KEY=$WS_USERKEY \
-e WS_TOKEN=$WS_APIKEY \
-e WS_REPORT_TYPE=json
whitesourcetools/ws-sbom-generator
```
Running as organization administrator, generating `tv` formatted SBOM report for a single project, default extra args
```shell
docker run --name ws-sbom-generator \
-v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \
-v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \
-e WS_URL=$WS_WSS_URL \
-e WS_USER_KEY=$WS_USERKEY \
-e WS_TOKEN=$WS_APIKEY \
-e WS_SCOPE_TOKEN=<WS_PROJECT_TOKEN> \
whitesourcetools/ws-sbom-generator
```
Running as a product administrator, generating `rdf` formatted SBOM report for a single project, default extra args
```shell
docker run --name ws-sbom-generator \
-v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \
-v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \
-e WS_URL=$WS_WSS_URL \
-e WS_USER_KEY=$WS_USERKEY \
-e WS_TOKEN=$WS_PRODUCTTOKEN \
-e WS_TOKEN_TYPE=product
-e WS_SCOPE_TOKEN=$WS_PROJECTTOKEN \
whitesourcetools/ws-sbom-generator
```
Raw data
{
"_id": null,
"home_page": "https://github.com/whitesource-ps/ws-sbom-generator",
"name": "ws-sbom-generator",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "WhiteSource Professional Services",
"author_email": "ps@whitesourcesoftware.com",
"download_url": "",
"platform": null,
"description": "[![Logo](https://resources.mend.io/mend-sig/logo/mend-dark-logo-horizontal.png)](https://www.mend.io/) \n\n[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://opensource.org/licenses/Apache-2.0)\n[![CI](https://github.com/whitesource-ps/ws-sbom-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/whitesource-ps/ws-sbom-generator/actions/workflows/ci.yml)\n[![Python 3.8](https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Blue_Python_3.8_Shield_Badge.svg/76px-Blue_Python_3.8_Shield_Badge.svg.png)](https://www.python.org/downloads/release/python-380/)\n[![GitHub release](https://img.shields.io/github/v/release/whitesource-ps/ws-sbom-generator)](https://github.com/whitesource-ps/ws-sbom-generator/releases/latest) \n\n# Mend SBOM Generator\nThis tool generates SBOM reports in either [SPDX](https://spdx.org) or [CycloneDX](https://cyclonedx.org/) formats, for specified projects. \n\nThe tool can be executed either via [CLI](#sbom-generator-cli) or as a [Docker container](#sbom-generator-docker-container). \n\n>**Note:** This tool utilizes a forked package of [spdx-tools](https://github.com/spdx/tools). \n\n<br/>\n\n# SBOM Generator CLI\n\n## Supported Operating Systems\n- **Linux (Bash):**\tCentOS, Debian, Ubuntu, RedHat\n- **Windows (PowerShell):**\t10, 2012, 2016\n\n## Prerequisites\n- Python 3.8 or later\n- Mend user with admin permissions\n\n>**Note:** \n>The specified user (`-u, --userKey`) must be associated with a group assigned as either Organization Administrators (for generating report for all projects in the organization) or Product Administrators. For the latter, `--tokenType` must be specified (see [Command-Line Arguments](#command-line-arguments)). \n\n## Installation\n1. Install the PyPI package `ws-sbom-generator`\n ```\n pip install ws-sbom-generator\n ```\n > **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. \n\n1. Update the [creation info](https://spdx.github.io/spdx-spec/v2-draft/document-creation-information/#68-creator-field) as needed in the [resource/sbom_extra.json](./ws_sbom_generator/resources/sbom_extra.json) file:\n ```json\n {\n \"namespace\": \"http://CreatorWebsite/pathToSpdx/DocumentName-UUID\",\n \"org_email\": \"org@domain.com\",\n \"person\": \"First Last\",\n \"person_email\": \"first.last@domain.com\"\n }\n ```\n\n## Usage\n\n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type $FORMAT --out $HOME/reports --extra resources/sbom_extra.json\n```\n\n### Command-Line Arguments\n\n| Parameter | Type | Required | Description |\n|:----------|:----:|:--------:|:------------|\n| **‑h, ‑‑help** | switch | No | Show help and exit |\n| **‑a, ‑‑wsUrl** | string | Yes | Mend server URL |\n| **‑u, ‑‑userKey** | string | Yes | Mend User Key |\n| **‑k, ‑‑token** | string | Yes | Mend API Key or Product token |\n| **‑y, ‑‑tokenType** | string | No* | [`organization`\\|`product`*] (default: `organization`) |\n| **‑t, ‑‑type** | string | No* | Report format [`json`\\|`tv`\\|`rdf`\\|`xml`\\|`yaml`\\|`cdx`\\*\\|`all`\\*] (default: `tv`) |\n| **‑s, ‑‑scope** | string | No | Product or Project token to generate the report(s) for. When specifying a Product token, one report will be generated for each project under that product. If not specified, one report will be generated for each project in your organization. |\n| **‑o, ‑‑out** | string | No | Output directory (default: `$PWD`) |\n| **‑on, ‑‑outfile** | string | No* | Output file name* (default: `Mend {PROJECT_NAME} SBOM report-{FORMAT}`) |\n| **‑lt, ‑‑licensetext** | bool | No | Include full license text for all libraries* (default: `False`) |\n| **‑th, ‑‑threads** | int | No | Number of threads to run in parallel for report generation (default: `10`) |\n| **‑e, ‑‑extra** | string | No* | Path to a json file containing the [creation info](https://spdx.github.io/spdx-spec/v2-draft/document-creation-information/#68-creator-field) to be included in the report (default: `$PWD/resources/sbom_extra.json` |\n\n>**Notes:** \n>\\* Token type (`--tokenType product`) is required in case the specified `userKey` is associated with a group with Product Administrators permissions. \n>\\* Report type (`--type`) `cdx` will generate a JSON file in [CycloneDX v1.4](https://cyclonedx.org/docs/1.4/json/) format. \n>\\* Report type (`--type`) `all` will generate one file in each format for each specified project. \n>\\* Output file name (`--outfile`) is only supported for a single project scope. \n>\\* Full license texts will be taken by default from the [SPDX License List](https://spdx.org/licenses/). If a given license does not exist there, the tool will attempt to take it from Mend's database. \n>\\* By default, the tool will use the placeholders in the [resource/sbom_extra.json](./ws_sbom_generator/resources/sbom_extra.json) file. \n\n### Execution Examples\n\nGenerating `tv` formatted SBOM report for a specific project \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PROJECTTOKEN --out $HOME/reports --extra sbom_extra.json\n```\n\nGenerating `tv` formatted SBOM report for all projects of a specified product \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PRODUCTTOKEN --out $HOME/reports --extra sbom_extra.json\n```\n\nGenerating `json` formatted SBOM report for all projects in the organization \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type json --out $HOME/reports\n```\n\nGenerating `json` formatted SBOM report for all projects in the organization, including full license text \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --type json --out $HOME/reports --licensetext True\n```\n\nGenerating `xml` formatted SBOM report for a single project (executed by a product administrator) \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_PRODUCTTOKEN --tokenType product --scope $WS_PROJECTTOKEN --type xml --out $HOME/reports --extra sbom_extra.json\n```\n\nGenerating `json` formatted SBOM report for a single project, specifying file name \n```shell\nws_sbom_generator --wsUrl $WS_WSS_URL --userKey $WS_USERKEY --token $WS_APIKEY --scope $WS_PROJECTTOKEN --type json --out $HOME/reports --extra sbom_extra.json --outfile my-project-sbom.json\n```\n\n<br/>\n\n# SBOM Generator Docker Container\n\n## Supported Operating Systems\n- **Linux:**\tCentOS, Debian, Ubuntu, RedHat\n- **Windows:**\t10, 2012, 2016\n\n## Prerequisites\n- Docker version 20 or later\n- Mend user with admin permissions\n\n>**Note:** \n>The specified user (`-u, --userKey`) must be associated with a group assigned as either Organization Administrators (for generating report for all projects in the organization) or Product Administrators. For the latter, `--tokenType` must be specified (see [Command-Line Arguments](#command-line-arguments)). \n\n## Installation\n\n```shell\ndocker pull whitesourcetools/ws-sbom-generator:latest \n ```\n\n## Usage\n\n```shell\ndocker run --name ws-sbom-generator \\ \n -v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom-generator/resources \\ \n -v $HOME/reports:/opt/ws-sbom-generator/sbom-generator/output \\\n -e WS_URL=$WS_WSS_URL \\\n -e WS_USER_KEY=$WS_USERKEY \\ \n -e WS_TOKEN=$WS_APIKEY \\\n -e WS_REPORT_TYPE=<REPORT_TYPE> \\\n whitesourcetools/ws-sbom-generator \n```\n\n### Execution Examples\n\nRunning as organization administrator, generating `json` formatted SBOM reports for all projects, default extra args \n\n```shell\ndocker run --name ws-sbom-generator \\ \n -v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \\ \n -v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \\\n -e WS_URL=$WS_WSS_URL \\\n -e WS_USER_KEY=$WS_USERKEY \\ \n -e WS_TOKEN=$WS_APIKEY \\\n -e WS_REPORT_TYPE=json\n whitesourcetools/ws-sbom-generator\n```\n\nRunning as organization administrator, generating `tv` formatted SBOM report for a single project, default extra args \n\n```shell\ndocker run --name ws-sbom-generator \\ \n -v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \\\n -v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \\\n -e WS_URL=$WS_WSS_URL \\\n -e WS_USER_KEY=$WS_USERKEY \\\n -e WS_TOKEN=$WS_APIKEY \\\n -e WS_SCOPE_TOKEN=<WS_PROJECT_TOKEN> \\\n whitesourcetools/ws-sbom-generator\n```\n\nRunning as a product administrator, generating `rdf` formatted SBOM report for a single project, default extra args \n\n```shell\ndocker run --name ws-sbom-generator \\ \n -v $HOME/ws-sbom-generator/resources:/opt/ws-sbom-generator/sbom_generator/resources \\\n -v $HOME/reports:/opt/ws-sbom-generator/sbom_generator/output \\\n -e WS_URL=$WS_WSS_URL \\\n -e WS_USER_KEY=$WS_USERKEY \\\n -e WS_TOKEN=$WS_PRODUCTTOKEN \\\n -e WS_TOKEN_TYPE=product\n -e WS_SCOPE_TOKEN=$WS_PROJECTTOKEN \\\n whitesourcetools/ws-sbom-generator\n```\n\n\n",
"bugtrack_url": null,
"license": "LICENSE.txt",
"summary": "WS SBOM Generator in SPDX format",
"version": "23.1.1.3",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8121b7e80179138d46cc851c36c02f037ed1ed8922ffec739fd26a497665b05e",
"md5": "6a9eecb1c6e315fcd6d11f2fb31a29d7",
"sha256": "435715ca4f8f7461cd8bf6180acc3973cb147c3688c800dcc83286affcdf645d"
},
"downloads": -1,
"filename": "ws_sbom_generator-23.1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a9eecb1c6e315fcd6d11f2fb31a29d7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19498,
"upload_time": "2023-01-03T19:12:42",
"upload_time_iso_8601": "2023-01-03T19:12:42.258672Z",
"url": "https://files.pythonhosted.org/packages/81/21/b7e80179138d46cc851c36c02f037ed1ed8922ffec739fd26a497665b05e/ws_sbom_generator-23.1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-03 19:12:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "whitesource-ps",
"github_project": "ws-sbom-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "ws-spdx-tools",
"specs": [
[
"==",
"0.7.0a3.post7"
]
]
},
{
"name": "ws-sdk",
"specs": [
[
"==",
"22.12.1.1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.22.3"
]
]
}
],
"lcname": "ws-sbom-generator"
}