@contrast/agent-bundle 5.46.0 → 5.47.0

package/node_modules/@contrast/route-coverage/lib/index.js

@@ -15,7 +15,11 @@
 // @ts-check
 'use strict';
 
-const { callChildComponentMethodsSync, Event } = require('@contrast/common');
+const {
+  callChildComponentMethodsSync,
+  Event,
+  RouteType,
+} = require('@contrast/common');
 
 /**
  * @param {import('.').Core & {
@@ -41,6 +45,8 @@ module.exports = function init(core) {
       const id = routeIdentifier(info.method, info.signature);
       if (routeInfo.get(id)) return;
 
+      if (!info.type) info.type = RouteType.HTTP;
+
       logger.trace({ info }, 'Discovered new route:');
       routeInfo.set(id, info);
     },
@@ -100,9 +106,11 @@ module.exports = function init(core) {
 
       recentlyObserved.add(route.signature);
       logger.trace({ info }, 'Observed route:');
+
       // these events need source correlation
       messages.emit(Event.ROUTE_COVERAGE_OBSERVATION, {
         ...route,
+        type: info.type ?? route.type ?? RouteType.HTTP,
         sourceInfo: store?.sourceInfo,
       });
     },
@@ -119,6 +127,7 @@ module.exports = function init(core) {
   require('./install/hapi')(core);
   require('./install/koa')(core);
   require('./install/restify')(core);
+  core.initComponentSync(require('./install/socket.io'));
 
   messages.on(Event.SERVER_LISTENING, () => {
     // we wait to report in timers event loop phase, this way we can

package/node_modules/@contrast/route-coverage/lib/install/express/express5.js

@@ -20,6 +20,7 @@ const {
   set,
   isString,
   Event,
+  RouteType,
   primordials: {
     ArrayPrototypeJoin,
     StringPrototypeSubstring,
@@ -310,12 +311,14 @@ class ExpressInstrumentation {
                   const method = StringPrototypeToLowerCase.call(data.args[0].method || '');
                   const template = ArrayPrototypeJoin.call(store.templateSegments, '') || '/';
 
+
                   if (instance[kMetaKey]?.observables?.[template]) {
                     self.observe({
                       url: data.args[0].originalUrl,
                       normalizedUrl: template,
                       method,
                       signature: instance[kMetaKey].observables[template],
+                      type: instance[kMetaKey].routeType,
                     });
                   } else {
                     core.logger.error({
@@ -335,7 +338,7 @@ class ExpressInstrumentation {
   }
 
   discover(info) {
-    const { method, observables } = info;
+    const { method, observables, routeType } = info;
     if (!method || !observables) return;
 
     for (const [normalizedUrl, signature] of Object.entries(observables)) {
@@ -344,6 +347,7 @@ class ExpressInstrumentation {
         normalizedUrl,
         method,
         signature,
+        type: routeType,
         framework: 'express',
       });
     }
@@ -383,11 +387,22 @@ class ExpressInstrumentation {
       // mounted routers aren't discoverable since they themselves don't
       // represent routes, they dispatch to sub routers/route handlers.
       if (value.name != 'router' && value.handle?.name != 'router') {
+        let routeType;
+        if (value[kMetaKey]?.method == 'use') {
+          // if the handler is registered via `use` method, there are no
+          // associated HTTP methods. this use case is considered middleware.
+          if (!this.core.config.getEffectiveValue('assess.report_middleware_routes')) return;
+          routeType = RouteType.MIDDLEWARE;
+        } else {
+          routeType = RouteType.HTTP;
+        }
+
         // `value` is a terminal Layer with observable signatures.
         // emit discovery after appending metadata.
         if (value[kMetaKey]) {
           const observables = this.generateObservables(metas, value.handle);
           if (observables) {
+            value[kMetaKey].routeType = routeType;
             if (!value[kMetaKey].observables) {
               value[kMetaKey].observables = observables;
             } else {

package/node_modules/@contrast/route-coverage/lib/install/fastify.js

@@ -15,7 +15,10 @@
 'use strict';
 
 const { getFastifyMethods } = require('../utils/methods');
-const { primordials: { StringPrototypeToLowerCase, StringPrototypeSplit } } = require('@contrast/common');
+const {
+  primordials: { StringPrototypeToLowerCase, StringPrototypeSplit },
+  RouteType,
+} = require('@contrast/common');
 const { patchType } = require('./../utils/route-info');
 
 // Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Fastify
@@ -35,7 +38,7 @@ module.exports = function init(core) {
     return route?.[kRoutePrefix];
   }
 
-  function createRouteInfo(method, url, fullyDeclared) {
+  function createRouteInfo(method, url, fullyDeclared, type) {
     method = StringPrototypeToLowerCase.call(method);
 
     const signature = fullyDeclared
@@ -47,6 +50,7 @@ module.exports = function init(core) {
       url,
       method,
       normalizedUrl: url,
+      type,
       framework: 'fastify'
     };
     return routeInfo;
@@ -54,14 +58,18 @@ module.exports = function init(core) {
 
   function patchHandler(route, handle, routeInfo) {
     const pre = ({ args }) => {
-      const [req] = args;
-
-      // todo(NODE-3793): support for @fastify/websocket
-      if (req.constructor.name == 'WebSocket') return;
-
+      let req, type;
+      if (args[0]?.constructor?.name == 'WebSocket') {
+        req = args[1];
+        type = RouteType.MESSAGE_BROKER;
+      } else {
+        req = args[0];
+        type = RouteType.HTTP;
+      }
       const method = StringPrototypeToLowerCase.call(req.raw?.method);
       const [url] = StringPrototypeSplit.call(req.url, /\?/);
-      routeCoverage.observe({ ...routeInfo, url, method });
+
+      routeCoverage.observe({ ...routeInfo, method, type, url });
     };
 
     const name = `fastify.route.${handle}`;
@@ -81,24 +89,26 @@ module.exports = function init(core) {
     }
   }
 
-  function discoverAndPatch(method, path, handler, handle, methods, fullyDeclared) {
+  function discoverAndPatch(method, path, routeObj, handle, methods, fullyDeclared) {
+    const type = routeObj?.options?.websocket ? RouteType.MESSAGE_BROKER : RouteType.HTTP;
+
     if (Array.isArray(method)) {
       // If all valid methods are included in `method` then .all shorthand was most likely used
       if (methods.every(m => method.includes(m))) {
-        const routeInfo = createRouteInfo('all', path, fullyDeclared);
+        const routeInfo = createRouteInfo('all', path, fullyDeclared, type);
         routeCoverage.discover(routeInfo);
-        patchHandler(handler, handle, routeInfo);
+        patchHandler(routeObj, handle, routeInfo);
       } else {
         method.forEach((verb) => {
-          const routeInfo = createRouteInfo(verb, path, fullyDeclared);
+          const routeInfo = createRouteInfo(verb, path, fullyDeclared, type);
           routeCoverage.discover(routeInfo);
-          patchHandler(handler, handle, routeInfo);
+          patchHandler(routeObj, handle, routeInfo);
         });
       }
     } else {
-      const routeInfo = createRouteInfo(method, path, fullyDeclared);
+      const routeInfo = createRouteInfo(method, path, fullyDeclared, type);
       routeCoverage.discover(routeInfo);
-      patchHandler(handler, handle, routeInfo);
+      patchHandler(routeObj, handle, routeInfo);
     }
   }
 

package/node_modules/@contrast/route-coverage/lib/install/graphql.js

@@ -14,7 +14,10 @@
  */
 'use strict';
 
