Importing Services and Software Libraries

To reap the benefits of having up-to-date and in-depth software library information in VSM, we recommend the below setup.

Prerequisites

• You already have your SBOM generation process setup (most recommended as part of your build) - see our documentation on how to do so for the biggest package managers:

docs-vsm.leanix.net

Setting up the CycloneDX SBOM generation

📘

Fast centralized SBOM Onboarding

You still don't have a mature CI/CD with SBOM generation but still want to get the benefits from VSM and SBOM? We got you covered! LeanIX open-sourced VSM-SBOM-booster.
VSM-SBOM-booster is a open-source tool that you can run as a docker image that connects to your git repository instance and generates all services and SBOM without having to change all your CI/CD pipelines. Yet, we encourage you to use this tool as a starter. Eventually SBOMs need to be updated with every build.

Step 1: Calling the VSM API with a CycloneDX SBOM file

To import the service and its software dependencies by means of a CycloneDX BOM file use the below call.

🚧

Support for other SBOM schemas

Currently, the API only supports CycloneDX typed-SBOM JSON files. We are aware that there are also other SBOM schemas out there (e.g. SPDX. Let us know if you're using other schemas.

Example:

📘

Getting a Bearer Token

To authorize your API call you need to get a bearer token. See the docs on how to do so. Make sure the token has ADMIN access.

📘

Getting the <region> parameter

To call the endpoint you need to know the region your workspace is in. We are working on a way to provide this to you via the admin panel within your VSM workspace.

For now please just reach out to your LeanIX representative (Customer Success Manager/ Engineer, Sales Engineer ...)

curl --request POST \
     --url https://<region>-vsm.leanix.net/services/vsm/discovery/v1/service \
     --header 'accept: */*' \
     --header 'Authorization: Bearer <YOUR TOKEN>' \
     --header 'content-type: multipart/form-data' \
     --form id=svc12345 \
     --form sourceType=my-alerting-solution \
     --form sourceInstance=my-company \
     --form name=my-service \
     --form 'description=The one and only service with 110% uptime' \
     --form 'data={"number_of_incidents":"2","monitoring_dashboard":"https://my-company.my-alerting-solution.com/my-service"}' \
     --form [email protected]

For more details on the API, please refer to the API documentation:

docs-vsm.leanix.net

Create or Update services

GitHub Action

If you work with GitHub Actions we also have a GitHub Action available to make the SBOM generation & provision easier. Please find the detailed config options of the GitHub Action in the linked GitHub repository.

github.com

GitHub - leanix/vsm-discovery-github-action: Integrate into your CI/CD pipeline to manage service and SBOM information automatically for your LeanIX VSM workspace

Find a sample python project setup using this GitHub Action below:

github.com

GitHub - leanix-public/vsm-webshop-demo: A sample hello world service to demonstrate the VSM GitHub Action to upload Cyclone DX SBOMs

See two example usages below on how this GitHub Action can be used.

Example: NodeJS project

name: Generate and register service

on:
  push:
    branches:
      - main

jobs:
  post-deploy:
      name: Post Deployment
      runs-on: ubuntu-latest
      steps:
        - name: Setup Node ${{ env.NODE_VERSION }} Environment
            uses: actions/setup-node@v1
            with:
              node-version: ${{ env.NODE_VERSION }}
        
        # Use the respective command to generate SBOM file
        - name: Generate SBOM
            run:  |
                npm install --global @cyclonedx/cyclonedx-npm
                cyclonedx-npm --output-file "bom.json"
        
          # Invoke the GitHub action to register the service with SBOM
          - name: VSM discovery
            uses: leanix/vsm-discovery-github-action@main
            with:
              api-token: ${{ env.VSM_LEANIX_API_TOKEN }}
            # dry-run: true

Example: Java/Gradle project

Note: you will first have to add this plugin to your build.gradle or settings.gradle.kts.

name: Generate and register service

on:
  push:
    branches:
      - main

jobs:
  post-deploy:
      name: Post Deployment
      runs-on: ubuntu-latest
      steps:
          - name: Checkout
             uses: actions/checkout@v3

      - name: Set up JDK temurin 17
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Run gradlew cyclonedxBom task
        uses: gradle/gradle-build-action@v2
        with:
          build-root-directory: .
          arguments: cyclonedxBom

       # Invoke the GitHub action to register the service with SBOM
       - name: VSM discovery
         uses: leanix/vsm-discovery-github-action@main
         with:
            api-token: ${{ secrets.VSM_LEANIX_API_TOKEN }}
          # dry-run: true

📘

Importing multiple SBOM files per service

Currently, we do not support sending multiple SBOMs for the same service. You would need to merge these into one via tools like this or create individual services (most likely relevant anyways).

Step 2: Mapping your service

After the API call has fired, go to the mapping inbox and map the discovered service a) to an existing service or b) create a new service from it. Once, mapped any subsequent API call will update the source data in that service.

Step 3: Exploring the library data

After the service has been successfully mapped you can now see the Libraries tab on the service page. Navigate there to see all libraries ingested for that service.

📘

Tutorial - Setting the workflow up in Jenkins

Here's how to setup your jenkins pipeline to generate & send the SBOM file.