Integrate with Backstage

By embedding Sysdig security insights directly within Backstage, you gain immediate visibility into security concerns, significantly accelerating the time to detect and respond to issues. This makes it easier to identify and address potential issues in your applications earlier in the devops cycle.

Prerequisites

• Backstage is up and running

  See Getting Started with Backstage.

• Sysdig Requirements

  • Sysdig Secure API Key

    See Retrieve Sysdig API Key for more information.

  • Sysdig Secure Endpoint

    See SaaS Regions and IP Ranges for more information.

Installation

Change directory to the root of the Backstage application directory and install backstage-plugin-sysdig. Use of the following methods:

NPM

# From your Backstage root directory
yarn --cwd packages/app add @sysdig/backstage-plugin-sysdig

GitHub

# From your Backstage root directory
git clone https://github.com/sysdiglabs/backstage-plugin-sysdig plugins/sysdig
yarn install

Configuration

Sysdig plugin uses the following to perform various operations such as fetching vulnerability scan results from Sysdig backend.

• APIs: The Sysdig plugin interacts with the Backstage through APIs that leverages annotations in the catalog-info.yaml files associated with the components.

• Annotation: Annotations are a key concept in the Backstage catalog. They attach metadata to entities defined in the catalog-info.yaml files. The metadata could be links to the documentation, system dependencies, and integration points with tools such as Jenkins for CI/CD, or Sysdig for security insights.

Configure Route Reference for Sysdig

Routes implements cross-plugin communication within the Backstage application and define routing hierarchy to ensure smooth working of the plugin. For more information, see Backstage Frontend Routes.

In order for the Sysdig plugin to work, you must add route reference for Sysdig to the entitey routes in packages/app/src/components/catalog/EntityPage.tsx:

import { SysdigPage } from '@sysdig/backstage-plugin-sysdig';

...

const serviceEntityPage = (
  <EntityLayoutWrapper>

  ...

	<EntityLayout.Route path="/sysdig" title="Sysdig">
		<SysdigPage />
	</EntityLayout.Route>

  ...

  </EntityPageLayout>
)

Route references expose a path in Backstage’s routing system. They have opaque values that symbolizes route targets within an app, tied to specific paths during runtime. Routes indirectly connect various pages that lack inherent routing links, enabling navigation between them.

Configure Sysdig Connection

In order for the Backstage application to communicate with Sysdig, you need to define Sysdig connection setting in the Backstage application configuration file.

1. Open your terminal, set the following environment variable:
   • SYSDIG_SECURE_ENDPOINT: Your Sysdig Secure endpoint.
   • SYSDIG_SECURE_TOKEN: The Sysdig Secure API token associated with your Sysdig Secure account.
2. Add the Sysdig connection settings to the app-config.yaml file:

proxy:
  endpoints:
			'/sysdig':
			  target: ${SYSDIG_SECURE_ENDPOINT}
  		  changeOrigin: true
			  allowedMethods: ['GET']
			  headers:
					"Authorization": "Bearer ${SYSDIG_SECURE_TOKEN}"
					"Content-Type": "application/json"
					"Accept": "application/json"
				  "X-Sysdig-Product": "SDS"

...

sysdig:
		endpoint: ${SYSDIG_SECURE_ENDPOINT}

Annotate Sysdig Services

A service is registered in the Backstage Catalog by using a catalog-info.yaml file. This file contains annotations that connect it to its source code repository and other integrations.

The following is an example of a catalog-info.yaml for an service called sock-shop-cart.

Runtime Scanning

To identify vulnerabilities at runtime and in-use vulnerable packages, you can use the following annotation:

  annotations:
    # VM Runtime
    sysdigcloud.com/kubernetes-cluster-name: <cluster-name>
    sysdigcloud.com/kubernetes-namespace-name: <namespace-name>
    sysdigcloud.com/kubernetes-workload-name: <workload-name>
    sysdigcloud.com/kubernetes-workload-type: <workload-type>

They connect to the Sysdig service and fetch the runtime scan results of the sock-shop-cart application.

Registry Scanning

To identify vulnerabilities vulnerable packages in your registry, you can use the annotation similar to the following:

 # VM Registry
    sysdigcloud.com/registry-vendor: harbor
    sysdigcloud.com/registry-name: registry-harbor-registry.registry.svc.cluster.local:5443

Example Annotation

Sysdig provides curated annotations to help you with insights into the potential risks associated with your current build. In addition to the previous examples, you can fetch pipeline results, compliance reports, and more.

Here is an example of the catalog-info.yaml for a service named sock-shop-carts:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: sock-shop-carts
  annotations:
    # VM Runtime
    sysdigcloud.com/kubernetes-cluster-name: sock-shop-cluster
    sysdigcloud.com/kubernetes-namespace-name: sock-shop
    sysdigcloud.com/kubernetes-workload-name: sock-shop-carts
    sysdigcloud.com/kubernetes-workload-type: deployment

    # VM Registry
    sysdigcloud.com/registry-vendor: harbor
    sysdigcloud.com/registry-name: registry-harbor-registry.registry.svc.cluster.local:5443

    # VM Pipeline
    sysdigcloud.com/image-freetext: ghcr.io/sysdiglabs
    
    # Posture
    sysdigcloud.com/resource-name: sock-shop-carts
    sysdigcloud.com/resource-type: "Deployment"
  description: |
    This is the Sock shop service that keeps track of socks pairs to be purchased.
spec:
  type: service
  lifecycle: experimental
  owner: team-c
  system: sock-shop
  dependsOn:
    - component:default/sock-shop-carts-db

Not all the annotations are necessary for the plugin to work; the functionality of various reports may vary based on the information provided. For instance, to access Registry scanning results, you must annotate the relevant services with registry data.

Once the service is added to the catalog, you can manage the sock-shop-cart from Backstage.

For the detailed workflow, see Sysdig Integration with Backstage.