@contrast/route-coverage 1.51.0 → 1.53.0

package/lib/index.d.ts

@@ -23,6 +23,7 @@ import { Scopes } from '@contrast/scopes';
 export { RouteInfo };
 
 export interface RouteCoverage extends Installable {
+  DISCOVERY_QUEUE_EMPTY_MS: number;
   discover(info: RouteInfo): void;
   discoveryFinished(): void;
   queue(info: RouteInfo): void;
@@ -37,6 +38,7 @@ export interface Core {
   readonly messages: Messages;
   readonly patcher: Patcher;
   readonly scopes: Scopes;
+  initComponentSync(c: any): void;
 }
 
 declare function init(core: Core): RouteCoverage;

package/lib/index.js

@@ -41,6 +41,7 @@ module.exports = function init(core) {
   const routeIdentifier = (method, signature) => `${method}.${signature}`;
 
   const routeCoverage = core.routeCoverage = {
+    DISCOVERY_QUEUE_EMPTY_MS: 10_000,
     discover(info) {
       const id = routeIdentifier(info.method, info.signature);
       if (routeInfo.get(id)) return;
@@ -68,7 +69,7 @@ module.exports = function init(core) {
       if (routeQueue.size === 1) {
         setTimeout(() => {
           this.discoveryFinished();
-        }, 10_000);
+        }, this.DISCOVERY_QUEUE_EMPTY_MS);
       }
     },
 
@@ -121,12 +122,12 @@ module.exports = function init(core) {
     },
   };
 
-  require('./install/express')(core);
+  core.initComponentSync(require('./install/express'));
   require('./install/fastify')(core);
   require('./install/graphql')(core);
-  require('./install/hapi')(core);
+  core.initComponentSync(require('./install/hapi'));
   require('./install/koa')(core);
-  require('./install/restify')(core);
+  core.initComponentSync(require('./install/restify'));
   core.initComponentSync(require('./install/socket.io'));
 
   messages.on(Event.SERVER_LISTENING, () => {

package/lib/install/express.js

@@ -0,0 +1,535 @@
+/*
+ * 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 { AsyncLocalStorage } = require('node:async_hooks');
+const { EventEmitter } = require('events');
+const process = require('process');
+const {
+  get,
+  set,
+  isString,
+  Event,
+  RouteType,
+  primordials: {
+    ArrayPrototypeJoin,
+    StringPrototypeSubstring,
+    StringPrototypeToLowerCase,
+  }
+} = require('@contrast/common');
+const Core = require('@contrast/core/lib/ioc/core');
+const { formatHandler } = require('../utils/route-info');
+
+const METHODS = [
+  'all',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'patch',
+  'options',
+  'head',
+];
+const componentName = 'routeCoverage.express';
+const patchType = 'route-coverage-express';
+const kMetaKey = Symbol('cs_meta');
+
+module.exports = Core.makeComponent({
+  name: componentName,
+  factory: (core) => new ExpressInstrumentation(core),
+});
+
+class ExpressInstrumentation {
+  constructor(core) {
+    set(core, componentName, this);
+    Object.defineProperty(this, 'core', { value: core });
+    this.listenFlag = false;
+    this.isDiscoveryQueued = false;
+    this.events = new EventEmitter();
+    this.methodScope = new AsyncLocalStorage();
+    this.handleScope = new AsyncLocalStorage();
+  }
+
+  install() {
+    const { depHooks } = this.core;
+    depHooks.resolve({ name: 'express', version: '>=4 <6' }, (express, meta) => {
+      this.patchApplication(express.application);
+      this.patchRouter(express.Router, meta);
+      return this.patchExpress(express, meta);
+    });
+    depHooks.resolve({ name: 'express', version: '4', file: 'lib/router/layer.js' }, (Layer, meta) => this.patchLayer(Layer, meta));
+    depHooks.resolve({ name: 'router', version: '2' }, (Router, meta) => this.patchRouter(Router, meta));
+    depHooks.resolve({ name: 'router', file: 'lib/layer.js', version: '2' }, (Layer, meta) => this.patchLayer(Layer, meta));
+  }
+
+  patchExpress(express, pkgMeta) {
+    const self = this;
+    const { core } = self;
+
+    return core.patcher.patch(express, {
+      name: 'express.application',
+      patchType: `${patchType}-discovery`,
+      post(data) {
+        const app = data.result;
+        // force instantiation of router in express 4
+        app.lazyrouter?.();
+
+        core.messages.on(Event.SERVER_LISTENING, () => {
+          let router;
+
+          self.listenFlag = true;
+
+          try {
+            router = app._router || app.router;
+          } catch (err) {
+            /* some versions of express will error if you access deprecated router path */
+          }
+
+          if (!router?.stack?.[0]) {
+            core.logger.debug('no routes detected in express router stack: %s@%s', pkgMeta.name, pkgMeta.version);
+            return;
+          }
+
+          self.handleDiscovery(router);
+          self.events.on('deferred-discovery', () => {
+            // rerun discovery if other instrumentation detects post-listen route registration
+            self.handleDiscovery(router);
+          });
+        });
+
+        return app;
+      }
+    });
+  }
+
+  patchApplication(application) {
+    const self = this;
+    const { core, handleScope, methodScope } = self;
+
+    [...METHODS, 'use', 'route'].forEach((method) => {
+      // then setup app and router to run in method scopes
+      core.patcher.patch(application, method, {
+        name: `express.application.${method}`,
+        patchType: `${patchType}-discovery`,
+        around(next, data) {
+          if (methodScope.getStore()) return next();
+          return methodScope.run({ method, args: data.args, type: 'app' }, next);
+        }
+      });
+    });
+
+    core.patcher.patch(application, 'handle', {
+      name: 'express.application.handle',
+      patchType: `${patchType}-discovery`,
+      around(next, data) {
+        // wrap request handling in "handle scope". the scope's store data
+        // helps for building observation templates as routing occurs
+        const store = { templateSegments: [] };
+        return handleScope.run(store, next);
+      }
+    });
+  }
+
+  patchRouter(Router, pkgMeta) {
+    const self = this;
+    const { core, methodScope } = this;
+    // express 4 uses setPrototypeOf
+    const patchTarget = (pkgMeta?.name == 'express' && pkgMeta?.version[0] == '4') ?
+      Router.prototype?.constructor :
+      Router.prototype;
+
+    if (!patchTarget) {
+      const descriptor = pkgMeta?.version ? `express ${pkgMeta.version}` : 'router package';
+      core.logger.error(`no router patch target for ${descriptor}`);
+      return Router;
+    }
+
+    // wrap router and app methods in "method scope" to capture info to help build signatures.
+    // express has a number of APIs that work at different levels of abstraction, and we need to patch
+    // all of them. the scopes let us know what top-level APIs are being called by application code.
+    [...METHODS, 'use', 'route'].forEach((method) => {
+      core.patcher.patch(patchTarget, method, {
+        name: `express.Router.prototype.${method}`,
+        patchType: `${patchType}-discovery`,
+        around(next, data) {
+          if (method == 'use') data._stackLength = data.obj.stack?.length;
+
+          const ret = methodScope.getStore() ?
+            next() :
+            methodScope.run({ method, args: data.args, type: 'router' }, next);
+
+          if (method == 'use' && data.obj.stack.length > data._stackLength) {
+            for (let i = data._stackLength; i < data.obj.stack.length; i++) {
+              const layer = data.obj.stack[i];
+              const methodStore = methodScope.getStore();
+
+              const meta = {
+                template: ExpressInstrumentation.normalizeTemplate(data.args[0]),
+                method: 'use',
+                type: methodStore?.type || 'router',
+              };
+
+              if (layer) {
+                self.attachDiscoveryMeta(layer, meta);
+              }
+            }
+          }
+
+          return ret;
+        }
+      });
+    });
+
+    // app[method] and router[method] end up calling this
+    // Append metadata to the created Route object at layer.route.
+    // we also patch the returned Route's methods for building signatures
+    core.patcher.patch(patchTarget, 'route', {
+      name: 'express.Route',
+      patchType: `${patchType}-discovery`,
+      post(data) {
+        const { result } = data;
+        const methodStore = methodScope.getStore();
+        const meta = {
+          template: ExpressInstrumentation.normalizeTemplate(data.args[0]),
+          method: methodStore?.method,
+          type: methodStore?.type || 'route',
+        };
+
+        self.attachDiscoveryMeta(result, meta);
+
+        // patch route instance methods we do that here when we have
+        // todo move to prototype to help w/ memory
+        METHODS.forEach((method) => {
+          if (result[method]) {
+            core.patcher.patch(result, method, {
+              name: `express.Router.prototype.route${method}`,
+              patchType: `${patchType}-discovery`,
+              pre(data) {
+                data._stackIdx = data.obj.stack?.length;
+              },
+              post(data) {
+                if (data.obj.stack?.length > data._stackIdx) {
+                  for (let i = data._stackIdx; i < data.obj.stack.length; i++) {
+                    const layer = data.obj.stack[i];
+                    const methodStore = methodScope.getStore();
+                    const meta = {
+                      type: methodStore?.type || 'route',
+                      method: methodStore?.method == 'all' ? 'all' : method,
+                    };
+
+                    self.attachDiscoveryMeta(layer, meta);
+                  }
+                }
+              },
+            });
+          }
+        });
+
+        return result;
+      },
+    });
+
+    return Router;
+  }
+
+  patchLayer(Layer, pkgMeta) {
+    const self = this;
+    const { core, handleScope, methodScope } = self;
+
+    // when Layer.match gets called, matchers functions run underneath. the API doesn't present a really clean
+    // way to instrument, so we're using scopes. we reference the scope's store in the instrumented matcher
+    // functions so we can correlate a matcher that succeeds to its corresponding route template segment.
+    core.patcher.patch(Layer.prototype, 'match', {
+      name: 'Layer.prototype.match',
+      patchType: `${patchType}-observation`,
+      pre(data) {
+        data._store = handleScope.getStore();
+        if (!data._store) return;
+        data[kMetaKey] = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
+      },
+      post(data) {
+        const { result } = data;
+        if (!result || !data._store || !data[kMetaKey]?.template) return;
+        // if the layer matches, we know to push corresponding path to store's template segments.
+        // we pop this value from the array in hook to all `next` callbacks below.
+        data._store.templateSegments.push(data[kMetaKey].template);
+      }
+    });
+
+    // patch the `next` callback of every Layer's request handler.
+    // we pop the value from the stack of route template segments being managed.
+    const handleRequest = pkgMeta.name == 'express' && pkgMeta.version[0] == '4' ? 'handle_request' : 'handleRequest';
+    core.patcher.patch(Layer.prototype, handleRequest, {
+      name: `Layer.prototype.${handleRequest}`,
+      patchType: `${patchType}-observation`,
+      pre(data) {
+        const next = data.args[2];
+        const meta = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
+
+        if (meta.template) {
+          const store = handleScope.getStore();
+          // this runs often and there's no need to use patcher here. monkey patch directly to optimize
+          data.args[2] = function (...args) {
+            if (store) store.templateSegments.pop();
+            const ret = next(...args);
+            return ret;
+          };
+        }
+      }
+    });
+
+    // instrument the Layer constructor. this will allow us to patch
+    // created matchers to help us build observation template from metadata.
+    // if matcher was successful we store index of it in handle scope.
+    return core.patcher.patch(Layer, {
+      name: 'router.Layer',
+      patchType: `${patchType}-observation`,
+      pre(data) {
+        data._methodScope = methodScope.getStore();
+      },
+      post(data) {
+        const instance = data.result;
+
+        // patch handle to report observation when called. it checks handle
+        // scope to get current request's template to match with discovery info
+        core.patcher.patch(instance, 'handle', {
+          name: 'router.Layer.handle',
+          patchType: `${patchType}-observation`,
+          pre(data) {
+            if (instance[kMetaKey]?.observables) {
+              const store = handleScope.getStore();
+              if (store) {
+                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 {
+                  // one example that will trigger this logging is recursive routers
+                  // this will at least log that something like this has been encountered
+                  core.logger.error({
+                    method,
+                    template,
+                    observables: instance[kMetaKey]?.observables,
+                  }, 'unable to map route template to signature');
+                }
+              }
+            }
+          },
+        });
+      },
+    });
+  }
+
+  discover(info) {
+    const { method, observables, routeType } = info;
+    if (!method || !observables) return;
+
+    for (const [normalizedUrl, signature] of Object.entries(observables)) {
+      this.core.routeCoverage.discover({
+        url: normalizedUrl,
+        normalizedUrl,
+        method,
+        signature,
+        type: routeType,
+        framework: 'express',
+      });
+    }
+  }
+
+  observe(info) {
+    this.core.routeCoverage.observe({ framework: 'express', ...info });
+  }
+
+  /**
+   * Traverse the application's router "stack" and generate route discovery events
+   * using layer/route metadata that was appended by methods like router.post().
+   * @param {object} stack express application's router stack
+   */
+  handleDiscovery(router) {
+    const self = this;
+    // traverse fn executes this callback when visiting Layer instances
+    this.traverse(router, (path, key, value, target, state) => {
+      if (value.stack?.length > 0 || value.route) return;
+
+      // get metadata for this Layer
+      // metadata is on Layers within stacks and on Routes instances.
+      const metas = [];
+      for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (Number.isFinite((Number(seg))) || seg == 'route') {
+          const metaPath = ArrayPrototypeJoin.call(path.slice(0, i + 1), '.');
+          const layerOrRoute = get(router, metaPath);
+          if (layerOrRoute?.[kMetaKey]) {
+            metas.push(layerOrRoute[kMetaKey]);
+          }
+        }
+      }
+
+      // 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 {
+              Object.assign(value[kMetaKey].observables, observables);
+            }
+          }
+          self.discover(value[kMetaKey]);
+        }
+      }
+    });
+  }
+
+  /**
+   * Traverses the top-level app's routing stack and executes the provided callback when
+   * visiting nodes. The callback is invoked only to visit Layer instances, objects and
+   * functions, since these are the only 2 types that could have our metadata attached.
+   */
+  traverse(target, cb, path = [], data = new Map()) {
+    loopKeys: for (const key in target) {
+      path.push(key);
+
+      // only visit Layer instances
+      const maybeLayer = target[key];
+      if (
+        maybeLayer?.constructor?.name == 'Layer' &&
+        !maybeLayer?.stack?.length
+      ) {
+        let _data = data.get(maybeLayer);
+
+        if (!_data) {
+          _data = { paths: [] };
+          data.set(maybeLayer, _data);
+        }
+
+        // you can mount a router on itself
+        // prevent infinitely recursing into self-mounted routers
+        for (const visitedPath of _data.paths) {
+          // these conditions indicate recursive nesting at particular path
+          if (
+            path.length > visitedPath.length &&
+            visitedPath.every((el, i) => path[i] == el)
+          ) {
+            path.pop();
+            continue loopKeys;
+          }
+        }
+
+        _data.paths.push([...path]); // copy because path argument mutates
+
+        const halt = cb(path, key, maybeLayer, target) === false;
+        if (halt) return;
+      }
+
+      // might be able to fine-tune this a bit more
+      if (typeof maybeLayer == 'object' || typeof maybeLayer == 'function') {
+        this.traverse(maybeLayer, cb, path, data);
+      }
+
+      path.pop();
+    }
+  }
+
+  generateObservables(metas, handler) {
+    const { core } = this;
+    handler = core.patcher.unwrap(handler);
+
+    let type = '';
+    let method = '';
+    const templates = [];
+
+    // loop backwards
+    for (let i = metas.length - 1; i >= 0; i--) {
+      const meta = metas[i];
+      // use the most recent `type` and `method` used when building routes, so don't overwrite if set
+      if (!type && meta.type) type = meta.type;
+      if (!method && meta.method) method = meta.method;
+      templates.unshift(meta.template ?? '');
+    }
+    let template = ArrayPrototypeJoin.call(templates, '');
+    if (template == '') template = '/';
+    const signature = `${type}.${method}(${template}, ${formatHandler(handler)})`;
+
+    // this gets merged into meta.observables if same route handler is mounted at multiple paths
+    return {
+      [template]: signature,
+    };
+  }
+
+  attachDiscoveryMeta(target, meta) {
+    // if this is called after the server was listening we need to re-traverse
+    if (this.listenFlag && !this.isDiscoveryQueued) {
+      this.isDiscoveryQueued = true;
+      process.nextTick(() => {
+        this.isDiscoveryQueued = false;
+        this.events.emit('deferred-discovery');
+      });
+    }
+
+    Object.defineProperty(target, kMetaKey, {
+      enumerable: false,
+      value: meta,
+    });
+  }
+
+  static normalizeTemplate(paths) {
+    if (typeof paths == 'function') return '';
+    if (isString(paths)) return ExpressInstrumentation.normalizePathSegment(paths);
+    if (paths instanceof RegExp) return ExpressInstrumentation.normalizePathSegment(paths);
+
+    if (Array.isArray(paths)) {
+      const ret = [];
+      paths = paths.flat(Infinity).filter((v) => typeof v !== 'function');
+      if (paths.length) ret.push(...paths.map((v) => ExpressInstrumentation.normalizePathSegment(v) || '/'));
+      else ret.push('');
+      return ret.length > 1 ? `[${ArrayPrototypeJoin.call(ret, ', ')}]` : ret[0];
+    }
+  }
+
+  static normalizePathSegment(value) {
+    if (!value || value == '/') {
+      // app.[method](handler) and app.[method]('/', handler) are the same so default to empty string
+      return '';
+    }
+    if (value instanceof RegExp) {
+      const rxString = value.toString();
+      // todo: figure out best way to represent regexp in route template
+      return `/[${StringPrototypeSubstring.call(rxString, 1, rxString.length - 1)}]`;
+    }
+    return value;
+  }
+}

