@contrast/route-coverage 1.51.0 → 1.53.0

package/lib/install/restify.js

@@ -14,58 +14,240 @@
  */
 'use strict';
 
-const { isString, primordials: { StringPrototypeToLowerCase, StringPrototypeSplit } } = require('@contrast/common');
-const { createSignature, patchType } = require('../utils/route-info');
-
-// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Restify
-module.exports = function init(core) {
-  const { patcher, depHooks, routeCoverage } = core;
-  const discover = (route) => routeCoverage.discover(route);
-  const observe = (route) => routeCoverage.observe(route);
-
-  function createRoute(url, method) {
-    method = StringPrototypeToLowerCase.call(method);
-    return {
-      signature: createSignature(url, method, 'server'),
-      method,
-      url,
-      normalizedUrl: url,
-      framework: 'restify'
-    };
+const { AsyncLocalStorage } = require('async_hooks');
+const {
+  isString,
+  primordials: {
+    StringPrototypeToLowerCase,
+    StringPrototypeSplit,
+    StringPrototypeSubstring,
+  },
+  set,
+  RouteType,
+} = require('@contrast/common');
+const { Core } = require('@contrast/core/lib/ioc/core');
+const { formatHandler, patchType } = require('../utils/route-info');
+
+const COMPONENT_NAME = 'routeCoverage.restify';
+const FRAMEWORK = 'restify';
+
+module.exports = Core.makeComponent({
+  name: COMPONENT_NAME,
+  factory: (core) => new RestifyInstrumentation(core),
+});
+
+class RestifyInstrumentation {
+  constructor(core) {
+    set(core, COMPONENT_NAME, this);
+    Object.defineProperty(this, 'core', { value: core });
+    this.routeScope = new AsyncLocalStorage();
+    this.conditionalHandlers = new WeakMap();
   }
 
-  return core.routeCoverage.restify = {
-    install() {
-      depHooks.resolve({ name: 'restify', version: '>=10 <12' }, (restify) => {
-        patcher.patch(restify, 'createServer', {
-          name: 'restify.createServer',
-          patchType,
-          post({ result: server }) {
-            patcher.patch(server.router, 'mount', {
-              name: 'restify.router.mount',
+  formatHandler(fn) {
+    return formatHandler(this.core.patcher.unwrap(fn));
+  }
+
+  install() {
+    const self = this;
+    const { depHooks } = this.core;
+
+    depHooks.resolve({ name: 'restify', version: '>=10 <12' }, (restify, pkgMeta) => {
+      self.patchPlugins(restify, pkgMeta);
+      self.patchServer(restify, pkgMeta);
+    });
+  }
+
+  patchPlugins(restify) {
+    const self = this;
+    const { patcher, routeCoverage } = this.core;
+    if (!restify.plugins?.conditionalHandler) return;
+
+    const name = 'restify.plugins.conditionalHandler';
+    patcher.patch(restify.plugins, 'conditionalHandler', {
+      name,
+      patchType,
+      around(next, data) {
+        const { args } = data;
+        const conditionals = Array.isArray(args[0]) ? args[0] : [args[0]];
+        const formattedHandlers = [];
+
+        // we have to do this before calling next() to get return value
+        // since restify potentially alters conditional.handlers
+        for (const conditional of conditionals) {
+          const isHandlerArr = Array.isArray(conditional.handler);
+          const target = isHandlerArr ? conditional.handler : conditional;
+          const propsIter = isHandlerArr ? Object.keys(conditional.handler) : ['handler'];
+
+          for (const propName of propsIter) {
+            if (typeof target[propName] !== 'function') continue;
+
+            const formattedHandler = self.formatHandler(target[propName]);
+            formattedHandlers.push(formattedHandler);
+
+            patcher.patch(target, propName, {
+              name: 'restify.plugins.conditionalHandler',
               patchType,
-              post({ result: route }) {
-                const { path, method } = route;
-                if (!path || !method || !isString(path)) return;
-                const routeInfo = createRoute(path, method);
-                discover(routeInfo);
-
-                const [handler] = route.chain._stack;
-                route.chain._stack[0] = patcher.patch(handler, {
-                  name: 'route.chain._stack[0].handler',
+              pre(data) {
+                const { args: [req] } = data;
+                const store = self.routeScope.getStore();
+                if (!store) return;
+
+                for (const routeInfo of store.observables) {
+                  if (routeInfo.signature.indexOf(formattedHandler) >= 0) {
+                    routeCoverage.observe({
+                      ...routeInfo,
+                      method: StringPrototypeToLowerCase.call(req.method),
+                      url: StringPrototypeSplit.call(req.url, '?')[0],
+                    });
+                    break;
+                  }
+                }
+              },
+            });
+          }
+        }
+
+        const result = next();
+
+        // save list of handlers that have been registered under the returned
+        // consolidated one. when this return value gets mounted at an actual
+        // path(s), we can lookup the handlers and discover each individually
+        // with that additional route info.
+        self.conditionalHandlers.set(result, formattedHandlers);
+
+        return result;
+      },
+    });
+  }
+
+  patchServer(restify, pkgMeta) {
+    const self = this;
+    const { logger, patcher, routeCoverage } = this.core;
+
+    patcher.patch(restify, 'createServer', {
+      name: 'restify.createServer',
+      patchType,
+      post({ result: server }) {
+        patcher.patch(server.router, 'mount', {
+          name: 'restify.router.mount',
+          patchType,
+          post({ result: route }) {
+            if (!route.path || !route.method || !isString(route.path)) {
+              logger.error({ route }, 'unable to process restify route');
+              return;
+            }
+
+            const { path } = route;
+            const method = StringPrototypeToLowerCase.call(route.method);
+            const baseInfo = {
+              method,
+              url: path,
+              normalizedUrl: path,
+              framework: FRAMEWORK,
+              type: RouteType.HTTP,
+            };
+
+            for (let idx = 0; idx < route.chain._stack.length; idx++) {
+              const handler = route.chain._stack[idx];
+              const routeInfo = {
+                ...baseInfo,
+                signature: `server.${method}(${path}, ${self.formatHandler(handler)})`,
+              };
+
+              if (!self.conditionalHandlers.has(handler)) {
+                // "regular" handlers
+                routeCoverage.discover(routeInfo);
+                route.chain._stack[idx] = patcher.patch(route.chain._stack[idx], {
+                  name: 'restify.route.chain._stack',
                   patchType,
-                  post({ args }) {
-                    const [req] = args;
-                    const { url: reqUrl, method } = req;
-                    const [url] = StringPrototypeSplit.call(reqUrl, '?');
-                    observe({ ...routeInfo, method: StringPrototypeToLowerCase.call(method), url });
+                  pre({ args: [req] }) {
+                    routeCoverage.observe({
+                      ...routeInfo,
+                      method: StringPrototypeToLowerCase.call(req.method),
+                      url: StringPrototypeSplit.call(req.url, '?')[0],
+                    });
+                  }
+                });
+              } else {
+                // "conditional" handlers dispatch to their registered handlers
+                const formattedHandlers = self.conditionalHandlers.get(handler);
+                const store = { observables: [] };
+
+                for (const formattedHandler of formattedHandlers) {
+                  const routeInfo = {
+                    ...baseInfo,
+                    signature: `server.${method}(${path}, ${formattedHandler})`,
+                  };
+                  routeCoverage.discover(routeInfo);
+                  store.observables.push(routeInfo);
+                }
+
+                route.chain._stack[idx] = patcher.patch(route.chain._stack[idx], {
+                  name: 'restify.route.chain._stack',
+                  patchType,
+                  around(next) {
+                    return self.routeScope.run(store, next);
                   }
                 });
               }
-            });
+            }
           }
         });
+
+        self.patchMiddlewareChains(server, pkgMeta);
+      }
+    });
+  }
+
+  patchMiddlewareChains(server) {
+    const self = this;
+    const { config, routeCoverage, patcher } = this.core;
+
+    if (!config.getEffectiveValue('assess.report_middleware_routes')) return;
+
+    for (const propName of ['preChain', 'useChain']) {
+      patcher.patch(server[propName], 'add', {
+        name: `restify.server.${propName}.add`,
+        patchType,
+        around(next, data) {
+          const len = data.obj._stack.length;
+          const ret = next();
+
+          if (data.obj._stack.length > len) {
+            const method = StringPrototypeSubstring.call(propName, 0, 3);
+            const baseData = {
+              method,
+              url: '/',
+              normalizedUrl: '/',
+              type: RouteType.MIDDLEWARE,
+              framework: FRAMEWORK,
+            };
+
+            for (let idx = 0; idx < data.obj._stack.length; idx++) {
+              const routeData = {
+                ...baseData,
+                signature: `server.${method}(${self.formatHandler(data.obj._stack[idx])})`,
+              };
+
+              routeCoverage.discover(routeData);
+              patcher.patch(data.obj._stack, idx, {
+                name: `restify.server.${propName}`,
+                patchType,
+                pre({ args: [req] }) {
+                  routeCoverage.observe({
+                    ...routeData,
+                    method: StringPrototypeToLowerCase.call(req.method),
+                    url: StringPrototypeSplit.call(req.url, '?')[0],
+                  });
+                },
+              });
+            }
+          }
+          return ret;
+        }
       });
     }
-  };
-};
+  }
+}
+

package/lib/utils/route-info.js

@@ -15,6 +15,8 @@
 'use strict';
 
 const patchType = 'route-coverage';
+const { funcInfo } = require('@contrast/fn-inspect');
+const { primordials: { StringPrototypeReplace, StringPrototypeSubstring } } = require('@contrast/common');
 
 /**
  * Creates a formatted "signature" for a route
@@ -28,4 +30,27 @@ function createSignature(path, method = '', obj = 'Router', handler = '[Function
   return `${obj}.${method}('${path}', ${handler})`;
 }
 
-module.exports = { createSignature, patchType };
+/**
+ * Creates a formatted handler signature for a route
+ * @param {function} handler
+ * @param {string=} appDir
+ * @return {string} formatted handler
+ */
+function formatHandler(handler, appDir) {
+  const info = funcInfo(handler);
+  if (!info) return '[Function]';
+
+  let file = info.file ?
+    StringPrototypeReplace.call(info.file, appDir, '') :
+    '';
+  if (file.length > 30) {
+    file = `...${StringPrototypeSubstring.call(file, file.length - 40)}`;
+  }
+  const handlerName = info.method || handler.name || 'anonymous';
+  const formattedHandler = (file && Number.isFinite(info.lineNumber) && Number.isFinite(info.column)) ?
+    `[${handlerName} ${file} ${info.lineNumber}:${info.column}]` :
+    `[Function: ${handlerName}]`; // what util.inspect(handler) would return
+  return formattedHandler;
+}
+
+module.exports = { createSignature, patchType, formatHandler };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.51.0",
+  "version": "1.53.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.38.0",
-    "@contrast/config": "1.54.0",
-    "@contrast/core": "1.59.0",
-    "@contrast/dep-hooks": "1.28.0",
+    "@contrast/common": "1.39.0",
+    "@contrast/config": "1.55.0",
+    "@contrast/core": "1.60.0",
+    "@contrast/dep-hooks": "1.29.0",
     "@contrast/fn-inspect": "^5.0.2",
-    "@contrast/logger": "1.32.0",
-    "@contrast/patcher": "1.31.0",
-    "@contrast/scopes": "1.29.0",
+    "@contrast/logger": "1.33.0",
+    "@contrast/patcher": "1.32.0",
+    "@contrast/scopes": "1.30.0",
     "semver": "^7.6.0"
   }
 }

package/lib/install/express/express4.js

@@ -1,157 +0,0 @@
-/*
- * 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 METHODS = [
-  'all',
-  'get',
-  'post',
-  'put',
-  'delete',
-  'patch',
-  'options',
-  'head',
-];
-
-const fnInspect = require('@contrast/fn-inspect');
-const { createSignature, patchType } = require('../../utils/route-info');
-const { isString, primordials: { ArrayPrototypeJoin, StringPrototypeToLowerCase, StringPrototypeReplace, StringPrototypeReplaceAll, StringPrototypeSplit, StringPrototypeSlice } } = require('@contrast/common');
-
-// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Express
-module.exports = function init(core) {
-  const { patcher, depHooks, routeCoverage } = core;
-  const discover = (route) => routeCoverage.discover(route);
-  const observe = (route) => routeCoverage.observe(route);
-
-  const isRoute = (layer) => !!layer.route;
-  const isRouter = (layer) => layer.name && StringPrototypeToLowerCase.call(layer.name) === 'router';
-  const isValidPath = (path) => isString(path) || Array.isArray(path) || path instanceof RegExp;
-  const getHandleMethod = (layer) => fnInspect.funcInfo(layer.__handle)?.file.includes('express-async-errors') ? '__handle' : 'handle';
-  const getLastLayer = (router) => router?.stack[router.stack.length - 1];
-
-  function regExpToPath(regex) {
-    if (regex.source) {
-      let [path] = StringPrototypeSplit.call(regex?.source, '/?');
-      path = StringPrototypeReplaceAll.call(path, '\\', '');
-      path = StringPrototypeReplace.call(path, '^', '');
-      return path;
-    }
-  }
-
-  function format(url) {
-    if (Array.isArray(url)) {
-      return `/[${ArrayPrototypeJoin.call(url)}]`;
-    } else if (url instanceof RegExp) {
-      return `/{${StringPrototypeSlice.call(url.toString(), 1, -1)}}`;
-    } else {
-      return url;
-    }
-  }
-
-  function parseRoute(route) {
-    const { path } = route;
-    const method = route.methods._all ? 'all' : route.stack[0].method;
-    return { url: format(path), method };
-  }
-
-
-  function createRouteInfo(url, method, obj) {
-    return {
-      signature: createSignature(url, method, obj),
-      url,
-      normalizedUrl: url,
-      method,
-      framework: 'express'
-    };
-  }
-
-  function patchHandle(layer, routeInfo) {
-    const handle = getHandleMethod(layer);
-    patcher.patch(layer, handle, {
-      name: 'express.Route.handle',
-      patchType,
-      post({ args }) {
-        const [req] = args;
-        const [url] = StringPrototypeSplit.call(req.originalUrl, '?');
-        const { method } = req;
-        if (url && method) {
-          observe({ ...routeInfo, url, method: StringPrototypeToLowerCase.call(method) });
-        }
-      }
-    });
-  }
-
-  function traverse(stack, path = '', depth = 0) {
-    path = format(path);
-    stack.forEach((layer) => {
-      if (isRoute(layer)) {
-        const { url, method } = parseRoute(layer.route);
-        const routeInfo = createRouteInfo(path + url, method);
-        discover(routeInfo);
-        patchHandle(layer, routeInfo);
-      } else if (isRouter(layer)) {
-        const regexPath = regExpToPath(layer.regexp);
-        if (depth < 3) traverse(layer.handle.stack, path + regexPath, depth += 1);
-      } else {
-        const regexPath = regExpToPath(layer.regexp);
-        const routeInfo = createRouteInfo(path + regexPath, 'use');
-        discover(routeInfo);
-        patchHandle(layer, routeInfo);
-      }
-    });
-  }
-  return core.routeCoverage.express4 = {
-    install() {
-      depHooks.resolve({ name: 'express', version: '>=4 <5' }, (express) => {
-        patcher.patch(express.application, 'use', {
-          name: 'express.application.use',
-          patchType,
-          post({ args, result }) {
-            const len = args.length;
-            const fn = args[len - 1];
-            const path = len > 1 ? args[0] : undefined;
-            if (path && !isValidPath(path)) return;
-            const handlers = Array.isArray(fn) ? fn : [fn];
-            handlers.forEach((layer) => {
-              if (isRouter(layer)) {
-                traverse(layer.stack, path);
-              } else if (path) {
-                const routeInfo = createRouteInfo(format(path), 'use', 'App');
-                discover(routeInfo);
-                const lastLayer = getLastLayer(result._router);
-                if (lastLayer) patchHandle(lastLayer, routeInfo);
-              }
-            });
-          }
-        });
-
-        METHODS.forEach((method) => {
-          patcher.patch(express.application, method, {
-            name: `express.application.${method}`,
-            patchType,
-            post({ args, result }) {
-              const [url, fn] = args;
-              if (!url || !fn || !isValidPath(url)) return;
-              const routeInfo = createRouteInfo(format(url), method, 'App');
-              discover(routeInfo);
-              const lastLayer = getLastLayer(result._router);
-              if (lastLayer) patchHandle(lastLayer, routeInfo);
-            }
-          });
-        });
-      });
-    }
-  };
-};