Socket Security Plugin for Backstage

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

Note: As of version 1.0.0, this plugin has been split into separate frontend and backend packages. The frontend provides UI components while the backend handles Socket API integration with server-side caching.

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
• Backend Integration: Server-side caching and API handling via the backend plugin

Installation

This plugin requires both frontend and backend packages:

1. Install Frontend Plugin

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

2. Install Backend Plugin

yarn --cwd packages/backend add @sanity-labs/backstage-plugin-socket-backend

Then add the backend plugin to packages/backend/src/index.ts:

backend.add(import('@sanity-labs/backstage-plugin-socket-backend'));

3. Add UI Components

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

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

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

4. Add to Entity Pages

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 '@sanity-labs/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 '@sanity-labs/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 '@sanity-labs/backstage-plugin-socket';

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

Configuration

Add configuration to your app-config.yaml:

socket:
  # Backend configuration (required)
  apiToken: ${SOCKET_API_TOKEN}  # Required - Socket.dev API token
  apiBaseUrl: https://api.socket.dev  # Optional - Socket API base URL (default: https://api.socket.dev)

  # Frontend configuration (optional)
  cacheTime: 30  # Frontend cache time in minutes (default: 30)
  staleTime: 5   # Stale time in minutes (default: 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

Set your Socket API token as an environment variable:

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

Or add it to your .env file:

SOCKET_API_TOKEN=your-socket-api-token-here

Note: The backend plugin handles all Socket API communication and authentication. No proxy configuration is needed. For additional backend configuration options, see the backend plugin README.

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

Architecture

This plugin uses a frontend-backend architecture:

• Frontend (@sanity-labs/backstage-plugin-socket): React components for displaying security findings
• Backend (@sanity-labs/backstage-plugin-socket-backend): REST API with server-side caching that integrates with Socket.dev API

The backend plugin handles:

• Socket.dev API authentication and communication
• Server-side caching to reduce API calls
• Data transformation and aggregation

The frontend plugin provides:

• UI components for displaying security findings
• Client-side query caching with React Query
• Filtering and search functionality

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

License

Apache-2.0