npm package: @sanity-labs/backstage-plugin-socket
Description: A Backstage plugin that integrates with Socket Security to display security findings and vulnerability analysis for repositories.
Latest version: 1.0.2

# 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

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

### 2. Install Backend Plugin

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

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

```typescript
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`:

```typescript
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`:

```typescript
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`:

```typescript
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:

```typescript
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`:

```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:

```bash
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](../socket-backend/README.md).

### 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:

```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

```bash
yarn start
```

### Running Tests

```bash
yarn test
```

### Building

```bash
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](https://socket.dev).

## License

Apache-2.0