Skip to main content

Ingest software bill of material (SBOM) into your catalog

The following example shows you how to create a sbomComponent blueprint that ingests all third party components in your sbom.json or sbom.xml file using both Port's GitHub file ingesting feature (for sbom.json) and a combination of Port's API and webhook functionality (for sbom.xml). You will then relate this blueprint to a sbomVulnerability blueprint, allowing you to map all the components affected by a security vulnerability.

To ingest the packages to Port, a port-app-config.yml file in the needed repository or organisation is used.

Prerequisites​

This guide assumes:

  • You have a Port account
  • You have installed Port's GitHub app in your organisation or in repositories you are interested in.

GitHub configuration​

To ingest GitHub objects, use one of the following methods:

Setting up the blueprint and mapping configuration​

Create the following blueprint definition and webhook configuration:

SBOM component blueprint
{
  "identifier": "sbomComponent",
  "description": "This blueprint represents an SBOM component in our software catalog",
  "title": "SBOM Component",
  "icon": "Package",
  "schema": {
    "properties": {
      "name": {
        "title": "Name",
        "type": "string"
      },
      "version": {
        "title": "Version",
        "type": "string"
      },
      "package_url": {
        "title": "Package URL",
        "type": "string"
      },
      "external_references": {
        "title": "External References",
        "type": "array"
      },
      "licenses": {
        "title": "Licenses",
        "type": "array"
      },
      "type": {
        "title": "Type",
        "type": "string",
        "default": "library",
        "enum": [
          "application",
          "framework",
          "library",
          "container",
          "platform",
          "operating-system",
          "device",
          "device-driver",
          "firmware",
          "file",
          "data",
          "machine-learning-model"
        ]
      },
      "software_product": {
        "title": "Software Product",
        "type": "string"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}
SBOM vulnerability blueprint
{
  "identifier": "sbomVulnerability",
  "description": "This blueprint represents an SBOM vulnerability in our software catalog",
  "title": "SBOM Vulnerability",
  "icon": "Package",
  "schema": {
    "properties": {
      "description": {
        "title": "Description",
        "type": "string"
      },
      "reference": {
        "title": "BOM Reference",
        "type": "string"
      },
      "recommendation": {
        "title": "Recommendation",
        "type": "string"
      },
      "ratings": {
        "title": "Ratings",
        "type": "array"
      },
      "source": {
        "title": "Source",
        "type": "string"
      },
      "published": {
        "title": "Published On",
        "type": "string",
        "format": "date-time"
      },
      "state": {
        "title": "State",
        "type": "string",
        "default": "exploitable",
        "enum": [
          "resolved",
          "resolved_with_pedigree",
          "exploitable",
          "in_triage",
          "false_positive",
          "not_affected"
        ],
        "enumColors": {
          "resolved": "green",
          "resolved_with_pedigree": "lightGray",
          "exploitable": "red",
          "in_triage": "yellow",
          "false_positive": "purple",
          "not_affected": "green"
        }
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {
    "components": {
      "title": "Components",
      "target": "sbomComponent",
      "required": false,
      "many": true
    }
  }
}
note

This documentation uses the CycloneDX SBOM standard. For more information on the schema structure, you can look here

Working with Port's API and Bash script​

Here are example snippets showing how to integrate Port's API and Webhook with your existing pipelines using Python and report SBOM entities from them:

To manage your GitHub integration configuration using Port:

  1. Go to the data sources page of your portal.
  2. Under Exporters, click on your desired GitHub organization.
  3. A window will open containing the default YAML configuration of your GitHub integration.
  4. Here you can modify the configuration to suit your needs, by adding/removing entries.
  5. When finished, click resync to apply any changes.

Using this method applies the configuration to all repositories that the GitHub app has permissions to.

When configuring the integration using Port, the YAML configuration is global, allowing you to specify mappings for multiple Port blueprints.

Important

When using Port's UI, the specified configuration will override any port-app-config.yml file in your GitHub repository/ies.

Put the following config in your port-app-config.yml file in your location of choice: repository level or organisation level.

SBOM mapping config (Click to expand)
resources:
  - kind: file
    selector:
      query: 'true'
      files:
        - path: '**/sbom.json'
    port:
      itemsToParse: .file.content.components
      entity:
        mappings:
          identifier: .item.bom-ref
          title: .item.name
          blueprint: '"sbomComponent"'
          properties:
            version: .item.version
            package_url: .item.purl
            type: .item.type
            external_references: .item.external_references
            licenses: .item.licenses
            software_product: .body.software_product + "-" + .body.software_version
          relations: {}

  - kind: file
    selector:
      query: 'true'
      files:
        - path: '**/sbom.json'
    port:
      itemsToParse: .file.content.vulnerabilities
      entity:
        mappings:
          identifier: .item.id
          title: .item.id
          blueprint: '"sbomVulnerability"'
          properties:
            description: .item.description
            reference: .item.reference
            recommendation: .item.recommendation
            ratings: .item.ratings
            source: .item.source
            published: .item.published
            state: .item.state
          relations: {}