Get Roadie in your IDE with our new MCP Servers
Roadie
← Backstage Plugins Guides
Security Insights logo

Backstage Security Insights Plugin

Created by Roadie

Security Insights brings GitHub security findings into Backstage. It gives each software component a clear view of its risks in one place. You see what matters without leaving your developer portal.

The plugin fetches alerts from GitHub Security features such as code scanning and Dependabot. It shows them in a simple table with filters and search. You can focus on open issues first. You can sort by severity to spot high impact problems. Each row links back to GitHub for full detail. A small stats widget summarizes counts so you can scan the state of a service at a glance.

This fits teams running a self hosted Backstage who want less context switching. Use it to triage during standups. Use it to track fixes across many services. Use it to highlight risk to service owners in your catalog. It helps you answer what is broken right now and who owns the fix.

The plugin stays close to Backstage patterns. It works with entity pages and overview cards. It respects GitHub sign in so people only see what they should. You get a steady picture of security health inside the place your engineers already use.

A screenshot of the Security Insights plugin. It is showing a security insights for a sample component.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the package

  1. Add the plugin to your app package
Copy 
yarn workspace app add @roadiehq/backstage-plugin-security-insights

If you do not use workspaces, run this in packages app

Copy 
yarn add @roadiehq/backstage-plugin-security-insights
  1. Make sure SCM auth is available in the frontend

Add the default SCM auth API factory to your app apis. This is needed by the plugin to talk to GitHub using the signed in user session.

Copy 
// packages/app/src/apis.ts
import { ScmAuth } from '@backstage/integration-react';

// add this entry to your exported apis array
export const apis = [
  // other api factories already in your app
  ScmAuth.createDefaultApiFactory(),
];

Add Security Insights and Dependabot tabs

  1. Open the service entity page
Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout, EntityPageLayout } from '@backstage/plugin-catalog';
import {
  EntitySecurityInsightsContent,
  EntityGithubDependabotContent,
  isSecurityInsightsAvailable,
} from '@roadiehq/backstage-plugin-security-insights';

const serviceEntityPage = (
  <EntityPageLayout>
    {/* other routes */}
    <EntityLayout.Route
      path="/security-insights"
      title="Security Insights"
      // Uncomment to only show when the entity has the required annotations
      // if={isSecurityInsightsAvailable}
    >
      <EntitySecurityInsightsContent />
    </EntityLayout.Route>

    <EntityLayout.Route
      path="/dependabot"
      title="Dependabot"
      // Uncomment to only show when the entity has the required annotations
      // if={isSecurityInsightsAvailable}
    >
      <EntityGithubDependabotContent />
    </EntityLayout.Route>
    {/* other routes */}
  </EntityPageLayout>
);

export const serviceEntityPageContent = serviceEntityPage;
  1. Make sure the page is used by your app router just like your existing entity pages
Copy 
// packages/app/src/App.tsx
// this is a common pattern, keep using your existing layout
// only ensure the serviceEntityPageContent is part of it

Add overview widgets

  1. Add the Security Insights widget
Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import {
  SecurityInsightsWidget,
  isSecurityInsightsAvailable,
} from '@roadiehq/backstage-plugin-security-insights';

// inside your overview content
// example using EntitySwitch
import { EntitySwitch } from '@backstage/plugin-catalog';
import Grid from '@material-ui/core/Grid';

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* other cards */}
    <EntitySwitch>
      <EntitySwitch.Case if={isSecurityInsightsAvailable}>
        <Grid item md={6}>
          <SecurityInsightsWidget />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
    {/* other cards */}
  </Grid>
);
  1. Add the Dependabot alerts widget
Copy 
// packages/app/src/components/catalog/EntityPage.tsx
import {
  DependabotAlertsWidget,
  isSecurityInsightsAvailable,
} from '@roadiehq/backstage-plugin-security-insights';

// inside your overview content
import { EntitySwitch } from '@backstage/plugin-catalog';
import Grid from '@material-ui/core/Grid';

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* other cards */}
    <EntitySwitch>
      <EntitySwitch.Case if={isSecurityInsightsAvailable}>
        <Grid item md={6}>
          <DependabotAlertsWidget />
        </Grid>
      </EntitySwitch.Case>
    </EntitySwitch>
    {/* other cards */}
  </Grid>
);

Configure Dependabot widget severity filter optional

Copy 
# app-config.yaml
dependabotAlertsConfiguration:
  severity: [ high, medium ]

Entity requirements

  • The plugin uses the repository location from the entity. Entities created from GitHub locations usually include the managed by location annotations set by the catalog.
  • If you want to hide tabs until an entity is ready, keep the isSecurityInsightsAvailable guard in place.

Sign in and permissions

  • Users need to sign in so the plugin can use their GitHub token through SCM auth.
  • Keep your GitHub auth provider enabled in your app. The default Backstage app already includes this in the sign in page. If you removed it, add it back.

Example sign in page setup

Copy 
// packages/app/src/App.tsx
import { SignInPage } from '@backstage/core-components';
import { githubAuthApiRef } from '@backstage/core-plugin-api';

const app = createApp({
  components: {
    SignInPage: props => (
      <SignInPage
        {...props}
        provider={{
          id: 'github-auth-provider',
          title: 'GitHub',
          message: 'Sign in using GitHub',
          apiRef: githubAuthApiRef,
        }}
      />
    ),
  },
});

Things to Know

GitHub Advanced Security

This plugin requires features provided by GitHub advanced security. Specifically, it calls the code-scanning endpoints.

Advanced security is free for public repos but not for private repos even on GitHub Enterprise plans. It must be purchased separately.

You can check if you have Advanced Security enabled by navigating to your repo in GitHub and checking under Security -> Overview -> “Code scanning alerts”.

Changelog

This changelog is produced from commits made to the Security Insights 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.

Features

  • Improve GitHub OAuth state sharing across plugins. Security Insights uses a shared package to manage login state and scopes. #1792 9 months ago
  • Modify GitHub sign in flow. Make the Sign In button work as expected. Add a common login wrapper in the plugin. #1788 9 months ago
  • Add a Sign In button in entity GitHub related cards. Helps users sign in to see data. #1665 12 months ago

Bug Fixes

  • Set filtered table data on first load. Fix empty table when the Open filter is active. #1707 11 months ago

Maintenance

  • Upgrade to Backstage 1.40. #1952 2 months ago
  • Remove unused plugin dependencies. #1847 7 months ago
  • Revert a plugin dependency update from #1821. #1825 8 months ago
  • Update plugin dependencies. #1821 8 months ago
  • Update a dependency in GitHub plugin packages. #1801 9 months ago
  • Move from moment to luxon for date handling. #1759 10 months ago
  • Update Backstage package versions. #1728 10 months ago
  • Update Backstage dependencies. #1684 12 months ago

Set up Backstage in minutes with Roadie

Get a demo