Black Duck logo

Backstage Black Duck Plugin

Created by Deepankumar

Black Duck is a software composition analysis platform from Synopsys. It helps you find security issues and license risks in open source and third party code. It gives broad visibility across applications and containers. Recent releases add deeper supply chain checks such as SBOM analysis and malware detection.

The Black Duck plugin brings these results into Backstage. It adds a risk profile card on a service overview. It adds a security page that shows a table of vulnerabilities for the service. Your team can see issues where they already track ownership and docs. You keep context while moving from a service record to its open source risk. The plugin is maintained in the Backstage community plugins repo. A backend plugin is available to connect to your Black Duck instance.

Typical use cases are simple. Check risk before a release. Watch for policy and license problems during development. Review issues across many services without jumping between tools. This helps engineers triage faster and gives security teams a clear view of exposure. If your org relies on open source at scale, the plugin makes that risk visible inside your portal.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

Copy
yarn add --cwd packages/app @backstage-community/plugin-blackduck

Install the backend plugin for the new backend system

This plugin uses the new backend system only. The old backend system is not supported.

Copy
yarn add --cwd packages/backend @backstage-community/plugin-blackduck-backend

Register the backend module

Open packages/backend/src/index.ts. Add the backend module to your backend.

Copy
// packages/backend/src/index.ts

import { createBackend } from '@backstage/backend-defaults';
import { blackduckModule } from '@backstage-community/plugin-blackduck-backend';

const backend = createBackend();

// Register the BlackDuck backend plugin
backend.add(blackduckModule());

backend.start();

If your backend file uses a different bootstrap setup, register the module in the same place where you add other backend modules.

Add the Risk Profile card to the Overview tab

Edit packages/app/src/components/catalog/EntityPage.tsx. Import the RiskCard. Place it in the overview content.

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

import React from 'react';
import Grid from '@material-ui/core/Grid';
import { EntityLayout, EntityAboutCard, EntityHasSubcomponentsCard } from '@backstage/plugin-catalog';
import { RiskCard } from '@backstage-community/plugin-blackduck';

// ... any existing imports and helpers like entityWarningContent

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* keep your existing overview content */}
    <Grid item md={6}>
      <EntityAboutCard variant="gridItem" />
    </Grid>

    <Grid item md={6} xs={12}>
      <RiskCard />
    </Grid>

    <Grid item md={8} xs={12}>
      <EntityHasSubcomponentsCard variant="gridItem" />
    </Grid>
  </Grid>
);

Add the BlackDuck page to a service

Add a route to show the BlackDuck table for a single version. Put it in the service entity layout.

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

import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { BlackDuckPage } from '@backstage-community/plugin-blackduck';

// reuse the same overviewContent you defined above
const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    {/* your other routes remain */}

    <EntityLayout.Route path="/blackduck" title="Security">
      <BlackDuckPage />
    </EntityLayout.Route>
  </EntityLayout>
);

export default serviceEntityPage;

Use the All Version page

If your project tracks more than one version in BlackDuck, use the All Version page. Keep the same route. Swap the component.

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

import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { BlackDuckAllVersionPage } from '@backstage-community/plugin-blackduck';

const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    <EntityLayout.Route path="/blackduck" title="Security">
      <BlackDuckAllVersionPage />
    </EntityLayout.Route>
  </EntityLayout>
);

export default serviceEntityPage;

You still need to set a default version in the annotation shown below. The RiskCard reads one version.

Hide the page when the annotation is missing

Use the helper to hide the tab for entities that are not wired to BlackDuck.

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

import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { BlackDuckPage, isBlackDuckAvailable } from '@backstage-community/plugin-blackduck';

const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="/" title="Overview">
      {overviewContent}
    </EntityLayout.Route>

    <EntityLayout.Route
      if={isBlackDuckAvailable}
      path="/blackduck"
      title="BlackDuck"
    >
      <BlackDuckPage />
    </EntityLayout.Route>
  </EntityLayout>
);

export default serviceEntityPage;

Add the catalog annotations

Add the project mapping on each entity that should show BlackDuck data. Put it in the entity yaml file in your catalog.

Copy
# catalog-info.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-service
  annotations:
    blackduck/project: example-host/example-service/version
spec:
  type: service
  owner: team-a
  lifecycle: production

Use one route per service as shown above. The page will read the annotation and load the right project.

Notes on backend support

This plugin supports the new backend system. The old backend system is not supported. If your backend still uses the legacy backend setup, migrate to the new backend system first.

Things to Know

Multiple hosts

You can point the plugin to multiple Black Duck hosts. Use the correct base URL for your hosted or on-prem server. Include the right hostname and path if your server is not at the root. Keep the token header format as shown. Black Duck expects the token prefix.

Copy
blackduck:
  default: one
  hosts:
    - name: one
      host: https://blackduck.yourcompany.one.com/api
      token: BLACKDUCK_TOKEN
    - name: two
      host: https://blackduck.yourcompany.two.com/api
      token: SECOND_BLACKDUCK_TOKEN

Plugin exports

The plugin exports three components:

  • RiskCard for the overview page.
  • BlackDuckPage for tabs.
  • BlackDuckAllVersionPage a more detailed entity tab that shows information from multiple versions.

Permissions

The Black Duck plugin supports the Backstage permissions framework. To integrate the plugin with the permissions framework, follow these steps on the backend readme file.

Changelog

This changelog is produced from commits made to the Black Duck plugin since a year ago, and based on the code located here. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

  • Remove legacy backend support in Black Duck plugins #2586 8 months ago
  • Legacy backend was previously deprecated #2045 10 months ago

Features

  • Add Black Duck scaffolder action for project creation #1885 7 months ago

Bug fixes

  • Fix project lookup when the project name has spaces or special characters #2948 6 months ago
  • Fix missing config schema in the Black Duck backend plugin #1150 12 months ago
  • Prevent missing annotation errors when Black Duck is not configured #1123 12 months ago

Maintenance

  • Reduce false positives in knip reports by updating repo tools and using a workspace based config #3018 6 months ago
  • Remove unused dev dependencies and add a script to rebuild knip reports #2433 8 months ago
  • Set up linters so repo lint works across workspaces #1272 12 months ago

Set up Backstage in minutes with Roadie