-const { primordials: { ArrayPrototypeJoin } } = require('@contrast/common');
+const {
+  RouteType,
+  primordials: { ArrayPrototypeJoin },
+} = require('@contrast/common');
 const { patchType } = require('./../utils/route-info');
 
 module.exports = function init(core) {
@@ -61,6 +64,7 @@ module.exports = function init(core) {
             method,
             normalizedUrl,
             signature,
+            type: RouteType.HTTP, // todo: extend existing types
             framework: 'graphql',
           });
         });
@@ -77,6 +81,7 @@ module.exports = function init(core) {
                 method: store.sourceInfo?.method,
                 normalizedUrl,
                 signature,
+                type: RouteType.HTTP, // todo: extend existing types
                 url: normalizedUrl,
                 framework: 'graphql',
               });

package/node_modules/@contrast/route-coverage/lib/install/koa.js

@@ -36,7 +36,7 @@ module.exports = function init(core) {
 
   return core.routeCoverage.koa = {
     install() {
-      depHooks.resolve({ name: 'koa', version: '>=2.3.0 <3' }, (Koa) => {
+      depHooks.resolve({ name: 'koa', version: '>=2.3.0 <4' }, (Koa) => {
         // Koa uses its own routing library @koa/router to define routes before
         // mounting them on the app with .use so instrumenting use and traversing
         // the constructed routes is the more technically correct approach than

package/node_modules/@contrast/route-coverage/lib/install/socket.io.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright: 2025 Contrast Security, Inc
+ * Contact: support@contrastsecurity.com
+ * License: Commercial
+
+ * NOTICE: This Software and the patented inventions embodied within may only be
+ * used as part of Contrast Security’s commercial offerings. Even though it is
+ * made available through public repositories, use of this Software is subject to
+ * the applicable End User Licensing Agreement found at
+ * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
+ * between Contrast Security and the End User. The Software may not be reverse
+ * engineered, modified, repackaged, sold, redistributed or otherwise used in a
+ * way not consistent with the End User License Agreement.
+ */
+'use strict';
+
+const { set, RouteType, primordials } = require('@contrast/common');
+const Core = require('@contrast/core/lib/ioc/core');
+const { patchType } = require('../utils/route-info');
+
+const COMPONENT_NAME = 'routeCoverage.socketio';
+const FRAMEWORK = 'socket.io';
+const kServerMountPath = Symbol('cs:socket.io.path');
+const kServerRouteSignature = Symbol('cs:socket.io.route-signature');
+
+module.exports = Core.makeComponent({
+  name: COMPONENT_NAME,
+  factory: (core) => new SocketIORouteCoverage(core),
+});
+
+class SocketIORouteCoverage {
+  constructor(core) {
+    Object.defineProperty(this, 'core', { value: core });
+    set(core, COMPONENT_NAME, this);
+  }
+
+  makePath(mountPath) {
+    // we append trailing "/" since that's part of socket.io protocol
+    return mountPath.endsWith('/') ? mountPath : `${mountPath}/`;
+  }
+
+  makeSignature(mountPath) {
+    return `Socket.IO ${mountPath}`;
+  }
+
+  install() {
+    const self = this;
+    const {
+      depHooks,
+      patcher,
+      routeCoverage,
+    } = this.core;
+
+    depHooks.resolve(
+      { name: 'socket.io', version: '4' },
+      /** @param {import('socket.io-4')} xport the exported socket.io module */
+      (xport) => {
+        patcher.patch(xport.Server.prototype, 'initEngine', {
+          name: 'socket.io.Server.prototype.initEngine',
+          patchType,
+          post(data) {
+            if (!this._path) return;
+            const [httpServer] = data.args;
+            const path = self.makePath(this._path);
+            const signature = self.makeSignature(path);
+
+            this.eio[kServerMountPath] = path;
+            this.eio[kServerRouteSignature] = signature;
+
+            routeCoverage.discover({
+              framework: FRAMEWORK,
+              signature,
+              method: 'all',
+              normalizedUri: path,
+              type: RouteType.MESSAGE_BROKER,
+              url: path,
+            });
+
+            // handle observation for HTTP polling; this doesn't emit when upgrading to ws://
+            httpServer.on(
+              'request',
+              /** @param {import('http').IncomingMessage} req */
+              (req /*, res */) => {
+                if (req.url?.startsWith?.(path)) {
+                  routeCoverage.observe({
+                    framework: FRAMEWORK,
+                    method: primordials.StringPrototypeToLowerCase.call(req.method),
+                    normalizedUrl: path,
+                    signature,
+                    type: RouteType.MESSAGE_BROKER,
+                    url: path,
+                  });
+                }
+              });
+          }
+        });
+      }
+    );
+
+    // this is to handle observations for websocket upgrades; 1 upgrade request counts as single observation
+    depHooks.resolve(
+      { name: 'engine.io', version: '6' },
+      /** @param {import('engine.io')} xport the exported engine.io module */
+      (xport) => {
+        patcher.patch(xport.Server.prototype, 'onWebSocket', {
+          name: 'engine.io.Server.prototype.onWebSocket',
+          patchType,
+          pre(data) {
+            const eioServer = this;
+            const [req] = data.args;
+
+            if (!eioServer[kServerMountPath] || !eioServer[kServerRouteSignature]) return;
+
+            routeCoverage.observe({
+              framework: FRAMEWORK,
+              method: req.method,
+              normalizedUrl: eioServer[kServerMountPath],
+              signature: eioServer[kServerRouteSignature],
+              type: RouteType.MESSAGE_BROKER,
+              url: eioServer[kServerMountPath],
+            });
+          },
+        });
+      }
+    );
+  }
+}

package/node_modules/@contrast/route-coverage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Handles route discovery and observation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -20,14 +20,14 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.37.0",
-    "@contrast/config": "1.53.0",
-    "@contrast/core": "1.58.0",
-    "@contrast/dep-hooks": "1.27.0",
+    "@contrast/common": "1.38.0",
+    "@contrast/config": "1.54.0",
+    "@contrast/core": "1.59.0",
+    "@contrast/dep-hooks": "1.28.0",
     "@contrast/fn-inspect": "^5.0.2",
-    "@contrast/logger": "1.31.0",
-    "@contrast/patcher": "1.30.0",
-    "@contrast/scopes": "1.28.0",
+    "@contrast/logger": "1.32.0",
+    "@contrast/patcher": "1.31.0",
+    "@contrast/scopes": "1.29.0",
     "semver": "^7.6.0"
   }
 }

package/node_modules/@contrast/scopes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/scopes",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Handles AsyncLocalStorage scopes",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -20,9 +20,9 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/core": "1.58.0",
-    "@contrast/dep-hooks": "1.27.0",
-    "@contrast/logger": "1.31.0",
-    "@contrast/patcher": "1.30.0"
+    "@contrast/core": "1.59.0",
+    "@contrast/dep-hooks": "1.28.0",
+    "@contrast/logger": "1.32.0",
+    "@contrast/patcher": "1.31.0"
   }
 }

package/node_modules/@contrast/sec-obs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/sec-obs",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Contrast service providing framework-agnostic Observability support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -17,14 +17,14 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.37.0",
-    "@contrast/config": "1.53.0",
-    "@contrast/core": "1.58.0",
-    "@contrast/dep-hooks": "1.27.0",
-    "@contrast/logger": "1.31.0",
-    "@contrast/patcher": "1.30.0",
-    "@contrast/rewriter": "1.35.0",
-    "@contrast/scopes": "1.28.0",
+    "@contrast/common": "1.38.0",
+    "@contrast/config": "1.54.0",
+    "@contrast/core": "1.59.0",
+    "@contrast/dep-hooks": "1.28.0",
+    "@contrast/logger": "1.32.0",
+    "@contrast/patcher": "1.31.0",
+    "@contrast/rewriter": "1.36.0",
+    "@contrast/scopes": "1.29.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.57.1",
     "@opentelemetry/exporter-trace-otlp-http": "^0.57.1",

package/node_modules/@contrast/sources/lib/index.js

@@ -23,6 +23,11 @@ const NormalizedUriMapper = require('./normalized-uri-mapper');
 const { HttpSourceInfo } = require('./source-info');
 
 const componentName = 'sources';
+const SourceType = {
+  HTTP: 'HTTP',
+  WEBSOCKET: 'WEBSOCKET',
+};
+
 
 module.exports = Core.makeComponent({
   name: componentName,
@@ -48,20 +53,40 @@ class Sources {
     const { _hooks, _normalizedUriMapper, core } = this;
 
     return function (next, data) {
-      const { args: [event, req, res] } = data;
-
-      if (event !== 'request') {
-        if (event === 'listening') {
-          // take a snapshot of Perf.all at this point. this will get logged
-          // at some point on the perf interval timer.
-          core.Perf.mark('listening');
-          core.messages.emit(Event.SERVER_LISTENING, { type: serverType, server: data.obj });
-        }
+      const { args: [event, req, resOrSocket] } = data;
+
+      if (event === 'listening') {
+        // take a snapshot of Perf.all at this point. this will get logged
+        // at some point on the perf interval timer.
+        core.Perf.mark('listening');
+        core.messages.emit(Event.SERVER_LISTENING, { type: serverType, server: data.obj });
         return next();
       }
 
-      core.Perf.requestCount += 1;
+      const isUpgrade = event === 'upgrade';
+      let protocol = serverType == 'http' ? 'http' : 'https';
+
+      if (isUpgrade) {
+        for (let i = 0; i < req.rawHeaders.length; i += 2) {
+          if (req.rawHeaders[i].toLowerCase?.() == 'upgrade') {
+            protocol = req.rawHeaders[i + 1]?.toLowerCase?.();
+            break;
+          }
+        }
+      }
+
+      // For HTTP servers we run the "request" and "upgrade" events in a source
+      // scope. We only support "websocket" upgrades currently, but this can be
+      // extended. Support for non-HTTP sources is expected and will require new
+      // instrumentation and possibly model alterations.
+      if (
+        event !== 'request' &&
+        (!isUpgrade || (isUpgrade && protocol !== 'websocket'))
+      ) {
+        return next();
+      }
 
+      // websocket sources are http
       const sourceInfo = new HttpSourceInfo({
         serverType,
         raw: req,
@@ -69,20 +94,38 @@ class Sources {
       });
       const store = { sourceInfo };
 
-      onFinished(res, (/* err, req */) => {
-        core.messages.emit(Event.RESPONSE_FINISH, store);
-      });
+      if (isUpgrade) {
+        core.patcher.patch(resOrSocket, 'emit', {
+          name: `${serverType}.socket.emit`,
+          patchType: 'sources',
+          around(next) {
+            return core.scopes.sources.run(store, next);
+          },
+        });
+      } else {
+        onFinished(resOrSocket, (/* err, req */) => {
+          core.messages.emit(Event.RESPONSE_FINISH, store);
+        });
+      }
+
+      core.Perf.requestCount += 1;
 
       return core.scopes.sources.run(store, () => {
-        if (_hooks._events.onSource) {
-          _hooks.emit('onSource', {
-            // future: non-http sources will have their own type
-            sourceType: 'HTTP',
-            store,
-            incomingMessage: req,
-            serverResponse: res,
-          });
-        }
+        const sourceType = protocol == 'websocket' ? SourceType.WEBSOCKET : SourceType.HTTP;
+        const eventArg = {
+          sourceType,
+          store,
+          incomingMessage: req,
+        };
+
+        if (sourceType == SourceType.HTTP)
+          eventArg.serverResponse = resOrSocket;
+
+        else if (sourceType == SourceType.WEBSOCKET)
+          eventArg.socket = resOrSocket;
+
+        if (_hooks._events.onSource)
+          _hooks.emit('onSource', eventArg);
 
         return next();
       });