@contrast/assess 1.7.0 → 1.9.0

package/lib/dataflow/sources/handler.js

@@ -19,7 +19,7 @@ const {
   InputType,
   DataflowTag,
   isString,
-  traverseValues
+  join,
 } = require('@contrast/common');
 
 module.exports = function(core) {
@@ -28,17 +28,17 @@ module.exports = function(core) {
       dataflow: {
         sources,
         tracker,
-        eventFactory: { createSourceEvent }
+        eventFactory
       }
     },
-    createSnapshot,
     config,
+    createSnapshot,
     logger,
   } = core;
 
   const emptyStack = Object.freeze([]);
 
-  sources.createTags = function createTags({ inputType, key, value }) {
+  sources.createTags = function createTags({ inputType, fieldName = '', value }) {
     if (!value?.length) {
       return null;
     }
@@ -48,25 +48,30 @@ module.exports = function(core) {
       [DataflowTag.UNTRUSTED]: [0, stop]
     };
 
-    if (inputType === InputType.HEADER && key.toLowerCase() === 'referer') {
+    if (inputType === InputType.HEADER && fieldName.toLowerCase() === 'referer') {
       tags[DataflowTag.HEADER] = [0, stop];
     }
 
     return tags;
   };
 
+  sources.createStacktrace = function(stacktraceOpts) {
+    return config.assess.stacktraces === 'NONE'
+      ? emptyStack
+      : createSnapshot(stacktraceOpts)();
+  };
+
   sources.handle = function({
     context,
+    keys,
     name,
     inputType = InputType.UNKNOWN,
     stacktraceOpts,
     data,
-    sourceContext
+    sourceContext,
   }) {
     if (!data) return;
 
-    const max = config.assess.max_context_source_events;
-
     if (!sourceContext) {
       core.logger.trace({ inputType, name }, 'skipping assess source handling - no request context');
       return null;
@@ -76,31 +81,60 @@ module.exports = function(core) {
       context = inputType;
     }
 
+    const max = config.assess.max_context_source_events;
+    let _data = data;
     let stack;
 
-    traverseValues(data, (path, type, value, obj) => {
+    if (keys) {
+      _data = {};
+      for (const key of keys) {
+        _data[key] = data[key];
+      }
+    }
+
+    function createEvent({ fieldName, pathName, value }) {
+      // create the stacktrace once per call to .handle()
+      stack || (stack = sources.createStacktrace(stacktraceOpts));
+      return eventFactory.createSourceEvent({
+        context: `${context}.${pathName}`,
+        name,
+        fieldName,
+        pathName,
+        stack,
+        inputType,
+        tags: sources.createTags({ inputType, fieldName, value }),
+        result: { tracked: true, value },
+      });
+    }
+
+    if (Buffer.isBuffer(data) && !tracker.getData(data)) {
+      const event = createEvent({ pathName: 'body', value: data, fieldName: '' });
+      if (event) {
+        tracker.track(data, event);
+      }
+      return;
+    }
+
+    traverse(_data, (path, fieldName, value, obj) => {
+      const pathName = join(path, '.');
+
       if (sourceContext.sourceEventsCount >= max) {
         core.logger.trace({ inputType, name }, 'exiting assess source handling - %s max events exceeded', max);
         return true;
       }
 
       if (isString(value) && value.length) {
-        stack = stack || config.assess.stacktraces === 'NONE'
-          ? emptyStack
-          : createSnapshot(stacktraceOpts)();
-        const key = path[path.length - 1];
-        const pathName = path.join('.');
-        const event = createSourceEvent({
-          context: `${context}.${pathName}`,
-          name,
-          fieldName: key,
-          pathName,
-          stack,
-          inputType,
-          tags: sources.createTags({ inputType, key, value }),
-          result: { tracked: true, value },
-        });
+        const strInfo = tracker.getData(value);
+
+        if (strInfo) {
+          // TODO: confirm this "layering-on" approach is what we want
+          // when the value is tracked the handler wins out and we "re-tracks" the value with new source
+          // event metadata. without this step tracker would complain about value already being tracked.
+          // alternatively we could treat this more like a propagation event and update existing metadata.
+          value = strInfo.value;
+        }
 
+        const event = createEvent({ pathName, value, fieldName });
         if (!event) {
           core.logger.warn({ inputType, name, pathName, value }, 'unable to create source event');
           return;
@@ -108,15 +142,96 @@ module.exports = function(core) {
 
         const { extern } = tracker.track(value, event);
         if (extern) {
-          logger.trace({ extern, key, name, inputType }, 'tracked');
-          obj[key] = extern;
+          logger.trace({ extern, fieldName, name, inputType }, 'tracked');
+          obj[fieldName] = extern;
+
           sourceContext.sourceEventsCount++;
         }
+      } else if (Buffer.isBuffer(value) && !tracker.getData(value)) {
+        const event = createEvent({ pathName, value, fieldName });
+        if (event) {
+          tracker.track(value, event);
+        } else {
+          core.logger.warn({ inputType, name, pathName, value }, 'unable to create source event');
+        }
       }
     });
 
+    if (keys) {
+      for (const key of keys) {
+        data[key] = _data[key];
+      }
+    }
+
     return data;
   };
 
   return sources;
 };
+
+/**
+ * A custom traversal function for handling source value tracking efficiently.
+ * Implementation was adapted from traversal methods in @contrast/common.
+ * @param {any} target object to traverse
+ * @param {function} cb function<path, key, value, obj>
+ * @param {string[]} path path of node being visted; constructed of nested keys
+ * @param {boolean} halt whether to halt traversal; determined by callback
+ * @param {Set} visited used to dedupe circular references
+ */
+function traverse(target, cb, path = [], visited = new Set()) {
+  if (isTraversable(target)) {
+    for (const key in target) {
+      path.push(key);
+
+      const value = target[key];
+
+      if (visited.has(value)) {
+        path.pop();
+        break;
+      }
+
+      if (isVisitable(value)) {
+        const halt = cb(path, key, value, target) === false;
+        if (halt) {
+          return;
+        }
+      }
+
+      if (isTraversable(value)) {
+        visited.add(value);
+        traverse(value, cb, path, visited);
+      }
+
+      path.pop();
+    }
+  }
+}
+
+/**
+ * Visit strings, buffers, basic objects and arrays.
+ * @param {any} value the value to check
+ * @returns {boolean}
+ */
+function isVisitable(value) {
+  if (!value) return false;
+
+  return value.constructor?.name === 'String' ||
+    value.constructor?.name === 'Buffer' ||
+    (typeof value === 'object' && !value.constructor);
+}
+
+/**
+ * The criteria for traversal is a strict as possible. We only traverse plain
+ * objects and arrays and objects created via Object.create(null).
+ * @param {any} value the value to check
+ * @returns {boolean}
+ */
+function isTraversable(value) {
+  if (!value || typeof value !== 'object') return false;
+
+  return value.constructor?.name === 'Object' ||
+    value.constructor?.name === 'Array' ||
+    !value.constructor;
+}
+
+module.exports.traverse = traverse;

package/lib/dataflow/sources/index.js

@@ -20,23 +20,18 @@ const { callChildComponentMethodsSync } = require('@contrast/common');
 module.exports = function (core) {
   const sources = core.assess.dataflow.sources = {};
 
-  // API
   require('./handler')(core);
-  // installers
-  // general
-  require('./install/http')(core);
 
-  // frameworks and frameworks specific libraries
   require('./install/express')(core);
   require('./install/fastify')(core);
   require('./install/koa')(core);
-
-  // libraries
   require('./install/body-parser1')(core);
   require('./install/busboy1')(core);
   require('./install/cookie-parser1')(core);
   require('./install/formidable1')(core);
+  require('./install/http')(core);
   require('./install/qs6')(core);
+  require('./install/querystring')(core);
 
   sources.install = function install() {
     callChildComponentMethodsSync(sources, 'install');

package/lib/dataflow/sources/install/body-parser1.js

@@ -36,12 +36,12 @@ module.exports = function init(core) {
 
       if (!sourceContext) {
         logger.error({ name }, 'unable to handle source. Missing `sourceContext`');
-        return;
+        return next(...args);
       }
 
       if (sourceContext.parsedBody) {
         logger.trace({ name }, 'values already tracked');
-        return;
+        return next(...args);
       }
 
       // when using a specific parser, we know the input type.
@@ -55,19 +55,32 @@ module.exports = function init(core) {
             : InputType.BODY;
       }
 
+      let keys;
+      let _data = req.body;
+      let context = 'req.body';
+      const isString = typeof _data === 'string';
+      const isBuffer = Buffer.isBuffer(_data);
+
+      if (isString || isBuffer) {
+        context = 'req';
+        keys = ['body'];
+        _data = req;
+      }
+
       try {
         assess.dataflow.sources.handle({
-          context: 'req.body',
+          context,
+          data: _data,
           name,
+          keys,
           inputType,
+          sourceContext,
           stacktraceOpts: {
             constructorOpt: contrastNext
           },
-          data: req.body,
-          sourceContext,
         });
 
-        sourceContext.parsedBody = !!Object.keys(req.body).length;
+        sourceContext.parsedBody = !!Object.keys(_data).length;
       } catch (err) {
         logger.error({ name, err }, 'unable to handle source');
       }

package/lib/dataflow/sources/install/express/index.js

@@ -17,12 +17,15 @@
 
 const { callChildComponentMethodsSync } = require('@contrast/common');
 
-module.exports = function init(core) {
+module.exports = function (core) {
   core.assess.dataflow.sources.expressInstrumentation = {
     install() {
       callChildComponentMethodsSync(this, 'install');
     }
   };
 
+  require('./params')(core);
+  require('./parsedUrl')(core);
+
   return core.assess.dataflow.sources.expressInstrumentation;
 };

package/lib/dataflow/sources/install/express/params.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright: 2022 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 { InputType } = require('@contrast/common');
+const { patchType } = require('../../../propagation/common');
+
+module.exports = function init(core) {
+  const { depHooks, patcher, logger } = core;
+
+  core.assess.dataflow.sources.expressInstrumentation.params = {
+    install() {
+      const name = 'Layer.prototype.match';
+      depHooks.resolve(
+        { name: 'express', file: 'lib/router/layer.js' },
+        (Layer) => {
+          patcher.patch(Layer.prototype, 'match', {
+            name,
+            patchType,
+            post(data) {
+              const layer = data.obj;
+
+              // we can exit early if
+              //  the layer doesn't match the request or
+              //  the layer doesn't recognize any parameters
+              if (!data.result || !layer.keys || layer.keys.length === 0) {
+                return;
+              }
+
+              const sourceContext = core.scopes.sources.getStore()?.assess;
+
+              if (!sourceContext) {
+                logger.error({ name }, 'unable to handle source. Missing `sourceContext`');
+                return;
+              }
+
+              if (sourceContext.parsedParams) {
+                logger.trace({ name }, 'values already tracked');
+                return;
+              }
+
+              try {
+                core.assess.dataflow.sources.handle({
+                  context: 'req.params',
+                  name,
+                  inputType: InputType.PARAMETER_VALUE,
+                  stacktraceOpts: {
+                    constructorOpt: data.hooked,
+                    prependFrames: [data.orig]
+                  },
+                  data: layer.params,
+                  sourceContext
+                });
+                sourceContext.parsedParams = true;
+              } catch (err) {
+                logger.error({ err, name }, 'unable to handle source');
+              }
+            }
+          });
+
+          return Layer;
+        }
+      );
+    }
+  };
+
+  return core.assess.dataflow.sources.expressInstrumentation.params;
+};

package/lib/dataflow/sources/install/express/parsedUrl.js

@@ -0,0 +1,87 @@
+/*
+ * Copyright: 2022 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 { InputType } = require('@contrast/common');
+const { patchType } = require('../../common');
+
+module.exports = function init(core) {
+  const {
+    assess: {
+      dataflow: { sources }
+    },
+    depHooks,
+    patcher,
+    scopes
+  } = core;
+
+  core.assess.dataflow.sources.expressInstrumentation.parsedUrl = {
+    install() {
+      depHooks.resolve(
+        { name: 'express', file: 'lib/middleware/init.js' },
+        /** @param {import('express/lib/middleware/init')} mw */
+        (mw) => {
+          const name = 'express.middleware.init';
+          patcher.patch(mw, 'init', {
+            name,
+            patchType,
+            post(data) {
+              data.result = patcher.patch(data.result, {
+                name: 'express.middleware.init.expressInit',
+                patchType,
+                pre(data) {
+                  const { args: [req] } = data;
+                  patcher.patch(data.args, '2', {
+                    name: 'express.middleware.init.expressInit.next',
+                    patchType,
+                    pre(data) {
+                      const sourceContext = scopes.sources.getStore()?.assess;
+                      if (!sourceContext) return;
+
+                      const sourceInfo = {
+                        context: 'req._parsedUrl',
+                        data: req._parsedUrl,
+                        name,
+                        sourceContext,
+                        stacktraceOpts: {
+                          constructorOpt: data.hooked
+                        }
+                      };
+
+                      sources.handle({
+                        ...sourceInfo,
+                        inputType: InputType.URI,
+                        keys: ['href', 'path', 'pathname'],
+                      });
+
+                      sources.handle({
+                        ...sourceInfo,
+                        inputType: InputType.QUERYSTRING,
+                        keys: ['query', 'search'],
+                      });
+                    }
+                  });
+                }
+              });
+            }
+          });
+        }
+      );
+    }
+  };
+
+  return core.assess.dataflow.sources.expressInstrumentation.parsedUrl;
+};

package/lib/dataflow/sources/install/http.js

@@ -19,9 +19,9 @@ const { toLowerCase, InputType } = require('@contrast/common');
 
 module.exports = function(core) {
   const {
-    scopes: { sources },
+    scopes,
     instrumentation: { instrument },
-    assess: { dataflow: { sources: dataflowSources } },
+    assess: { dataflow },
     patcher,
   } = core;
 
@@ -40,7 +40,7 @@ module.exports = function(core) {
 
     try {
       const [, req, res] = data.args;
-      const store = sources.getStore();
+      const store = scopes.sources.getStore();
 
       if (!store) {
         logger.debug('cannot acquire store for assess request handling');
@@ -80,7 +80,7 @@ module.exports = function(core) {
         pre(data) {
           const [name = '', value] = data.args;
           if (toLowerCase(name) === 'content-type' && value) {
-            store.assess.responseData.contentType = value;
+            scopes.sources.getStore().assess.responseData.contentType = value;
           }
         }
       });
@@ -97,7 +97,6 @@ module.exports = function(core) {
       }
 
       const headers = {};
-      const sourceInputType = InputType.HEADER;
       const sourceName = 'ClientRequest';
 
       store.assess = {
@@ -107,22 +106,37 @@ module.exports = function(core) {
         findings: {},
       };
 
-      try {
-        dataflowSources.handle({
+      const sourceInfo = {
+        name: sourceName,
+        stacktraceOpts: {
+          constructorOpt: data.hooked,
+          prependFrames: [data.orig]
+        },
+        sourceContext: store.assess
+      };
+
+      [
+        {
           context: 'req.headers',
+          inputType: InputType.HEADER,
           data: req.headers,
-          inputType: sourceInputType,
-          name: sourceName,
-          stacktraceOpts: {
-            constructorOpt: data.hooked,
-            prependFrames: [data.orig]
-          },
-          sourceContext: store.assess
-        });
-
-      } catch (err) {
-        logger.error({ err, inputType: sourceInputType, name: sourceName }, 'unable to handle http source');
-      }
+          ...sourceInfo,
+        },
+        {
+          context: 'req',
+          keys: ['url'],
+          inputType: InputType.URI,
+          data: req,
+          ...sourceInfo,
+        }
+      ].forEach((sourceData) => {
+        const { inputType } = sourceData;
+        try {
+          dataflow.sources.handle(sourceData);
+        } catch (err) {
+          logger.error({ err, inputType, name: sourceName }, 'unable to handle http source');
+        }
+      });
 
       for (let i = 0; i < req.rawHeaders.length; i += 2) {
         const header = toLowerCase(req.rawHeaders[i]);

package/lib/dataflow/sources/install/querystring.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright: 2022 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 { InputType } = require('@contrast/common');
+const { patchType } = require('../common');
+
+module.exports = (core) => {
+  const { depHooks, patcher, logger } = core;
+
+  core.assess.dataflow.sources.querystringInstrumentation = {
+    install() {
+      const name = 'querystring.parse';
+      depHooks.resolve({ name: 'querystring' },
+        (querystring) => patcher.patch(querystring, 'parse', {
+          name,
+          patchType,
+          post({ args, hooked, orig, result }) {
+            const sourceContext = core.scopes.sources.getStore()?.assess;
+            const inputType = InputType.QUERYSTRING;
+
+            if (!sourceContext) {
+              logger.error({ name }, 'unable to handle source. Missing `sourceContext`');
+              return;
+            }
+
+            if (sourceContext.parsedQuery) {
+              logger.trace({ name }, 'values already tracked');
+              return;
+            }
+
+            // We only run analysis for the `querystring` result when it's used
+            // as the framework's query parser
+            if (sourceContext.reqData?.queries === args[0]) {
+              try {
+                core.assess.dataflow.sources.handle({
+                  context: 'req.query',
+                  name,
+                  inputType,
+                  stacktraceOpts: {
+                    constructorOpt: hooked,
+                    prependFrames: [orig]
+                  },
+                  data: result,
+                  sourceContext
+                });
+
+                // we do not set the `parsedQuery` value here so that frameworks
+                // may handle queries in their own more specific manner.
+              } catch (err) {
+                logger.error({ err, name }, 'unable to handle source');
+              }
+            }
+          }
+        })
+      );
+    }
+  };
+
+  return core.assess.dataflow.sources.querystringInstrumentation;
+};
+