Generating a Concert-defined SBOM

The IBM® Concert platform supports three custom, Concert-defined SBOM schemas required to generate a holistic view of your global application topology. The ConcertDef schemas contain a subset of application component-type extensions, including a properties object with details about the change to the CI/CD pipeline.

The ConcertDef schema is a derivative of CycloneDX SBOM schema version 1.5. Concert-defined SBOMs can be generated automatically by using custom scripts in CI/CD tools, such as Jenkins or ArgoCD. Alternatively, you can create and upload them manually for quick testing and data ingestion. It is highly recommended that you automate SBOM file generation by integrating with your CI/CD pipeline tools to ensure the consistency, accuracy, and scalability of your application data.

Concert-defined SBOM files adhere to three distinct schemas, each serving a specific purpose in the software development lifecycle: application (pre-build), build, and deploy.

Warning: When you replace an SBOM file for an existing application, the image (name of the Docker image) must be the same. Only the digest should be unique.

Schema #1: Application SBOM

The application definition SBOM focuses on the static definition of the application's components, libraries, and dependencies. It provides a high-level, theoretical list of these components and their metadata. This SBOM is typically used in the pre-build phase to outline the intended structure of the application, however it can be generated at any time during the lifecycle for ingestion into the Concert platform. One application definition SBOM is required for every application in your environment.

Refer to the example below or view a sample application SBOM file in ConcertDef format on the Concert GitHub repository.

Note: Generate an application definition SBOM file for every application in your environment.

{
  "bomFormat": "ConcertDef",
  "specVersion": "1.0.2",
  "metadata": {
    "timestamp": "2024-12-06T15:23:57Z",
    "type": "application",
    "component": {
      "name": "concert-sample-devsecops",
      "version": "1.0.0"
    },
    "business": {
      "name": "Acme Inc.",
      "units": [
        {
          "name": "Unit 1",
          "email": "myemail@acme.com",
          "phone": "(123) 123-1234"
        }
      ]
    }
  },
  "components": [
    {
      "bom-ref": "build:concert-sample-devsecops",
      "type": "build",
      "name": "concert-sample-devsecops",
      "version": "1.0.0",
      "components": [
        {
          "bom-ref": "container:us.icr.io/icr4mcc/concert-sample-devsecops",
          "type": "container",
          "name": "us.icr.io/icr4mcc/concert-sample-devsecops"
        },
        {
          "bom-ref": "repository:coderepo:github:concert-sample-devsecops",
          "type": "code",
          "name": "concert-sample-devsecops",
          "purl": "https://github.ibm.com/concert/concert-sample-devsecops"
        }
      ]
    }
  ],
  "environments": [
    {
      "bom-ref": "environment:dev",
      "type": "environment",
      "name": "dev"
    },
    {
      "bom-ref": "environment:stage",
      "type": "environment",
      "name": "stage"
    },
    {
      "bom-ref": "environment:prod",
      "type": "environment",
      "name": "prod"
    }
  ],
  "services": [
    {
      "bom-ref": "appapi:concert-sample-devsecops",
      "name": "concert-sample-devsecops",
      "endpoints": [
        "/"
      ]
    }
  ],
  "dependencies": [
    {
      "ref": "build:concert-sample-devsecops",
      "dependsOn": [
        "appapi:concert-sample-devsecops"
      ]
    }
  ],
  "properties": [
    {
      "name": "application_criticality",
      "value": "3"
    }
  ]
}

Schema #2: Build SBOM

The build inventory SBOM captures a real-time inventory of components that are used during the build process. It offers a detailed, practical list of components and build-time dependencies. This SBOM reflects the actual components assembled into the final product during the build phase. There may be many build inventory SBOMs depending on the number of micro-services in your application.

Note: Generate a build SBOM file for each micro-service in your applications.

Refer to the example below or view sample build SBOM files in ConcertDef format on the Concert GitHub repository.

{
  "bomFormat": "ConcertDef",
  "specVersion": "1.0.2",
  "metadata": {
    "timestamp": "2024-12-06T15:23:57Z",
    "type": "build",
    "component": {
      "name": "concert-sample-devsecops",
      "version": "1.0.0",
      "build-number": "204"
    }
  },
  "components": [
    {
      "type": "container",
      "name": "us.icr.io/icr4mcc/concert-sample-devsecops",
      "uri": "us.icr.io/icr4mcc/concert-sample-devsecops:204-main-a0a7e8eab28b5d3ca7abc4014080cda6309b68fa@sha256:dbd24de377d42d4e4d3a24004d5fb8664d87c74ec30ca9d26ed72cee1e7bee57",
      "tag": "204-main-a0a7e8eab28b5d3ca7abc4014080cda6309b68fa",
      "digest": "sha256:dbd24de377d42d4e4d3a24004d5fb8664d87c74ec30ca9d26ed72cee1e7bee57"
    },
    {
      "type": "code",
      "name": "concert-sample-devsecops",
      "purl": "https://github.ibm.com/concert/concert-sample-devsecops",
      "cyclonedx-bom-link": "urn:uuid:ddec31c8-caae-4bf6-807a-bbb6e0bc3f1c/1",
      "commit_sha": "a0a7e8eab28b5d3ca7abc4014080cda6309b68fa",
      "branch": "main"
    }
  ]
}

