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

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

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

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

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

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

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

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

#### 2. Configure the Backstage Proxy

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

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

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

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

## License

Apache-2.0