last update: 2025-12-17

Snyk Backstage Plugin

The Snyk plugin displays security details from snyk.io.

Features

• List vulnerabilities detected by Snyk directly in Backstage with the EntitySnykContent component.
• Use the SnykOverview widget to get a compact vulnerability count on your entity page.

Installation

1. Ensure you are on a Snyk Paid plan to access the Snyk API.

2. Install the plugin:

yarn --cwd packages/app add backstage-plugin-snyk

3. Add the plugin to the EntityPage.tsx file. Feel free to rename the title to Security, Snyk, Vulns, or whatever you prefer.

// packages/app/src/components/catalog/EntityPage.tsx

import {
  SnykOverview,
  EntitySnykContent,
  isSnykAvailable,
} from "backstage-plugin-snyk";

...

const serviceEntityPage = (
  ...
  <EntityLayout.Route 
    path="/snyk"
    title="Snyk"
    // Uncomment the line below if you'd like to only show the tab on entities with the correct annotations already set
    // if={isSnykAvailable}
  >
    <EntitySnykContent />
  </EntityLayout.Route>
);

To show the vulnerability count widget:

// packages/app/src/components/catalog/EntityPage.tsx
const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    ...
    <Grid item md={6} if={isSnykAvailable}>
      <SnykOverview />
    </Grid>
  </Grid>
);

Or make it conditional:

// packages/app/src/components/catalog/EntityPage.tsx

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    ...
    <EntitySwitch>
      <EntitySwitch.Case if={isSnykAvailable}>
        <Grid item md={6}>
          <SnykOverview />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
  </Grid>
);

Plugin Configuration

1. Add the Snyk proxy configuration to the app-config.yaml file in the root directory. The User Agent helps us track API traffic from Backstage setups so we can invest more in the plugin!

proxy:
  endpoints:
    ...
    /snyk:
      # Host of the API to use for calls.
      # For Snyk Enterprise customers with regional contracts, change this to api.eu.snyk.io (for EU) or api.au.snyk.io (for AUS) (see https://docs.snyk.io/working-with-snyk/regional-hosting-and-data-residency)
      target: https://api.snyk.io/ 
      headers:
        User-Agent: tech-services/backstage-plugin/1.x
        Authorization: token ${SNYK_TOKEN}
    ...

2. Optionally, add the following configuration to your app-config.yaml:

snyk:
  # Host of the Web UI to render links. Defaults to "app.snyk.io"
  # If you use an EU or AU Snyk account, change this to app.eu.snyk.io or app.au.snyk.io
  appHost: app.snyk.io
  #
  # Uncomment to specify the version of the API to use for calls. Defaults to "2024-02-28".
  # Override with care, not all versions have a target API.
  # apiVersion: 2024-02-28
  # Uncomment to specify the version for the issues API specifically. Defaults to 2024-01-23
  # issuesApiVersion: 2024-01-23
  #
  # Mocks the API calls, useful for development and for testing the plugin without a Snyk account. Defaults to "false".
  mocked: false
  #
  # Shows resolved issues in all graphs. Defaults to "false" to show only non-resolved issues.
  showResolvedInGraphs: false

3. Obtain your Snyk token (a service account with Viewer permission at your group level is preferred) and set the SNYK_TOKEN environment variable with its value:

   export SNYK_TOKEN="123-123-123-123"

4. Add one of the following annotations to your entities:

   • snyk.io/org-id: The ID of the Snyk organization where your project is located. You can find the ID in the Organization Settings in the Snyk dashboard.
   • snyk.io/org-ids: Specify one or more Snyk organization IDs, comma-separated. This will try to find any targets or projects in any of the organizations. snyk.io/org-id is ignored when this annotation is set.

5. Then add one or more of the following annotations to your entities:

   • snyk.io/targets: Specify one or more targets by name or ID. Using the target ID will avoid an API call and be faster. Use this API endpoint to get the Target IDs.
   • snyk.io/target-id: Specify a single target by name or ID. Using the target ID will avoid an API call and be faster. Use this API endpoint to get the Target IDs.
   • snyk.io/target-name: Specify a single target by display name. Prefer snyk.io/target-id when possible.
   • snyk.io/project-ids: The project ID (see slug in URL or ID in project settings). If there are multiple projects (e.g., multiple package.json or pom files), add them comma-separated.
   • snyk.io/exclude-project-ids: Exclude specific projects you might not want.

