@newrelic/security-agent 3.0.4 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+### v4.0.0 (2026-11-03)
+### ⚠ BREAKING CHANGES
+* Dropped support for Node.js v20.x
+
+#### Features
+* Added Node 26.x support and removed 20.x, updated CI matrix and fs callback hooks (#379)
+
+#### Miscellaneous chores
+* Updated Readme (#381)
+
+### v3.0.5 (2026-10-29)
+#### Bug fixes
+* Subscribe to agent mongodb channels instead of wrapping prototypes (#375)
+* Delegate wrapped mongodb methods to the prototype at call time (#376)
+
+#### Miscellaneous chores
+* bump undici to 7.30.1 and ws to 8.22.0 (#377)
+
 ### v3.0.4 (2026-05-14)
 #### Bug fixes
 * remove dependency on uuid module (#357)

package/README.md

@@ -42,7 +42,7 @@ The `@newrelic/security-agent` must be explicitly enabled in order to perform IA
 The [Developer docs](http://newrelic.github.io/node-newrelic/) for writing instrumentation will be of help. We particularly recommend the [tutorials](https://newrelic.github.io/node-newrelic/tutorial-Instrumentation-Basics.html) and the [shim API](https://newrelic.github.io/node-newrelic/Shim.html) documentation.
 
 ### Supported  Node.js Versions
-- Node version 20.x, 22.x and 24.x
+- Node version 22.x, 24.x and 26.x
 
 ### Supported  Modules
 

package/lib/instrumentation-security/hooks/fs/nr-fs.js

@@ -57,6 +57,13 @@ let functionProbableToFI = [
   "mkdir",
 ];
 
+// Node 26+ callback readFile/writeFile/appendFile no longer go through binding.open,
+// so the open hook misses them. Older versions still do; wrapping there would double-report.
+if (semver.satisfies(process.version, '>=26.0.0')) {
+  functionsProbableToFA.push("readFile");
+  functionProbableToFI.push("writeFile", "appendFile");
+}
+
 const promiseFunctionsProbableToFA = [
   "open",
   "readdir",

package/lib/instrumentation-security/hooks/mongodb/common.js

@@ -7,6 +7,7 @@
 
 /* eslint sonarjs/cognitive-complexity: ["error", 18] -- TODO: https://issues.newrelic.com/browse/NEWRELIC-5252 */
 
+const diagnosticsChannel = require("diagnostics_channel");
 const { CURSOR_OPS, COLLECTION_OPS, DB_OPS } = require("./constants");
 const common = module.exports;
 const requestManager = require("../../core/request-manager");
@@ -18,6 +19,30 @@ const { EVENT_TYPE, EVENT_CATEGORY } = require('../../core/event-constants');
 const { NR_CSEC_FUZZ_REQUEST_ID } = require('../../core/constants');
 const logger = API.getLogger();
 
+// Prefix for the newrelic agent's mongodb tracing channels. The agent publishes
+// one tracing channel per instrumented mongodb class; subscribing to these lets
+// us attach to constructed instances without reassigning prototype methods.
+const AGENT_MONGODB_CHANNEL_PREFIX = "orchestrion:mongodb:";
+// Marks an instance whose methods we have already wrapped, so repeated channel
+// events for the same object do not double-wrap.
+const CSEC_MONGO_INSTANCE_HOOKED = Symbol("csecMongoInstanceHooked");
+// Tracks the active subscription handlers per agent channel. The mongodb hook
+// can run more than once in a process (e.g. the newrelic agent being unloaded
+// and re-instrumented), each time with a fresh `shim`. The tracing channel is
+// process-global, so on each run we must remove the previous subscription
+// (bound to the old `shim`) before adding a new one, otherwise we stack
+// duplicate subscribers that serve a stale `shim`.
+//
+// This registry must live on `globalThis`, not in a module-scoped variable:
+// this file's path contains "mongodb", so test/require-cache busters that evict
+// modules matching "mongodb" would reload this module and reset a module-scoped
+// Map — losing the handle needed to unsubscribe the still-live prior
+// subscription. Keyed by full channel name -> handlers object.
+const CHANNEL_SUBSCRIPTIONS_KEY = Symbol.for("newrelic.csec.mongodb.channelSubscriptions");
+const channelSubscriptions =
+  globalThis[CHANNEL_SUBSCRIPTIONS_KEY] ||
+  (globalThis[CHANNEL_SUBSCRIPTIONS_KEY] = new Map());
+
 function methodChecker(data) {
   data = data.toLowerCase();
   if (data.includes("delete")) {
@@ -53,52 +78,200 @@ function payloadType(obj) {
 
 }
 
-function queryHook(shim, mod, method) {
-  shim.wrap(mod, method, function makeQueryWrapper(shim, fn) {
-    logger.debug(`Instrumenting mongodb.${method}`);
-    return function queryWrapper() {
-      const request = requestManager.getRequest(shim);
-      if (CURSOR_OPS.includes(method)) {
-        if (!this.mongo_sec_hooked && this.operation && this.operation.cmd) {
-          const pType = payloadType(this.operation.cmd);
-          const payloadData = {
-            payloadType: pType,
-            payload: this.operation.cmd,
-          };
-          shim.interceptedArgs = payloadData;
-        }
-      } else {
-        this.mongo_sec_hooked = true;
-
-        const pType = methodChecker(method);
+/**
+ * Builds the security wrapper for a mongodb operation. The returned function
+ * reads the operation payload, generates the NoSQL security event, and (for
+ * fuzz requests) hooks the callback, then delegates to the original method.
+ *
+ * This is shared by both attachment strategies: the legacy prototype wrap
+ * (`queryHook`, used for mongodb < 4 where the newrelic agent does not provide
+ * subscriber based instrumentation) and the per-instance attachment
+ * (`instrumentInstance`, used for mongodb >= 4 so we do not reassign a
+ * prototype method already instrumented by the newrelic agent).
+ *
+ * @param {Shim} shim
+ * @param {string} method name of the operation being wrapped
+ * @param {Function} fn the original method
+ * @returns {Function} the wrapped method
+ */
+function makeQueryWrapper(shim, method, fn) {
+  return function queryWrapper() {
+    const request = requestManager.getRequest(shim);
+    if (CURSOR_OPS.includes(method)) {
+      if (!this.mongo_sec_hooked && this.operation && this.operation.cmd) {
+        const pType = payloadType(this.operation.cmd);
         const payloadData = {
           payloadType: pType,
-          payload: arguments,
+          payload: this.operation.cmd,
         };
         shim.interceptedArgs = payloadData;
-
       }
+    } else {
+      this.mongo_sec_hooked = true;
 
-      try {
-        if (request) {
-          //generate event here
-          const traceObject = secUtils.getTraceObject(shim);
-          const secMetadata = securityMetaData.getSecurityMetaData(request, JSON.parse(JSON.stringify(shim.interceptedArgs)), traceObject, secUtils.getExecutionId(), EVENT_TYPE.NOSQL_DB_COMMAND, EVENT_CATEGORY.MONGO)
-          const secEvent = API.generateSecEvent(secMetadata);
-          API.sendEvent(secEvent);
-          if (request.headers[NR_CSEC_FUZZ_REQUEST_ID]) {
-            callbackHook(shim, arguments, arguments.length - 1, secEvent);
-          }
+      const pType = methodChecker(method);
+      const payloadData = {
+        payloadType: pType,
+        payload: arguments,
+      };
+      shim.interceptedArgs = payloadData;
+
+    }
+
+    try {
+      if (request) {
+        //generate event here
+        const traceObject = secUtils.getTraceObject(shim);
+        const secMetadata = securityMetaData.getSecurityMetaData(request, JSON.parse(JSON.stringify(shim.interceptedArgs)), traceObject, secUtils.getExecutionId(), EVENT_TYPE.NOSQL_DB_COMMAND, EVENT_CATEGORY.MONGO)
+        const secEvent = API.generateSecEvent(secMetadata);
+        API.sendEvent(secEvent);
+        if (request.headers[NR_CSEC_FUZZ_REQUEST_ID]) {
+          callbackHook(shim, arguments, arguments.length - 1, secEvent);
         }
-      } catch (error) {
       }
-      
+    } catch (error) {
+    }
 
-      return fn.apply(this, arguments);
-    };
+
+    return fn.apply(this, arguments);
+  };
+}
+
+function queryHook(shim, mod, method) {
+  shim.wrap(mod, method, function wrapQuery(shim, fn) {
+    logger.debug(`Instrumenting mongodb.${method}`);
+    return makeQueryWrapper(shim, method, fn);
+  });
+}
+
+/**
+ * Attaches the security wrapper to a single mongodb instance (a `Collection`,
+ * cursor, etc.) as an own property, leaving the class prototype untouched.
+ *
+ * The newrelic agent (>= the release that instruments mongodb via
+ * `diagnostics_channel`) reassigns the driver prototype methods. If we also
+ * wrapped the prototype, the two reassignments would clobber one another and
+ * the agent's datastore instrumentation would be lost. Wrapping the instance
+ * sits below the prototype, so both coexist. See
+ * https://github.com/newrelic/csec-node-agent/issues/374.
+ *
+ * @param {Shim} shim
+ * @param {object} instance a constructed mongodb object (e.g. a `Collection`)
+ * @param {string[]} methods operation names to wrap when present on `instance`
+ */
+function instrumentInstance(shim, instance, methods) {
+  if (!instance || instance[CSEC_MONGO_INSTANCE_HOOKED]) {
+    return;
+  }
+  // Guard so repeated channel events for the same instance do not re-wrap.
+  Object.defineProperty(instance, CSEC_MONGO_INSTANCE_HOOKED, {
+    value: true,
+    enumerable: false,
+    writable: true,
+    configurable: true
   });
+
+  const proto = Object.getPrototypeOf(instance);
+  for (let i = 0; i < methods.length; i++) {
+    const method = methods[i];
+    if (typeof instance[method] !== "function") {
+      continue;
+    }
+    logger.debug(`Instrumenting mongodb instance method ${method}`);
+    // Own property on the instance; does not touch the prototype. Delegate to
+    // the prototype method *lazily* (resolved at call time) rather than
+    // capturing it now: the newrelic agent wraps the prototype method on each
+    // (re-)instrumentation, so a value captured at construction time can go
+    // stale and bypass the agent's current wrapper. Reading it from the
+    // prototype at call time always runs whatever the agent currently has.
+    instance[method] = makeQueryWrapper(shim, method, function callProto() {
+      return proto[method].apply(this, arguments);
+    });
+  }
+}
+
+/**
+ * Subscribes to a newrelic agent mongodb construction tracing channel and
+ * attaches the security wrapper to each constructed instance. Returns false if
+ * the agent does not expose the channel (e.g. an older agent without
+ * subscriber based mongodb instrumentation), so callers can fall back to the
+ * legacy prototype wrapping.
+ *
+ * @param {Shim} shim
+ * @param {string} channelName the agent channel, e.g. `nr_collection`
+ * @param {string[]} methods operation names to wrap on each instance
+ * @returns {boolean} whether the channel subscription was established
+ */
+function subscribeToAgentChannel(shim, channelName, methods) {
+  const fullName = `${AGENT_MONGODB_CHANNEL_PREFIX}${channelName}`;
+  try {
+    const channel = diagnosticsChannel.tracingChannel(fullName);
+    // Only ride the agent's channel when the agent is actually instrumenting
+    // mongodb on it (it subscribes its own handler via `start`). If nothing is
+    // publishing here (e.g. an older newrelic agent without subscriber based
+    // mongodb instrumentation, or the agent disabled), report failure so the
+    // caller falls back to the legacy prototype wrapping. There is no colliding
+    // agent instrumentation in that case, so prototype wrapping is safe.
+    if (channel.start.hasSubscribers !== true) {
+      return false;
+    }
+    // Remove any prior subscription for this channel. On re-instrumentation the
+    // previous handlers closed over a now-stale `shim`; replacing them keeps a
+    // single live subscription bound to the current `shim`.
+    const previous = channelSubscriptions.get(fullName);
+    if (previous) {
+      channel.unsubscribe(previous);
+    }
+    const handlers = {
+      end(event) {
+        try {
+          instrumentInstance(shim, event && event.self, methods);
+        } catch (error) {
+          logger.debug(`Error instrumenting mongodb instance via ${channelName}`, error);
+        }
+      }
+    };
+    channel.subscribe(handlers);
+    channelSubscriptions.set(fullName, handlers);
+    return true;
+  } catch (error) {
+    logger.debug(`Could not subscribe to agent channel ${channelName}`, error);
+    return false;
+  }
 }
 
+/**
+ * Instruments cursor operations for mongodb >= 4 by subscribing to the newrelic
+ * agent's cursor construction channel and attaching to each instance. Falls
+ * back to the legacy prototype wrapping when the agent channel is unavailable.
+ *
+ * @param {Shim} shim
+ * @param {Cursor} [Cursor] cursor class, used only for the fallback path
+ */
+common.instrumentCursorViaChannel = function instrumentCursorViaChannel(shim, Cursor) {
+  const methods = CURSOR_OPS.concat(["each"]);
+  const subscribed = subscribeToAgentChannel(shim, "nr_cursor", methods);
+  if (!subscribed) {
+    common.instrumentCursor(shim, Cursor);
+  }
+};
+
+/**
+ * Instruments collection operations for mongodb >= 4 by subscribing to the
+ * newrelic agent's collection construction channel and attaching to each
+ * instance. Falls back to the legacy prototype wrapping when the agent channel
+ * is unavailable.
+ *
+ * @param {Shim} shim
+ * @param {Collection} [Collection] collection class, used only for the fallback path
+ */
+common.instrumentCollectionViaChannel = function instrumentCollectionViaChannel(shim, Collection) {
+  const subscribed = subscribeToAgentChannel(shim, "nr_collection", COLLECTION_OPS);
+  if (!subscribed) {
+    common.instrumentCollection(shim, Collection);
+  }
+};
+
 /**
  * Instruments all methods from constants.CURSOR_OPS on a given
  * cursor class

package/lib/instrumentation-security/hooks/mongodb/v4-mongo.js

@@ -6,12 +6,22 @@
 
 'use strict'
 
-const { instrumentCollection, instrumentCursor, instrumentDb } = require('./common')
+const { instrumentCollectionViaChannel, instrumentCursorViaChannel, instrumentDb } = require('./common')
 
 module.exports = function instrument(shim, mongodb) {
-  instrumentCursor(shim, mongodb.AbstractCursor)
-  instrumentCursor(shim, mongodb.FindCursor)
-  instrumentCursor(shim, mongodb.AggregationCursor)
-  instrumentCollection(shim, mongodb.Collection)
+  // The newrelic agent instruments mongodb (>= 4) via diagnostics_channel and
+  // reassigns the driver prototype methods. Reassigning those same prototype
+  // methods here would clobber the agent's instrumentation (and vice versa), so
+  // we subscribe to the agent's construction channels and attach our security
+  // wrapper to each constructed instance instead. A single `nr_cursor`
+  // subscription covers AbstractCursor and its subclasses (FindCursor,
+  // AggregationCursor). See https://github.com/newrelic/csec-node-agent/issues/374.
+  //
+  // If the agent does not expose those channels (older agent without
+  // subscriber based mongodb instrumentation), these fall back to the legacy
+  // prototype wrapping, which is safe because there is no colliding agent
+  // instrumentation in that case.
+  instrumentCursorViaChannel(shim, mongodb.AbstractCursor)
+  instrumentCollectionViaChannel(shim, mongodb.Collection)
   instrumentDb(shim, mongodb.Db)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newrelic/security-agent",
-  "version": "3.0.4",
+  "version": "4.0.0",
   "description": "New Relic Security Agent for Node.js",
   "main": "index.js",
   "jsonVersion": "1.2.9",
@@ -29,7 +29,7 @@
     "Node.js Application Security"
   ],
   "engines": {
-    "node": ">=20",
+    "node": ">=22.16.0",
     "npm": ">=6.0.0"
   },
   "author": "newrelic",
@@ -52,10 +52,10 @@
     "request-ip": "^3.3.0",
     "ringbufferjs": "^2.0.0",
     "semver": "^7.5.4",
-    "undici": "^7.19.0",
+    "undici": "^7.30.1",
     "unescape": "^1.0.1",
     "unescape-js": "^1.1.4",
-    "ws": "^8.17.1"
+    "ws": "^8.22.0"
   },
   "devDependencies": {
     "@grpc/proto-loader": "^0.7.10",