Schema #3: Deploy SBOM

The deploy inventory SBOM provides a comprehensive view of components in the deployed environment. It includes a detailed list of runtime dependencies, environment-specific configurations, and any post-build modifications. This SBOM documents the final state of the software in production during the deployment phase.

Note: The number of deploy SBOM files you must generate depends on the frequency at which the micro-services are deployed to your environments.

Refer to the example below or view sample deploy SBOM files in ConcertDef format on the Concert GitHub repository.

{
  "bomFormat": "ConcertDef",
  "specVersion": "1.0.2",
  "metadata": {
    "timestamp": "2024-12-06T17:41:43Z",
    "type": "deploy",
    "environment": "prod",
    "component": {
      "deploy-number": "190",
      "change-request-url": "https://us-south.git.cloud.ibm.com/rong/concert-sample-devsecops-change/issues/101",
      "name": "concert-sample-devsecops",
      "version": "1.0.0"
    }
  },
  "components": [
    {
      "type": "code",
      "name": "concert-sample-devsecops-deployment",
      "purl": "https://github.ibm.com/rong/concert-sample-devsecops-deployment",
      "commit_sha": "c637635161906c6c7c4bfa104d83f98c176e9892",
      "branch": "master"
    }
  ],
  "runtime-components": [
    {
      "bom-ref": "runtime-components:kubernetes:roks:cjsal64w0g8rl335fso0",
      "type": "kubernetes",
      "name": "cjsal64w0g8rl335fso0",
      "api-server": "https://172.20.0.1:2040",
      "properties": [
        {
          "name": "platform",
          "value": "ibmcloud"
        },
        {
          "name": "cluster_platform",
          "value": "roks"
        },
        {
          "name": "cluster_id",
          "value": "cjsal64w0g8rl335fso0"
        },
        {
          "name": "cluster_region",
          "value": "us-east"
        },
        {
          "name": "cluster_name",
          "value": "roks1"
        }
      ],
      "components": [
        {
          "type": "namespace",
          "name": "cd4concert",
          "components": [
            {
              "bom-ref": "container:us.icr.io/icr4mcc/concert-sample-devsecops",
              "type": "container",
              "name": "us.icr.io/icr4mcc/concert-sample-devsecops",
              "uri": "us.icr.io/icr4mcc/concert-sample-devsecops:204-main-a0a7e8eab28b5d3ca7abc4014080cda6309b68fa@sha256:dbd24de377d42d4e4d3a24004d5fb8664d87c74ec30ca9d26ed72cee1e7bee57"
            }
          ]
        }
      ]
    }
  ],
  "services": [
    {
      "bom-ref": "appapi:concert-sample-devsecops",
      "name": "concert-sample-devsecops",
      "properties": [
        {
          "name": "base_url",
          "value": "https://concert-sample-devsecops-service-cip-route-cd4concert.roks1-b12d73cc7b0aedf0e30addbf16d8fc5a-0000.us-east.containers.appdomain.cloud"
        },
        {
          "name": "network_exposure",
          "value": "private"
        }
      ]
    }
  ],
  "dependencies": [
    {
      "ref": "container:us.icr.io/icr4mcc/concert-sample-devsecops",
      "dependsOn": [
        "appapi:concert-sample-devsecops"
      ]
    }
  ]
}

Automating ConcertDef SBOM generation

You can use the Concert toolkit to automatically generate and upload an SBOM file in one of the Concert-defined (ConcertDef) formats.

Manually generating a ConcertDef SBOM file

To quickly test data ingestion and ensure that your Concert SBOM schema is correctly interpreted by your tools, you can manually create it by using a basic text or code editor.

Generate a new JSON file from one of the Concert-defined (ConcertDef) application, build, or deploy SBOM templates.
Edit the template details to reflect your application components and dependencies. For example, replace ${APP_NAME} and ${COMPONENT_NAME} with your application and component names, respectively.
Save the file with a .json extension, as in this example: concertdef-sbom.json.
Validate the SBOM file format by using a preferred validation tool to ensure it adheres to the ConcertDef schema.
Repeat these steps to generate SBOM files in all three Concert-defined schemas.