Annotation precedence when resolving targets:

• Start with snyk.io/targets (if present)
• Then append snyk.io/target-id, else snyk.io/target-name
• If none of the above are set, and no snyk.io/project-ids are present, fall back to github.com/project-slug

Notes:

• snyk.io/project-ids are always fetched and merged into the results and disable slug fallback
• snyk.io/exclude-project-ids are applied afterward to filter the combined list

Example:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: goof
  description: Goof
  annotations:
    snyk.io/org-id: 361fd3c0-41d4-4ea4-ba77-09bb17890967
    snyk.io/targets: Snyk Demo/java-goof,508d2263-ea8a-4e42-bc9d-844de21f4172
    snyk.io/target-id: aarlaud-snyk/github-stats
    snyk.io/project-ids: 7439e322-f9c1-4c42-8367-002b33b9d946,db066cb9-b373-46da-b918-b49b541e0d63
    snyk.io/exclude-project-ids: 4737fc9c-3894-40ba-9dc5-aa8ae658c9f6,38e02916-0cf7-4927-ba98-06afae9fef36
spec:
  type: service
  lifecycle: production
  owner: guest
  ....

More examples can be found here.

New FrontEnd System

Nice contributions helped us move to the new frontend system. It's ready to be used. Instructions are available here.

Migration Steps from Plugin Version 1.x to 2.x

• Update the proxy target to not contain /v1.

Releasing Process

This plugin uses a special versioning system for Backstage dependencies to ensure compatibility with different Backstage versions.

Version Bumping Overview

The plugin uses backstage:^ syntax for Backstage-related dependencies in development, which gets converted to explicit versions during publishing:

• Development: backstage:^ (flexible, uses Backstage Yarn plugin)
• Published: ^1.7.6 (explicit, npm-compatible)

Automated Release (CI/CD)

The CircleCI pipeline handles version bumping automatically:

1. Pre-publish: Removes Backstage Yarn plugin and converts backstage:^ → explicit versions
2. Publish: Runs semantic-release to publish to npm
3. Post-publish: Restores Backstage Yarn plugin and backstage:^ syntax

Manual Release

For local publishing, manually run:

# Remove plugin and bump versions
yarn plugin remove @yarnpkg/plugin-backstage
yarn backstage-cli versions:bump --skip-install

# Publish to npm
npm publish

# Restore plugin and backstage:^ syntax
yarn plugin import https://versions.backstage.io/v1/releases/1.47.3/yarn-plugin
yarn backstage-cli versions:bump --skip-install

Version Resolution

• backstage.json defines the target Backstage version
• versions:bump converts backstage:^ to explicit versions based on this target
• Published packages have fixed Backstage dependency versions for stability

Troubleshooting

• Missing or incorrect token set in the backend proxy.

  

• 404 errors from the Snyk API? Add the following pathRewrite to your app-config.yaml proxy:

proxy:
  endpoints:
    ...
    /snyk:
      target: https://api.snyk.io/
      headers:
        User-Agent: tech-services/backstage-plugin/1.x
        Authorization: token ${SNYK_TOKEN}
      pathRewrite:
        "^/proxy/snyk/": "/"

New Frontend System

Follow these steps to detect and configure the Snyk plugin if you'd like to use it in an application that supports the new Backstage frontend system.

Package Detection

Once you install the backstage-plugin-snyk package using your preferred package manager, you have to choose how the package should be detected by the app. The package can be automatically discovered when the feature discovery config is set, or it can be manually enabled via code (for more granular package customization cases).

//...

Extensions Configuration

Currently, the plugin installs 5 extensions: 1 api, 1 page, 1 nav item (sidebar item), 1 entity page card and 1 entity page content (also known as entity page tab), see below examples of how to configure the available extensions.

# app-config.yaml
app:
  extensions:
    # Example disabling the Snyk entity card
    - 'entity-card:snyk': false
    # Example disabling the Snyk entity content
    - 'entity-content:snyk': false
    # Example customizing the Snyk entity content
    - 'entity-content:snyk':
        config:
          path: '/security'
          title: 'Security'
          filter:
            kind: 'component'