Socket Backend Plugin

Backend plugin for the Socket.dev security integration. This plugin provides a REST API for fetching Socket.dev security reports with server-side caching.

Note: This is the backend companion to @sanity-labs/backstage-plugin-socket. Both packages are required for full functionality.

Installation

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

Setup

1. Add the plugin to your backend in packages/backend/src/index.ts:

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

2. Configure in app-config.yaml:

socket:
  apiToken: ${SOCKET_API_TOKEN}  # Required - Socket.dev API token
  cacheTime: 5                    # Optional - Backend cache TTL in minutes (default: 5)
  apiBaseUrl: https://api.socket.dev  # Optional - Socket API base URL (default: https://api.socket.dev)

3. Set environment variable:

Option 1: Using .env file (recommended for local development)

Create a .env file in the root of your project:

SOCKET_API_TOKEN=your-socket-api-token

Then run the development servers with the dotenv wrapper:

yarn dev

The dev script uses dotenv-cli to automatically load variables from .env.

Option 2: Export environment variable

export SOCKET_API_TOKEN=your-socket-api-token
yarn start-backend

Note: A .env.example file is provided in the repository root as a template.

API Endpoints

GET /api/socket/health

Health check endpoint with cache statistics.

Response:

{
  "status": "ok",
  "cache": {
    "size": 3,
    "keys": ["report-owner/repo"]
  },
  "config": {
    "apiBaseUrl": "https://api.socket.dev",
    "cacheTime": 5,
    "hasApiToken": true
  }
}

GET /api/socket/reports/:repo/latest

Get the latest security report for a repository.

Parameters:

• repo (path): Repository in format owner/repo (URL-encoded)

Example:

curl http://localhost:7007/api/socket/reports/owner%2Frepo/latest

Response:

{
  "repository": "owner/repo",
  "findings": [...],
  "totalFindings": 10,
  "criticalFindings": 2,
  "highFindings": 3,
  "mediumFindings": 5,
  "lowFindings": 0,
  "scannedAt": "2024-01-01T00:00:00Z",
  "cachedAt": "2024-01-01T00:05:00Z"
}

Caching

The backend implements TTL-based in-memory caching to reduce Socket.dev API calls:

• Default cache TTL: 5 minutes
• Cache key format: report-{repository}
• Cache automatically expires stale entries

Development

Build:

yarn tsc
yarn build

Test:

yarn test

Lint:

yarn lint