Automate SBOM and vulnerability management via Helm API SDK

Overview

The Helm API allows users to efficiently manage SBOMs, assess vulnerabilities, and generate detailed reports. Currently available as a Python SDK (built on protobuf), the Helm API provides bindings and helper scripts to facilitate interactions with the API.

Key features

• Upload single or multiple SBOMs.

• Retrieve all vulnerabilities or filter to focus on CISA KEV vulnerabilities.

• Generate FDA SBOM reports or CycloneDX VEX reports.

• Identify unmatched SBOM components in your data.

Getting started

Request API access

1. Contact us to start using the Helm API. The Helm API is currently available as a Python SDK. It is in protobuf, with the API SDK providing Python bindings as well as helper bash scripts with which to call the SDK. The current API SDK version is 2.87.0.

2. If you need our C# SDK, it is currently in alpha mode. Contact us if you would like access to this.

Download Helm API SDK

1. Once you have received an email granting you access to the Helm API, click the Developers item in the sidebar.

2. Download the file below.

34KB

co_medcrypt_heimdall-tools_2.87.0_heimdall-tools-2.87.0-medcrypt-helm-api-sdk.tgz

Click to download the Helm API Python SDK, then verify the checksum

1. Before using the file, you should check that the MD5 checksum is b2568125fa42008ed03844276d36fb7d. If you're not sure how to do this, this source can be helpful.
2. Because our API documentation is hosted on Gitbook, you will see an interim page that Gitbook is verifying the safety of this file -- this page unfortunately does not go away, but your file will complete downloading successfully.

Authentication and setup

Once you have been granted access to the Helm API, you'll need to download our API SDK, then generate your API key to make calls to the API.

Step 1: Download the API SDK above

Download the file from the section above. There are four scripts for the Helm API:

• run_upload_sbom.sh

• run_unmatched_sbom_entries.sh

• run_vuln_list.sh

• run_product_version_report.sh

Step 2: Install SDK prerequisites

1. Install python3: pip3 install -r requirements.txt. This installs the required Python modules.

2. Check that all Python dependencies listed in the requirements.txt file are installed in your environment.

Step 3: Authenticate in Helm UI

1. Click the Developers option on the sidebar. This will display the Developers page.

2. In the Helm UI, you'll see an Email field which is the Helm email address that you have API access for. This will be your client_id that you will update in the scripts in the next steps.

3. In the Helm UI, click Generate API key. This will be your client_secret that you will update in the scripts in the next steps.

Step 4: Configure SDK scripts

After uncompressing this file, you will find a readme.txt document that contains the rest of the steps to execute the API.

1. From the command line, cd to the directory api/run.

2. Update the client_id and client_secret in these scripts: run_upload_sbom.sh, run_unmatched_sbom_entries.sh, run_vuln_list.sh, and run_product_version_report.sh.

3. Refer to the respective script section below, then update the corresponding parameters respectively.

Run scripts to automate SBOM and vulnerability management

Step 1: Run script to upload one or multiple SBOMs

You can upload one or multiple SBOMs using the run_upload_sbom.sh script. The following command-line parameters are available:

• --client_id: This is your API account username. In the Helm UI, this is the API user name.

• --client_secret: This is your API key that you will generate from the Helm UI.

• --sbom_files: This is the path to the SBOM file on your system.

• --product_name: This is the name of the product that you want to create a version for.

• --version: This is the product version that you want to create and upload an SBOM for.

• --createProdVers: If your product version doesn't already exist, you can create a new product version for a given SBOM product.

• --api_url: This is the API URL provided by Medcrypt.

• --file_type: This is the file type you'll be uploading. It only needs to be set if you are uploading a SPDX SBOM. If so, set to SPDX.

When you've set your parameters, run ./run_upload_sbom.sh.

Step 2: Run script to get all unmatched SBOM entries for product version

You can return all unmatched SBOM entries for a given product and version using the run_unmatched_sbom_entries.sh script. The following command-line parameters are available:

• --client_id: This is your API account username. In the Helm UI, this is the API user name.

• --client_secret: This is your API key that you will generate from the Helm UI.

• --product_name: This is the name of the product that you want to create a version for.

• --version: This is the product version that you want to create and upload an SBOM for.

• --api-url: This is the API URL provided by Medcrypt.

When you've set your parameters, run ./run_unmatched_sbom_entries.sh.

Step 3: Run script to get all vulnerabilities or CISA KEV vulnerabilities for product version

You can return all vulnerabilities or just CISA KEV vulnerabilities for a given product and version using the run_vuln_list.sh script. The following command-line parameters are available:

• --client_id: This is your API account username. In the Helm UI, this is the API user name.

• --client_secret: This is your API key that you will generate from the Helm UI.

• --product_name: This is the name of the product that you want to create a version for.

• --version: This is the product version that you want to create and upload an SBOM for.

• --api-url: This is the API URL provided by Medcrypt.

• --start_date: This is the start date at which to begin filtering vulnerabilities.

• --end_date: This is the end date at which to begin filtering vulnerabilities.

• --exploit_source: You can specify CISA_KEV to get just vulnerabilities on the CISA KEV list. If you don't specify this, you will get all of your vulnerabilities. The default value is UNDEFINED.

When you've set your parameters, run ./run_vuln_list.sh.

Step 4: Run script to generate product version report script

You can create and download an FDA SBOM or CycloneDX VEX report for a given product and version using the run_product_version_report.sh script. The following command-line parameters are available:

• --client_id: This is your API account username. In the Helm UI, this is the API user name.

• --client_secret: This is your API key that you will generate from the Helm UI.

• --product_name: This is the name of the product that you want to create a version for.

• --version: This is the product version that you want to create and upload an SBOM for.

• --api-url: This is the API URL provided by Medcrypt.

• --file_path: This is the path where you would like a generated report to be saved to.

• --report_type: Specify either FDA_EXCEL or CDX_VEX to generate your FDA SBOM in Excel format or CycloneDX VEX report.

When you've set your parameters, run ./run_product_version_report.sh.

API methods

The Helm API provides the following methods:

• listorganizations: Retrieves the organizations that the user has access to.

• listorganizationproducts: Retrieves the products a given organization has.

• listorganizationproductversions: Retrieves the product versions of a particular product for that organization.

• createorganizationproduct: Creates a new product under that organization with the provided product name. The user will have access to this product.

• createorganizationproductversions: Creates a new product version under a selected product with the provided version name.

• submitsbom:

  • Uploads an SBOM provided in the --sbom_files parameter.

  • Allows the user to upload an SBOM under an existing product and product version.

  • Users can create a new product, product version, and upload an SBOM under this new version.

• listunmatchedsbomentries: This lists all of your unmatched SBOM entries for a given SBOM product and version.

• listvulnerabilities: This lists all vulnerabilities for a given SBOM product and version. You can also filter this down via --exploit_source to CISA KEV vulnerabilities only, as detailed below.

• requestreport: This issues a request to generate a product version report. The report generation process is asynchronous, so this may take a moment.

• getreportrequeststate: This checks on the status of a requested report.

• getreportfile: Once a report request is completed (report_request_state=4), the report file will be available for download.