sentinelle-agent 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# sentinelle-agent
+
+Sentinelle monitoring agent for **Node.js** apps. Supports **Express**, **Fastify**, **Koa**, **NestJS**.
+
+Pair this with the official dashboard at [sentinelle.dev](https://sentinelle.dev) to get heartbeats, route discovery, error capture and request metrics — all visible in real time.
+
+A Python sibling is published as [`sentinelle-agent` on PyPI](https://pypi.org/project/sentinelle-agent/) with identical wire format.
+
+## Install
+
+```bash
+npm install sentinelle-agent
+```
+
+## Configuration
+
+Two ways, equivalent:
+
+**Env vars** (recommended in production):
+
+```bash
+SENTINELLE_API_KEY=your-project-api-key
+SENTINELLE_SERVER_URL=https://api.sentinelle.dev
+SENTINELLE_APP_NAME=my-node-app
+```
+
+**Code:**
+
+```js
+const sentinelle = require('sentinelle-agent');
+
+sentinelle.init({
+  apiKey: 'your-project-api-key',
+  serverUrl: 'https://api.sentinelle.dev',
+  appName: 'my-node-app',
+});
+```
+
+Get your `apiKey` from your Sentinelle dashboard — project settings.
+
+## Express
+
+```js
+const express = require('express');
+const sentinelle = require('sentinelle-agent');
+
+sentinelle.init({ appName: 'my-app' });
+
+const app = express();
+
+// BEFORE your routes
+app.use(sentinelle.middleware());
+
+// your routes here
+app.get('/hello', (req, res) => res.json({ ok: true }));
+
+// AFTER your routes
+app.use(sentinelle.errorHandler());
+
+// Auto-discover all routes (call after registration)
+sentinelle.discoverRoutes(app);
+
+app.listen(3000);
+```
+
+## NestJS
+
+```ts
+// main.ts
+import * as sentinelle from 'sentinelle-agent';
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  sentinelle.init({ appName: 'my-nestjs-app' });
+
+  const app = await NestFactory.create(AppModule);
+  const expressApp = app.getHttpAdapter().getInstance();
+  expressApp.use(sentinelle.middleware());
+  expressApp.use(sentinelle.errorHandler());
+
+  await app.listen(3000);
+  sentinelle.discoverRoutes(expressApp);
+}
+bootstrap();
+```
+
+## What it does
+
+**Per-request** (Express middleware):
+- Times each request, captures method/path/status/responseMs/IP/UA
+- Aggregates top routes, errors 4xx/5xx, status distribution
+
+**Errors:**
+- Unhandled exceptions in routes (via `errorHandler` middleware)
+- Uncaught exceptions and unhandled rejections at process level
+- Slow requests (> 5000 ms) reported as warnings
+- Sensitive fields auto-redacted in bodies: `password`, `token`, `secret`, `authorization`, `cookie`, `credit_card`, `cvv`, `ssn`
+
+**Routes:**
+- Discovered automatically via Express internal router stack
+- Posted once to `/api/webhooks/agent/routes`
+
+**Heartbeat** (every 60s):
+- App uptime, RSS / heap memory, Node version
+- Request metrics (total, avg ms, errors 4xx/5xx, top 5 routes)
+- Posted to `/api/webhooks/agent/heartbeat`
+
+**Server-driven kill switch:**
+If the backend returns `kill_switch_active: true` in a heartbeat response, the agent stops uploading new errors (but keeps sending heartbeats so the project stays observable).
+
+## Custom errors
+
+```js
+const sentinelle = require('sentinelle-agent');
+
+try {
+  await chargeCard(user);
+} catch (err) {
+  sentinelle.getAgent()?.reportError({
+    type: 'PaymentFailed',
+    message: err.message,
+    fatal: false,
+  });
+  throw err;
+}
+```
+
+## Options
+
+```js
+sentinelle.init({
+  apiKey: '...',
+  serverUrl: 'https://api.sentinelle.dev',
+  appName: 'my-app',
+  heartbeatInterval: 60000,    // ms, default 60_000
+  captureUnhandled: true,      // install process-level handlers
+  debug: false,                // print [Sentinelle Agent] log lines
+});
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "sentinelle-agent",
+  "version": "1.0.0",
+  "description": "Sentinelle monitoring agent for Node.js — error capture, route discovery, request metrics, and health reporting. Supports Express, Fastify, Koa, NestJS.",
+  "main": "src/index.js",
+  "keywords": [
+    "monitoring",
+    "rasp",
+    "security",
+    "observability",
+    "error-tracking",
+    "health-check",
+    "express",
+    "fastify",
+    "koa",
+    "nestjs",
+    "middleware",
+    "sentinelle"
+  ],
+  "author": "Sentinelle <hello@sentinelle.dev>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "homepage": "https://sentinelle.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sentinelle-dev/sentinelle-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sentinelle-dev/sentinelle-agent/issues"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  }
+}

package/src/core.js

@@ -0,0 +1,320 @@
+/**
+ * AgentCore — the heart of the Sentinelle agent
+ * Handles heartbeat, error batching, request metrics, and communication with Sentinelle server
+ */
+
+class AgentCore {
+  constructor(config) {
+    this.config = config;
+    this.running = false;
+    this.heartbeatTimer = null;
+    this.flushTimer = null;
+
+    // Buffers
+    this.errors = [];
+    this.requestMetrics = {
+      total: 0,
+      byStatus: {},
+      byRoute: {},
+      avgResponseMs: 0,
+      totalResponseMs: 0,
+      errors5xx: 0,
+      errors4xx: 0,
+    };
+    this.discoveredRoutes = [];
+
+    // Server-driven kill switch state — set by heartbeat response.
+    // Quand actif, l'agent suspend l'envoi d'erreurs (qui pourraient déclencher
+    // des fix auto) mais continue le heartbeat pour rester observable.
+    this.killSwitchActive = false;
+    this.killSwitchSince = null;
+
+    // System info
+    this.systemInfo = {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      pid: process.pid,
+    };
+  }
+
+  log(msg) {
+    if (this.config.debug) {
+      console.log(`[Sentinelle Agent] ${msg}`);
+    }
+  }
+
+  /**
+   * Start the agent — begins heartbeat and sets up unhandled error capture
+   */
+  start() {
+    if (this.running) return;
+    this.running = true;
+
+    this.log(`Starting agent for "${this.config.appName}" → ${this.config.serverUrl}`);
+
+    // Heartbeat
+    this.heartbeatTimer = setInterval(() => this.sendHeartbeat(), this.config.heartbeatInterval);
+
+    // Flush error buffer every 30s
+    this.flushTimer = setInterval(() => this.flushErrors(), 30000);
+
+    // Capture unhandled errors
+    if (this.config.captureUnhandled) {
+      process.on('uncaughtException', (err) => {
+        this.reportError({
+          type: 'UncaughtException',
+          message: err.message,
+          stack: err.stack,
+          fatal: true,
+          timestamp: new Date().toISOString(),
+        });
+        // Flush immediately for fatal errors
+        this.flushErrors();
+      });
+
+      process.on('unhandledRejection', (reason) => {
+        const err = reason instanceof Error ? reason : new Error(String(reason));
+        this.reportError({
+          type: 'UnhandledRejection',
+          message: err.message,
+          stack: err.stack,
+          fatal: false,
+          timestamp: new Date().toISOString(),
+        });
+      });
+    }
+
+    // Send initial heartbeat
+    setTimeout(() => this.sendHeartbeat(), 2000);
+
+    this.log('Agent started');
+  }
+
+  /**
+   * Stop the agent
+   */
+  async stop() {
+    this.running = false;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    if (this.flushTimer) clearInterval(this.flushTimer);
+
+    // Flush remaining errors
+    await this.flushErrors();
+
+    this.log('Agent stopped');
+  }
+
+  /**
+   * Track a request (called by Express middleware)
+   */
+  trackRequest(data) {
+    this.requestMetrics.total++;
+    this.requestMetrics.totalResponseMs += data.responseMs || 0;
+    this.requestMetrics.avgResponseMs = Math.round(
+      this.requestMetrics.totalResponseMs / this.requestMetrics.total
+    );
+
+    // By status code
+    const status = data.statusCode || 0;
+    this.requestMetrics.byStatus[status] = (this.requestMetrics.byStatus[status] || 0) + 1;
+
+    if (status >= 500) this.requestMetrics.errors5xx++;
+    if (status >= 400 && status < 500) this.requestMetrics.errors4xx++;
+
+    // By route (top 50)
+    const routeKey = `${data.method} ${data.route || data.path}`;
+    if (!this.requestMetrics.byRoute[routeKey]) {
+      this.requestMetrics.byRoute[routeKey] = { count: 0, totalMs: 0, errors: 0 };
+    }
+    const route = this.requestMetrics.byRoute[routeKey];
+    route.count++;
+    route.totalMs += data.responseMs || 0;
+    if (status >= 400) route.errors++;
+
+    // Report slow requests as errors
+    if (data.responseMs > 5000) {
+      this.reportError({
+        type: 'SlowRequest',
+        message: `Slow request: ${data.method} ${data.path} took ${data.responseMs}ms`,
+        method: data.method,
+        path: data.path,
+        statusCode: data.statusCode,
+        responseMs: data.responseMs,
+        timestamp: data.timestamp,
+      });
+    }
+  }
+
+  /**
+   * Report an error (buffered, sent in batches)
+   */
+  reportError(error) {
+    this.errors.push({
+      ...error,
+      appName: this.config.appName,
+      agentVersion: '1.0.0',
+    });
+
+    this.log(`Error captured: ${error.type} — ${error.message}`);
+
+    // Flush immediately if buffer is large or error is fatal
+    if (this.errors.length >= 10 || error.fatal) {
+      this.flushErrors();
+    }
+  }
+
+  /**
+   * Report discovered routes to Sentinelle
+   */
+  async reportRoutes(routes) {
+    this.discoveredRoutes = routes;
+    this.log(`Discovered ${routes.length} routes`);
+
+    try {
+      await this._send('/api/webhooks/agent/routes', {
+        appName: this.config.appName,
+        routes,
+        discoveredAt: new Date().toISOString(),
+      });
+      this.log('Routes reported to Sentinelle');
+    } catch (err) {
+      this.log(`Failed to report routes: ${err.message}`);
+    }
+  }
+
+  /**
+   * Send heartbeat with system info and metrics
+   */
+  async sendHeartbeat() {
+    if (!this.running) return;
+
+    const memUsage = process.memoryUsage();
+    const uptime = process.uptime();
+
+    const payload = {
+      appName: this.config.appName,
+      status: 'alive',
+      uptime: Math.round(uptime),
+      memory: {
+        rss: Math.round(memUsage.rss / 1048576), // MB
+        heapUsed: Math.round(memUsage.heapUsed / 1048576),
+        heapTotal: Math.round(memUsage.heapTotal / 1048576),
+      },
+      system: this.systemInfo,
+      metrics: {
+        totalRequests: this.requestMetrics.total,
+        avgResponseMs: this.requestMetrics.avgResponseMs,
+        errors5xx: this.requestMetrics.errors5xx,
+        errors4xx: this.requestMetrics.errors4xx,
+        topRoutes: this._getTopRoutes(5),
+        statusDistribution: this.requestMetrics.byStatus,
+      },
+      routeCount: this.discoveredRoutes.length,
+      timestamp: new Date().toISOString(),
+    };
+
+    try {
+      const response = await this._send('/api/webhooks/agent/heartbeat', payload);
+      this.log('Heartbeat sent');
+      this._applyServerDirectives(response);
+    } catch (err) {
+      this.log(`Heartbeat failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Applique les directives renvoyées par le backend (kill switch, etc.)
+   */
+  _applyServerDirectives(response) {
+    if (!response || typeof response !== 'object') return;
+    const wasActive = this.killSwitchActive;
+    this.killSwitchActive = !!response.kill_switch_active;
+    if (this.killSwitchActive && !wasActive) {
+      this.killSwitchSince = new Date().toISOString();
+      this.log('🛑 Kill switch activé par le serveur — pause envoi d\'erreurs');
+    } else if (!this.killSwitchActive && wasActive) {
+      this.killSwitchSince = null;
+      this.log('Kill switch relâché — reprise normale');
+    }
+  }
+
+  /**
+   * Flush error buffer to Sentinelle
+   */
+  async flushErrors() {
+    if (this.errors.length === 0) return;
+
+    if (this.killSwitchActive) {
+      // On garde les erreurs en buffer (cap à 1000 pour éviter fuite mémoire)
+      // et on attend la levée du kill switch.
+      if (this.errors.length > 1000) {
+        this.errors.splice(0, this.errors.length - 1000);
+      }
+      this.log(`Kill switch actif — ${this.errors.length} erreur(s) en attente`);
+      return;
+    }
+
+    const batch = this.errors.splice(0, this.errors.length);
+
+    try {
+      await this._send('/api/webhooks/agent/errors', {
+        appName: this.config.appName,
+        errors: batch,
+        timestamp: new Date().toISOString(),
+      });
+      this.log(`Flushed ${batch.length} errors`);
+    } catch (err) {
+      // Put errors back if send failed
+      this.errors.unshift(...batch);
+      this.log(`Error flush failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Get top N routes by request count
+   */
+  _getTopRoutes(n) {
+    return Object.entries(this.requestMetrics.byRoute)
+      .map(([route, data]) => ({
+        route,
+        count: data.count,
+        avgMs: Math.round(data.totalMs / data.count),
+        errorRate: data.count > 0 ? Math.round((data.errors / data.count) * 100) : 0,
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, n);
+  }
+
+  /**
+   * Send data to Sentinelle server
+   */
+  async _send(path, data) {
+    const url = this.config.serverUrl + path;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10000);
+
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Sentinelle-Key': this.config.apiKey,
+          'User-Agent': `sentinelle-agent/1.0.0 (${this.config.appName})`,
+        },
+        body: JSON.stringify(data),
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+      }
+
+      return await res.json();
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+module.exports = { AgentCore };

package/src/express.js

@@ -0,0 +1,140 @@
+/**
+ * Express.js integration — middleware, error handler, and route discovery
+ */
+
+/**
+ * Request tracking middleware — captures response time, status codes, and request metadata
+ * Add BEFORE your routes: app.use(sentinelle.middleware())
+ */
+const expressMiddleware = (agent) => {
+  return (req, res, next) => {
+    const start = process.hrtime.bigint();
+
+    // Capture response finish
+    const originalEnd = res.end;
+    res.end = function (...args) {
+      const end = process.hrtime.bigint();
+      const responseMs = Number(end - start) / 1_000_000;
+
+      // Track request
+      agent.trackRequest({
+        method: req.method,
+        path: req.originalUrl || req.url,
+        route: req.route?.path || req.originalUrl || req.url,
+        statusCode: res.statusCode,
+        responseMs: Math.round(responseMs),
+        ip: req.ip || req.connection?.remoteAddress,
+        userAgent: req.headers['user-agent'],
+        timestamp: new Date().toISOString(),
+      });
+
+      originalEnd.apply(this, args);
+    };
+
+    next();
+  };
+};
+
+/**
+ * Error handler middleware — captures unhandled errors in routes
+ * Add AFTER your routes: app.use(sentinelle.errorHandler())
+ */
+const expressErrorHandler = (agent) => {
+  return (err, req, res, next) => {
+    // Report the error to Sentinelle
+    agent.reportError({
+      type: err.name || 'Error',
+      message: err.message,
+      stack: err.stack,
+      method: req.method,
+      path: req.originalUrl || req.url,
+      route: req.route?.path,
+      statusCode: err.status || err.statusCode || 500,
+      ip: req.ip || req.connection?.remoteAddress,
+      userAgent: req.headers['user-agent'],
+      body: req.method !== 'GET' ? sanitizeBody(req.body) : undefined,
+      query: Object.keys(req.query || {}).length > 0 ? req.query : undefined,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Don't swallow the error — pass it to the next handler
+    next(err);
+  };
+};
+
+/**
+ * Sanitize request body — remove sensitive fields
+ */
+const sanitizeBody = (body) => {
+  if (!body || typeof body !== 'object') return undefined;
+
+  const sensitiveKeys = ['password', 'token', 'secret', 'authorization', 'cookie', 'credit_card', 'card_number', 'cvv', 'ssn'];
+  const sanitized = { ...body };
+
+  for (const key of Object.keys(sanitized)) {
+    if (sensitiveKeys.some(s => key.toLowerCase().includes(s))) {
+      sanitized[key] = '[REDACTED]';
+    }
+  }
+
+  return sanitized;
+};
+
+/**
+ * Discover all registered Express routes
+ * Call after all routes are registered: sentinelle.discoverRoutes(app)
+ */
+const discoverExpressRoutes = (app) => {
+  const routes = [];
+
+  const extractRoutes = (stack, prefix = '') => {
+    if (!stack) return;
+
+    for (const layer of stack) {
+      if (layer.route) {
+        // Direct route
+        const methods = Object.keys(layer.route.methods)
+          .filter(m => layer.route.methods[m])
+          .map(m => m.toUpperCase());
+
+        for (const method of methods) {
+          routes.push({
+            method,
+            path: prefix + layer.route.path,
+          });
+        }
+      } else if (layer.name === 'router' && layer.handle?.stack) {
+        // Nested router
+        const routerPrefix = layer.regexp
+          ? extractPrefix(layer.regexp)
+          : '';
+        extractRoutes(layer.handle.stack, prefix + routerPrefix);
+      }
+    }
+  };
+
+  // Try to access Express internal router stack
+  if (app._router?.stack) {
+    extractRoutes(app._router.stack);
+  }
+
+  return routes;
+};
+
+/**
+ * Extract prefix path from Express regex
+ */
+const extractPrefix = (regexp) => {
+  if (!regexp) return '';
+  const str = regexp.toString();
+
+  // Match patterns like /^\/api\/?(?=\/|$)/i
+  const match = str.match(/^\/\^(\\\/[^?*+{(|]+)/);
+  if (match) {
+    return match[1].replace(/\\\//g, '/');
+  }
+
+  return '';
+};
+
+module.exports = { expressMiddleware, expressErrorHandler, discoverExpressRoutes };

package/src/index.js

@@ -0,0 +1,95 @@
+const { AgentCore } = require('./core');
+const { expressMiddleware, expressErrorHandler, discoverExpressRoutes } = require('./express');
+
+/**
+ * Sentinelle Agent — install in your Node.js app for automatic monitoring
+ *
+ * Usage:
+ *   const devguard = require('sentinelle-agent');
+ *
+ *   // Initialize
+ *   sentinelle.init({
+ *     apiKey: 'your-project-api-key',
+ *     serverUrl: 'http://localhost:4000',  // Sentinelle server
+ *     appName: 'my-app',
+ *   });
+ *
+ *   // Express middleware (add BEFORE routes)
+ *   app.use(sentinelle.middleware());
+ *
+ *   // Express error handler (add AFTER routes)
+ *   app.use(sentinelle.errorHandler());
+ *
+ *   // Auto-discover routes (call after all routes are registered)
+ *   sentinelle.discoverRoutes(app);
+ */
+
+let agent = null;
+
+const init = (options = {}) => {
+  if (agent) {
+    console.warn('[Sentinelle] Agent already initialized');
+    return agent;
+  }
+
+  const config = {
+    apiKey: options.apiKey || process.env.SENTINELLE_API_KEY,
+    serverUrl: (options.serverUrl || process.env.SENTINELLE_SERVER_URL || 'http://localhost:4000').replace(/\/$/, ''),
+    appName: options.appName || process.env.SENTINELLE_APP_NAME || 'unknown',
+    heartbeatInterval: options.heartbeatInterval || 60000, // 1 min
+    captureUnhandled: options.captureUnhandled !== false,
+    debug: options.debug || false,
+  };
+
+  if (!config.apiKey) {
+    console.error('[Sentinelle] API key required. Set apiKey option or SENTINELLE_API_KEY env var.');
+    return null;
+  }
+
+  agent = new AgentCore(config);
+  agent.start();
+
+  return agent;
+};
+
+const middleware = () => {
+  return (req, res, next) => {
+    if (!agent) return next();
+    return expressMiddleware(agent)(req, res, next);
+  };
+};
+
+const errorHandler = () => {
+  return (err, req, res, next) => {
+    if (!agent) return next(err);
+    return expressErrorHandler(agent)(err, req, res, next);
+  };
+};
+
+const discoverRoutes = (app) => {
+  if (!agent) {
+    console.warn('[Sentinelle] Agent not initialized. Call sentinelle.init() first.');
+    return;
+  }
+  const routes = discoverExpressRoutes(app);
+  agent.reportRoutes(routes);
+  return routes;
+};
+
+const getAgent = () => agent;
+
+const shutdown = async () => {
+  if (agent) {
+    await agent.stop();
+    agent = null;
+  }
+};
+
+module.exports = {
+  init,
+  middleware,
+  errorHandler,
+  discoverRoutes,
+  getAgent,
+  shutdown,
+};