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

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/[email protected]
            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/[email protected]
            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/[email protected]

      - name: Set up JDK temurin 17
        uses: actions/[email protected]
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Run gradlew cyclonedxBom task
        uses: gradle/[email protected]
        with:
          build-root-directory: .
          arguments: cyclonedxBom

       # Invoke the GitHub action to register the service with SBOM
       - name: VSM discovery
         uses: leanix/[email protected]
         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.