package/lib/install/fastify/fastify-express.js

@@ -0,0 +1,71 @@
+/*
+ * 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 { RouteType } = require('@contrast/common');
+const { patchType, formatHandler } = require('./../../utils/route-info');
+const isArray = (arr) => Array.isArray(arr);
+module.exports = function init(core) {
+  const { patcher, depHooks, routeCoverage, scopes } = core;
+
+  return core.routeCoverage.fastifyExpress = {
+    install() {
+      const name = 'fastifyExpress';
+      depHooks.resolve({ name: '@fastify/express', version: '*' }, (_xport) => patcher.patch(_xport, {
+        name,
+        patchType,
+        post(data) {
+          const store = { lock: true, name };
+          patcher.patch(data.args[0], 'use', {
+            name: 'use',
+            patchType,
+            around(next, data) {
+              const [url, fn] = data.args;
+              if (!url || !fn || !core.config.getEffectiveValue('assess.report_middleware_routes')) return next();
+
+              const middleware = isArray(fn) ? fn : [fn];
+              const formattedPath = isArray(url) ? `[${url.join(', ')}]` : url;
+              const patchedMiddleware = middleware.map((f) => {
+                const formattedHandler = formatHandler(f);
+                const signature = `fastify.use(${formattedPath}, ${formattedHandler})`;
+
+                const routeInfo = {
+                  signature,
+                  url: formattedPath,
+                  method: 'use',
+                  normalizedUrl: formattedPath,
+                  type: RouteType.MIDDLEWARE,
+                  framework: 'fastify'
+                };
+                routeCoverage.discover(routeInfo);
+
+                return patcher.patch(f, {
+                  name: 'middleware',
+                  patchType,
+                  post() {
+                    routeCoverage.observe(routeInfo);
+                  }
+                });
+              });
+              data.args[1] = patchedMiddleware;
+
+              return !scopes.instrumentation.isLocked() ? scopes.instrumentation.run(store, next) : next();
+            }
+          });
+        }
+      }));
+    }
+  };
+};