Socket Security Plugin for Backstage

A Backstage plugin that integrates with Socket Security to display security findings and vulnerability analysis for repositories.

Features

• Security Dashboard: View security findings and vulnerabilities for your repositories
• Entity Integration: Add the Socket Security card to any entity page
• Severity Classification: Issues are categorized by severity (Critical, High, Medium, Low)
• Detailed Analysis: View detailed information about each security finding
• Fix Availability: See which issues have fixes available

Installation

1. Install the plugin in your Backstage app:

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

2. (Optional) Add the standalone Socket Security page to your app routes in packages/app/src/App.tsx:

import { SocketPage } from '@joshbrand/backstage-plugin-socket';

const routes = (
  <FlatRoutes>
    {/* other routes */}
    <Route path="/socket" element={<SocketPage />} />
  </FlatRoutes>
);

3. Add the Socket Security card to entity pages. Choose one or both options:

Option A: Add to Overview Tab

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

import { EntitySocketSecurityCard } from '@joshbrand/backstage-plugin-socket';

const overviewContent = (
  <Grid container spacing={3} alignItems="stretch">
    {/* existing content */}
    <Grid item md={12} xs={12}>
      <EntitySocketSecurityCard />
    </Grid>
  </Grid>
);

Option B: Add a Dedicated Security Tab

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

import { EntitySocketSecurityCard } from '@joshbrand/backstage-plugin-socket';

// Add this route to your service entity page layout
const serviceEntityPage = (
  <EntityLayout>
    {/* existing routes like Overview, CI/CD, etc. */}
    
    <EntityLayout.Route path="/security" title="Security">
      <Grid container spacing={3} alignItems="stretch">
        <Grid item xs={12}>
          <EntitySocketSecurityCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>
  </EntityLayout>
);

Option C: Use Standalone Component

For custom implementations outside of entity context:

import { StandaloneSocketSecurityCard } from '@joshbrand/backstage-plugin-socket';

// Use anywhere with explicit repository parameter
<StandaloneSocketSecurityCard repository="github.com/owner/repo-name" />

Configuration

Socket API Token and Proxy Setup

The Socket API requires authentication and CORS configuration. You need to set up both the API token and a proxy configuration.

1. Configure the Socket API Token

Add your Socket API token to your environment variables:

export SOCKET_API_TOKEN=your-socket-api-token-here

Or add it to your .env file:

SOCKET_API_TOKEN=your-socket-api-token-here

2. Configure the Backstage Proxy

Add the following proxy configuration to your app-config.yaml:

proxy:
  endpoints:
    '/socket-api':
      target: 'https://api.socket.dev'
      headers:
        Authorization: 'Bearer ${SOCKET_API_TOKEN}'
      allowedMethods: ['GET']
      changeOrigin: true

# Optional Socket plugin configuration
socket:
  # Cache time in minutes (default: 30)
  cacheTime: 30
  # Stale time in minutes (default: 5) 
  staleTime: 5
  # Severity levels to include (default: ['critical', 'high', 'medium'])
  # Available: 'critical', 'high', 'medium', 'low'
  severityFilter:
    - critical
    - high
    - medium
    # - low  # Uncomment to include low severity alerts
  # Whether to show alerts that have been ignored by org policy (default: false)
  # Set to true to match Socket dashboard behavior and see all alerts
  showIgnoredAlerts: false

This proxy configuration:

• Routes /socket-api requests to https://api.socket.dev
• Automatically adds your API token to the Authorization header
• Handles CORS issues by proxying requests through the Backstage backend
• Uses changeOrigin: true to modify the origin header for proper API routing

Configuration Options

Severity Filtering

By default, the plugin excludes low severity alerts to focus on more critical issues. You can customize which severity levels to show by modifying the severityFilter array.

Ignored Alerts

The plugin uses Socket's full scan API, which includes alerts that have been ignored by your organization's security policy. By default, these ignored alerts are filtered out to show only actionable items. Set showIgnoredAlerts: true to see all alerts (matching the Socket dashboard behavior).

Note: The Socket dashboard may show more alerts than the plugin by default because it includes ignored alerts. Enable showIgnoredAlerts if you want to match the dashboard exactly.

Entity Annotation

To enable Socket security scanning for a component, add the socket.dev/repo-slug annotation to your entity's catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    socket.dev/repo-slug: 'github.com/owner/repo-name'
spec:
  type: service
  lifecycle: production

The socket.dev/repo-slug annotation should contain the repository identifier that Socket Security can analyze.

Usage

Standalone Page

Navigate to /socket to view the Socket Security dashboard for the current entity.

Entity Card

When viewing an entity with a socket.dev/repo-slug annotation, the Socket Security card will display:

• Summary Statistics: Total findings broken down by severity
• Detailed Table: All security findings with filtering and search
• Finding Details: Click on any row to see detailed information
• Fix Information: See which findings have available fixes

Standalone Card

The StandaloneSocketSecurityCard component can be used outside of entity context:

• Takes an explicit repository prop instead of reading from entity annotations
• Useful for custom dashboards or non-entity pages
• Provides identical functionality to the entity card
• Does not require entity context or socket.dev/repo-slug annotations

Security Findings

Each finding includes:

• Severity Level: Critical, High, Medium, or Low
• Package Information: Affected package and version
• Issue Description: Details about the security issue
• Fix Availability: Whether a fix is available
• Type: Classification of the security issue

Development

Running the Plugin

yarn start

Running Tests

yarn test

Building

yarn build

Socket SDK Integration

This plugin uses the official Socket SDK (@socketsecurity/sdk) to fetch security data. The SDK provides:

• Repository analysis and vulnerability detection
• Dependency security scanning
• Real-time security insights
• Integration with Socket's threat intelligence

For more information about Socket Security, visit socket.dev.

License

Apache-2.0