SBOM based discovery

Overview

SBOM stands for Software Bill Of Materials. SBOM-based discovery mode in twigs allows you to ingest assets specified in SBOM artifact to ThreatWorx. Currently supported SBOM standards and formats are as follows:

  • CycloneDX – JSON
  • SPDX, SPDX Lite – tagvalue
  • ThreatWorx (proprietary) – JSON, CSV

Pre-requisites

You need to have SBOM artifact. There are many ways to create an SBOM. For e.g. Github now allows you to create a CycloneDX for all code repositories. ThreatWorx also supports its own SBOM standard which is

Steps

The steps involved to discover assets from SBOM artifact are as below:

  • Open a new shell / terminal.
  • Check that twigs is installed and running properly by running below command:

twigs sbom -h

  • You can run the command as below:

twigs sbom [-h] --input INPUT [--standard {cyclonedx,spdx,threatworx}] [--format {json,tagvalue,csv}] [--assetid ASSETID] [--assetname ASSETNAME]

  • where INPUT is the path to the SBOM document
  • After discovery is complete, you can login into ThreatWorx console to view the newly discovery assets.

Depending on the type of SBOM, one or more assets may be created in the console. These will be tracked for new and updated vulnerabilities and threats continuously just like any other assets discovered using twigs. The SBOM artifact will be archived in the ThreatWorx console and will be available through the SBOM dashboard for audit. Uploading the SBOM is possible manually in the ThreatWorx console through the SBOM dashboard.

Examples

$ twigs sbom --input ~/my_repo_cyclonedx_sbom.json --standard cyclonedx --format json --assetid my_repo --assetname my_repo

Ingest CycloneDx JSON SBOM as an asset

$ twigs sbom --input ~/linux_tw_sbom.json --standard threatworx --format json

Ingest ThreatWorx JSON SBOM as an asset. Note there is no need to provide “assetid” nor “assetname” as the SBOM already contains those fields.

ThreatWorx SBOM

The ThreatWorx SBOM is designed to represent the typical enterprise attack surface in more detail than other SBOM standards. For e.g. a typical ThreatWorx SBOM for Windows endpoint will capture KBs or patch details in addition to the installed products and services. This allows for ThreatWorx to perform a more accurate assessment of the endpoint than possible with other SBOM standards.

Other unique findings included in the ThreatWorx SBOM are:

  • SCA / license information for open source components
  • CSPM, K8S, server and other misconfigurations
  • SAST, DAST, IaC code secrets
  • Multiple assets, (endpoints, cloud workloads etc.) included in one SBOM

These provide a more complete view of the attack surface than what is included in CycloneDX or SPDX.

How to generate a ThreatWorx SBOM

Any discovery using twigs can be converted to an ThreatWorx JSON SBOM using the common switch.

For e.g. an open source repository can be discovered as a ThreatWorx SBOM as follows:

twigs --sbom /path/to/my/sbom --repo <mygitrepo> --sast --secrets_scan

ThreatWorx SBOM CSV format

twigs supports ingesting assets from CSV SBOMs. CSV files contain “comma-separated values” records consisting of multiple columns. The format of CSV file for asset ingestion has following columns in that order:

  • Asset Id – This is a required field and specifies the Identifier for the asset
  • Asset Name – This is a required field and specifies the Name for the asset
  • Asset Type – This is a required field and specifies the Type of the asset. Typical asset types are as below:
    • Windows
    • Red Hat
    • Ubuntu
    • CentOS
    • Debian
  • Owner – This is an optional field and can be empty. This field contains the handle of the user who will own the asset. If empty, handle of the user running twigs will be set as owner for the asset.
  • Tags – This is a required field and specifies the Tags associated with the asset. There can be multiple tags which are separated by semi-colon (“;”). These tags if provided will help in more accurate assessment of vulnerabilities for the assets in the SBOM. Here are some of the supported tags:
    • OS_RELEASE – It contains the complete PRETTY_NAME for Linux flavors. For Windows it is OS name. For example:
      •  OS_RELEASE:Red Hat Enterprise Linux 8.1 (Ootpa)
      • OS_RELEASE:Microsoft Windows Server 2016 Datacenter
    • OS_VERSION – This is required for Windows assets and contains the OS version details (including Service Pack information). For example:
      •  OS_VERSION:6.1.7601 Service Pack 1 Build 7601
      • OS_VERSION:10.0.14393 N/A Build 14393
    • OS_RELEASE_ID – This is required for Windows assets, mainly newer versions of Windows which include a Release ID. For example:
      • OS_RELEASE_ID:1607
      • OS_RELEASE_ID:1809
    • OS_ARCH – This is required for Windows assets and specifies the machine architecture. For example:
      • OS_ARCH:64-bit x64-based PC
  • Products – This is a required field and specifies the list of products for the asset. There can be multiple products in the list which are separated by semi-colon (“;”)
  • Patches – This is a required field for Windows assets. Each patch is signaled as “KB” number such as “KB43215”. Multiple patches can be specified separated by semi-colon (“;”)

The CSV file starts with CSV header record as show below: 

Asset Id,Asset Name,Asset Type,Owner,Tags,Products,Patches