SOC-lite SDK

SOC-lite is a Node.js security middleware package for Express applications. It connects your application to the SOC-lite control plane, pulls signed heartbeat state, syncs threat signatures, inspects requests, and ships sanitized telemetry upstream.

Repository Layout

soc/
  package/
    index.js          # SDK entry point and middleware assembly
    interceptor.js    # Request inspection and blocking logic
    logger.js         # Async buffered log shipping
    worker.js         # Heartbeat and rule background sync
    dashboard.js      # Local observability UI and stats API
  server/
    src/app.js                        # Hardened Express app bootstrap
    src/server.js                     # HTTP server startup and shutdown
    src/routes/api-v1.js              # /heartbeat, /logs, /rules routes
    src/middleware/verify-agent.js    # API key authentication with Redis cache
    src/services/heartbeat.js         # Signed heartbeat generation
    src/services/log-ingest-queue.js  # Async ClickHouse ingestion queue
    src/services/threat-rules.js      # Threat signature loader and validator
    src/db/*.js                       # PostgreSQL, ClickHouse, Redis clients
    db/postgres/schema.sql            # Management schema
    db/clickhouse/security_logs.sql   # Analytics schema

Requirements

• Node.js >= 20.11.0
• Express >= 4.18.0 < 6
• A reachable SOC-lite server URL in SOC_LITE_SERVER_URL
• A valid project API key in SOC_LITE_API_KEY

Installation

npm install soc-lite-sdk

The SDK does not ship its own third-party runtime dependencies. Your host application must already use Express.

Mandatory Secret Handling

1. Store the API key in a .env file.
2. Load the key into process.env.
3. Pass process.env.SOC_LITE_API_KEY into the SDK.
4. Never hardcode the API key in source files.
5. Never commit .env to source control.

Example .env:

SOC_LITE_API_KEY=replace-with-your-project-api-key
SOC_LITE_SERVER_URL=https://soc.example.com

Recommended .gitignore entry:

.env

Quick Start

'use strict';

require('dotenv').config();

const express = require('express');
const createSocLiteMiddleware = require('soc-lite-sdk');

async function main() {
  const app = express();

  app.use(express.json({ limit: '1mb' }));

  const socLite = await createSocLiteMiddleware({
    apiKey: process.env.SOC_LITE_API_KEY,
    panelPath: '/soc-admin',
    mode: 'monitor'
  });

  app.use(socLite);

  app.get('/healthz', (req, res) => {
    res.json({ ok: true });
  });

  app.listen(3000);
}

main().catch((error) => {
  process.stderr.write(`${error.stack || error}\n`);
  process.exit(1);
});

Config Object

createSocLiteMiddleware(config) accepts:

| Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | apiKey | string | Yes | None | Project API key. Pass process.env.SOC_LITE_API_KEY. | | panelPath | string | No | '/soc-admin' | Local dashboard route mounted into the host Express app. | | mode | 'monitor' \| 'block' | No | 'monitor' | Requested protection mode. Effective block mode only activates with a valid signed heartbeat. | | trafficLogging | 'off' \| 'incidents' \| 'all' | No | 'incidents' | Controls whether request logs are buffered and shipped to the SOC-lite server. |

Runtime Behavior

• On startup, the SDK validates the config object and environment.
• The first signed heartbeat is fetched before middleware becomes active.
• Threat rules are pulled from the control plane and compiled in memory.
• Every 5 minutes, the SDK refreshes heartbeat state.
• Every 1 hour, the SDK refreshes threat rules without restarting the host server.
• If heartbeat fails 3 times in a row, or the signed heartbeat becomes stale, the SDK falls back to safe monitor/passive behavior.
• Request logs are buffered in memory and sent upstream asynchronously in batches.

Local Dashboard

When panelPath is set, the SDK mounts:

• GET {panelPath} for the local single-page dashboard
• GET {panelPath}/api/stats for live local stats

Operational guidance:

• Treat the dashboard as sensitive operational telemetry.
• Do not expose it on a public route without upstream access controls.
• Prefer internal-only routing, VPN access, or reverse-proxy authentication in production.

Security Guarantees

The current implementation is designed around OWASP-aligned secure coding practices:

• Strict environment-variable validation with fail-fast startup
• No raw API key persistence in server storage
• SHA-256 derived API key matching on the server
• HMAC-signed heartbeat verification before block mode activation
• Constant-time signature comparison
• JSON-only authenticated POST endpoints on the server
• Bounded request parsing, queue sizes, payload sizes, and background buffers
• Sanitization and masking of sensitive request fields and headers before logging
• Fail-safe degradation to passive or monitor mode during control-plane failure
• Security headers on both the control-plane API and local dashboard
• Non-blocking logging and background tasks to reduce host application impact

Developer Rules

• Do not pass secrets as string literals in application code.
• Do not disable TLS for the SOC-lite server in production.
• Do not expose the dashboard route to the public internet without access control.
• Do not modify SDK request inspection state from application code.
• Do not rely on block mode unless heartbeat is active and signed.

Troubleshooting

SOC-lite requires an apiKey

Cause: config.apiKey was missing or empty.

Fix: Load SOC_LITE_API_KEY from .env and pass process.env.SOC_LITE_API_KEY.

SOC_LITE_SERVER_URL must use https in production

Cause: The SDK was started in production with a non-local HTTP control-plane URL.

Fix: Use HTTPS for the central SOC-lite server, or bind the control plane to localhost only.

The SDK is in passive mode

Possible causes:

• The heartbeat endpoint is unreachable
• The heartbeat signature is invalid or expired
• The project is paused, archived, or over quota
• Redis session recording failed on the server

Production Checklist

• .env is excluded from source control
• SOC_LITE_SERVER_URL uses HTTPS
• Server-side API keys are stored as one-way derived values
• PostgreSQL, Redis, and ClickHouse credentials are rotated and least-privileged
• Reverse proxy enforces TLS and sane request size limits
• The local dashboard path is protected or kept internal
• Monitoring is configured for heartbeat failures and queue backpressure