@contrast/assess 1.49.0 → 1.51.0

package/lib/dataflow/propagation/install/string/split.js

@@ -15,13 +15,14 @@
 
 'use strict';
 
-const { primordials: { ArrayPrototypeJoin } } = require('@contrast/common');
+const { primordials: { ArrayPrototypeJoin, RegExpPrototypeExec } } = require('@contrast/common');
 const { createSubsetTags, getAdjustedUntrackedValue } = require('../../../tag-utils');
 const { patchType } = require('../../common');
 
 module.exports = function(core) {
   const {
     patcher,
+    scopes,
     assess: {
       getPropagatorContext,
       eventFactory,
@@ -32,13 +33,22 @@ module.exports = function(core) {
   return core.assess.dataflow.propagation.stringInstrumentation.split = {
     install() {
       const name = 'String.prototype.split';
+      const store = { lock: true, name };
 
       patcher.patch(String.prototype, 'split', {
         name,
         patchType,
         usePerf: 'sync',
+        around(next, data) {
+          // prevent instrumenting call to `exec` instance method when splitter is RegExp
+          return data.args[0] instanceof RegExp && !scopes.instrumentation.isLocked() ?
+            scopes.instrumentation.run(store, next) :
+            next();
+        },
         post(data) {
           const { name, args: origArgs, obj, result, hooked, orig } = data;
+          const splitterIsRx = origArgs[0] instanceof RegExp;
+
           if (
             !obj ||
             !result ||
@@ -46,68 +56,115 @@ module.exports = function(core) {
             result.length === 0 ||
             typeof obj !== 'string' ||
             (origArgs.length === 1 && origArgs[0] == null) ||
-            !getPropagatorContext()
+            !getPropagatorContext() ||
+            (!splitterIsRx && origArgs[0]?.[Symbol.split])
           ) return;
 
           const objInfo = tracker.getData(obj);
           if (!objInfo || obj === result[0]) return;
 
-          const args = origArgs.map((arg) => {
-            const argInfo = tracker.getData(arg);
-            return argInfo ?
-                { tracked: true, value: argInfo.value } :
-                { tracked: false, value: `'${arg}'` };
-          });
-
-          const event = eventFactory.createPropagationEvent({
-            name,
-            moduleName: 'String',
-            methodName: 'prototype.split',
-            context: `'${objInfo.value}'.split(${ArrayPrototypeJoin.call(args.map(a => a.value))})`,
-            history: [objInfo],
-            object: {
-              value: obj,
-              tracked: true,
-            },
-            args,
-            tags: {},
-            result: {
-              value: getAdjustedUntrackedValue(result),
-              tracked: false
-            },
-            stacktraceOpts: {
-              constructorOpt: hooked,
-              prependFrames: [orig]
-            },
-            source: 'O',
-            target: 'R'
-          });
-
-          if (!event) return;
-
-          let idx = 0;
+          let readIdx = 0;
+          let splitterRxGlobal;
+          let sepOffset;
+          let rxMatch;
+          let _event;
+
+          // make single global regex to check for calculating sepOffsets (vs using origArgs[0])
+          if (origArgs[0] instanceof RegExp) splitterRxGlobal = new RegExp(origArgs[0], 'g');
+
           for (let i = 0; i < result.length; i++) {
-            const res = result[i];
-            const start = obj.indexOf(res, idx);
-            idx += res.length;
-            const objSubstr = obj.substring(start, start + res.length);
-            const objSubstrInfo = tracker.getData(objSubstr);
-            if (objSubstrInfo) {
-              const tags = createSubsetTags(objInfo.tags, start, res.length);
-
-              if (!tags) continue;
-              const metadata = {
-                ...event,
-                result: { tracked: true, value: res },
-                tags,
-              };
-              eventFactory.createdEvents.add(metadata);
-              const { extern } = tracker.track(res, metadata);
-
-              if (extern) {
-                data.result[i] = extern;
+            let tags;
+            if (result[i].length) {
+              tags = createSubsetTags(objInfo.tags, readIdx, result[i].length);
+            }
+
+            if (tags) {
+              const metadata = makeEvent({
+                result: { tracked: true, value: result[i] },
+                tags: tags,
+              });
+
+              if (metadata) {
+                eventFactory.createdEvents.add(metadata);
+                const { extern } = tracker.track(result[i], metadata);
+                if (extern) data.result[i] = extern;
+              }
+            }
+
+            // increment read offset from element length
+            readIdx += result[i].length;
+
+            // calculate separator offset but don't increment until
+            // we check for regex capture groups in result below
+            if (splitterRxGlobal) {
+              rxMatch = RegExpPrototypeExec.call(splitterRxGlobal, obj);
+              if (rxMatch) sepOffset = rxMatch[0].length;
+            } else {
+              sepOffset = origArgs[0].length;
+            }
+
+            // handle if any regex matches are interleaved into the result
+            if (rxMatch) {
+              let groupIdx = rxMatch.length > 1 ? 1 : 0;
+
+              while (groupIdx && groupIdx < rxMatch.length) {
+                // move to next element in result
+                i++;
+
+                const tags = createSubsetTags(objInfo.tags, readIdx, rxMatch[groupIdx].length);
+                if (tags) {
+                  const metadata = makeEvent({
+                    result: { tracked: true, value: result[i] },
+                    tags: tags,
+                  });
+                  eventFactory.createdEvents.add(metadata);
+                  const { extern } = tracker.track(result[i], metadata);
+                  if (extern) data.result[i] = extern;
+                }
+                // increment read offset using rxMatch[groupIdx].length instead of sepOffset
+                readIdx += rxMatch[groupIdx].length;
+                groupIdx++;
               }
+            } else {
+              readIdx += sepOffset;
+            }
+          }
+
+          // Defer base event creation until needed. All events will share same
+          // common base event data that gets cached per propagator run.
+          function makeEvent(mergeData) {
+            if (!_event) {
+              const args = origArgs.map((arg) => {
+                const argInfo = tracker.getData(arg);
+                return argInfo ?
+                  { tracked: true, value: argInfo.value } :
+                  { tracked: false, value: `'${arg}'` };
+              });
+              _event = eventFactory.createPropagationEvent({
+                name,
+                moduleName: 'String',
+                methodName: 'prototype.split',
+                context: `'${objInfo.value}'.split(${ArrayPrototypeJoin.call(args.map(a => a.value))})`,
+                history: [objInfo],
+                object: {
+                  value: obj,
+                  tracked: true,
+                },
+                args,
+                tags: {},
+                result: {
+                  value: getAdjustedUntrackedValue(result),
+                  tracked: false
+                },
+                stacktraceOpts: {
+                  constructorOpt: hooked,
+                  prependFrames: [orig]
+                },
+                source: 'O',
+                target: 'R'
+              });
             }
+            return !_event ? null : { ..._event, ...mergeData };
           }
         },
       });

package/lib/dataflow/propagation/install/util-format.js

@@ -15,7 +15,7 @@
 
 'use strict';
 
-const { isString, primordials: { StringPrototypeMatch, StringPrototypeToLowerCase } } = require('@contrast/common');
+const { isString, primordials: { StringPrototypeMatch } } = require('@contrast/common');
 const { createAppendTags } = require('../../tag-utils');
 const { patchType } = require('../common');
 
@@ -47,7 +47,7 @@ module.exports = function(core) {
             let newTags = {};
             const history = [];
             const eventArgs = [];
-            const formatChars = args[0].includes('%') ? StringPrototypeMatch.call(args[0], /[^%]+/g).map((x) => x[0]) : [];
+            const formatChars = args[0].includes('%') ? StringPrototypeMatch.call(args[0], /%[sdifjoOc]/g).map((x) => x[1]) : [];
             let i = 0;
 
             if (formatChars.length > 0) {
@@ -58,14 +58,44 @@ module.exports = function(core) {
             for (i; i < args.length; i++) {
               let arg = args[i];
               const formatChar = formatChars[i - 1];
-              if (formatChar && typeof arg === 'object') {
-
-                if (formatChar === 'j') {
-                  arg = JSON.stringify(arg);
-                } else if (StringPrototypeToLowerCase.call(formatChar) === 'o') {
-                  // TO-DO: NODE-3235
+              if (formatChar) {
+                switch (formatChar) {
+                  case 's':
+                    if (typeof arg === 'object') {
+                      // util.inspect instrumentation NYI
+                      arg = arg?.toString ? arg.toString() : util.inspect(arg, { depth: 0, colors: false, compact: 3 });
+                    } else {
+                      arg = String(arg);
+                    }
+                    break;
+                  case 'd':
+                  case 'i':
+                  case 'f':
+                    // won't be tracked
+                    break;
+                  case 'j':
+                    arg = JSON.stringify(arg) ?? 'undefined';
+                    break;
+                  case 'o':
+                    // util.inspect instrumentation NYI
+                    arg = util.inspect(arg, { showHidden: true, showProxy: true });
+                    break;
+                  case 'O':
+                    // util.inspect instrumentation NYI
+                    arg = util.inspect(arg);
+                    break;
+                  case 'c':
+                    // c is ignored and skipped
+                    arg = '';
+                    break;
                 }
+              } else if (typeof arg !== 'string') {
+                arg = util.inspect(arg);
               }
+
+              const argInfo = tracker.getData(arg);
+              if (!argInfo) continue;
+
               const currIdx = result.indexOf(arg, idx);
               if (currIdx > -1) {
                 idx = currIdx + arg.length;
@@ -73,9 +103,6 @@ module.exports = function(core) {
                 continue;
               }
 
-              const argInfo = tracker.getData(arg);
-              if (!argInfo) continue;
-
               newTags = createAppendTags(newTags, argInfo.tags, currIdx);
 
               history.push({ ...argInfo });
@@ -120,8 +147,7 @@ module.exports = function(core) {
             }
           }
         });
-      }
-      );
+      });
     },
   };
 };

package/lib/dataflow/sources/handler.js

@@ -24,178 +24,182 @@ const {
     StringPrototypeToLowerCase
   }
 } = require('@contrast/common');
+const { Core } = require('@contrast/core/lib/ioc/core');
+
+module.exports = Core.makeComponent({
+  name: 'assess.dataflow.sources.handle',
+  factory(core) {
+    const {
+      assess: {
+        eventFactory,
+        dataflow: {
+          sources,
+          tracker
+        }
+      },
+      config,
+      createSnapshot,
+    } = core;
 
-module.exports = function (core) {
-  const {
-    assess: {
-      eventFactory,
-      dataflow: {
-        sources,
-        tracker
-      }
-    },
-    config,
-    createSnapshot,
-  } = core;
-
-  const logger = core.logger.child({ name: 'contrast:sources' });
+    const logger = core.logger.child({ name: 'contrast:sources' });
 
-  const emptyStack = Object.freeze([]);
+    const emptyStack = Object.freeze([]);
 
-  sources.createTags = function createTags({ inputType, fieldName = '', value, tagNames }) {
-    if (!value?.length) {
-      return null;
-    }
+    sources.createTags = function createTags({ inputType, fieldName = '', value, tagNames }) {
+      if (!value?.length) {
+        return null;
+      }
 
-    const stop = value.length - 1;
-    const tags = {
-      [DataflowTag.UNTRUSTED]: [0, stop]
-    };
+      const stop = value.length - 1;
+      const tags = {
+        [DataflowTag.UNTRUSTED]: [0, stop]
+      };
 
-    if (tagNames) {
-      for (const tag of tagNames) {
-        tags[tag] = [0, stop];
+      if (tagNames) {
+        for (const tag of tagNames) {
+          tags[tag] = [0, stop];
+        }
       }
-    }
 
-    if (inputType === InputType.HEADER && StringPrototypeToLowerCase.call(fieldName) === 'referer') {
-      tags[DataflowTag.HEADER] = [0, stop];
-    }
+      if (inputType === InputType.HEADER && StringPrototypeToLowerCase.call(fieldName) === 'referer') {
+        tags[DataflowTag.HEADER] = [0, stop];
+      }
 
-    return tags;
-  };
-
-  sources.createStacktrace = function (stacktraceOpts) {
-    return config.assess.stacktraces === 'NONE' || config.assess.stacktraces === 'SINK'
-      ? emptyStack
-      : createSnapshot(stacktraceOpts)();
-  };
-
-  sources.handle = function ({
-    context,
-    keys,
-    name,
-    inputType = InputType.UNKNOWN,
-    stacktraceOpts,
-    data,
-    sourceContext,
-  }) {
-    if (!data) return;
-
-    if (!sourceContext) {
-      logger.trace({ inputType, sourceName: name }, 'skipping assess source handling - no request context');
-      return null;
-    }
+      return tags;
+    };
 
-    // url exclusion
-    if (!sourceContext.policy) {
-      return null;
-    }
+    sources.createStacktrace = function(stacktraceOpts) {
+      return config.assess.stacktraces === 'NONE' || config.assess.stacktraces === 'SINK'
+        ? emptyStack
+        : createSnapshot(stacktraceOpts)();
+    };
 
-    if (!context) {
-      context = inputType;
-    }
+    sources.handle = function({
+      context,
+      keys,
+      name,
+      inputType = InputType.UNKNOWN,
+      stacktraceOpts,
+      data,
+      sourceContext,
+    }) {
+      if (!data) return;
+
+      if (!sourceContext) {
+        logger.trace({ inputType, sourceName: name }, 'skipping assess source handling - no request context');
+        return null;
+      }
 
-    const { policy: requestPolicy } = sourceContext;
-    const max = config.assess.max_context_source_events;
-    let _data = data;
-    let stack;
+      // url exclusion
+      if (!sourceContext.policy) {
+        return null;
+      }
 
-    if (keys) {
-      _data = {};
-      for (const key of keys) {
-        _data[key] = data[key];
+      if (!context) {
+        context = inputType;
       }
-    }
 
-    function createEvent({ fieldName, pathName, value, excludedRules }) {
-      const tagNames = Array.from(excludedRules).map((ruleId) => `excluded:${ruleId}`);
-      // 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, tagNames }),
-        result: { tracked: true, value },
-      });
-    }
+      const { policy: requestPolicy } = sourceContext;
+      const max = config.assess.max_context_source_events;
+      let _data = data;
+      let stack;
 
-    if (Buffer.isBuffer(data) && !tracker.getData(data)) {
-      const { track, excludedRules } = requestPolicy.getInputPolicy(InputType.BODY);
-      if (!track) {
-        core.logger.debug({ inputType }, 'assess input exclusion disabled tracking');
-        return;
+      if (keys) {
+        _data = {};
+        for (const key of keys) {
+          _data[key] = data[key];
+        }
       }
 
-      const event = createEvent({ pathName: 'body', value: data, fieldName: '', excludedRules });
-      if (event) {
-        tracker.track(data, event);
+      function createEvent({ fieldName, pathName, value, excludedRules }) {
+        const tagNames = Array.from(excludedRules).map((ruleId) => `excluded:${ruleId}`);
+        // 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, tagNames }),
+          result: { tracked: true, value },
+        });
       }
 
-      return;
-    }
-
-    traverse(_data, (path, fieldName, value, obj) => {
-      const pathName = ArrayPrototypeJoin.call(path, '.');
+      if (Buffer.isBuffer(data) && !tracker.getData(data)) {
+        const { track, excludedRules } = requestPolicy.getInputPolicy(InputType.BODY);
+        if (!track) {
+          core.logger.debug({ inputType }, 'assess input exclusion disabled tracking');
+          return;
+        }
 
-      if (sourceContext.sourceEventsCount >= max) {
-        logger.trace({ inputType, sourceName: name }, 'exiting assess source handling - %s max events exceeded', max);
-        return true;
-      }
+        const event = createEvent({ pathName: 'body', value: data, fieldName: '', excludedRules });
+        if (event) {
+          tracker.track(data, event);
+        }
 
-      const { track, excludedRules } = sourceContext.policy.getInputPolicy(inputType, fieldName);
-      if (!track) {
-        core.logger.debug({ fieldName, inputType }, 'assess input exclusion disabling tracking');
         return;
       }
 
-      if (isString(value) && value.length) {
-        const strInfo = tracker.getData(value);
-        if (strInfo) {
-          // TODO: confirm this "layering-on" approach is what we want
-          // when a value is already tracked, the handler will "re-track" 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;
+      traverse(_data, (path, fieldName, value, obj) => {
+        const pathName = ArrayPrototypeJoin.call(path, '.');
+
+        if (sourceContext.sourceEventsCount >= max) {
+          logger.trace({ inputType, sourceName: name }, 'exiting assess source handling - %s max events exceeded', max);
+          return true;
         }
-        const event = createEvent({ pathName, value, fieldName, excludedRules });
-        if (!event) {
-          logger.warn({ inputType, sourceName: name, pathName, value }, 'unable to create source event');
+
+        const { track, excludedRules } = sourceContext.policy.getInputPolicy(inputType, fieldName);
+        if (!track) {
+          core.logger.debug({ fieldName, inputType }, 'assess input exclusion disabling tracking');
           return;
         }
 
-        const { extern } = tracker.track(value, event);
-        if (extern) {
-          logger.trace({ extern, fieldName, sourceName: name, inputType }, 'tracked');
-          obj[fieldName] = extern;
-
-          sourceContext.sourceEventsCount++;
+        if (isString(value) && value.length) {
+          const strInfo = tracker.getData(value);
+          if (strInfo) {
+            // TODO: confirm this "layering-on" approach is what we want
+            // when a value is already tracked, the handler will "re-track" 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, excludedRules });
+          if (!event) {
+            logger.warn({ inputType, sourceName: name, pathName, value }, 'unable to create source event');
+            return;
+          }
+
+          const { extern } = tracker.track(value, event);
+          if (extern) {
+            logger.trace({ extern, fieldName, sourceName: name, inputType }, 'tracked');
+            obj[fieldName] = extern;
+
+            sourceContext.sourceEventsCount++;
+          }
+        } else if (Buffer.isBuffer(value) && !tracker.getData(value)) {
+          const event = createEvent({ pathName, value, fieldName, excludedRules });
+          if (event) {
+            tracker.track(value, event);
+          } else {
+            logger.warn({ inputType, sourceName: name, pathName, value }, 'unable to create source event');
+          }
         }
-      } else if (Buffer.isBuffer(value) && !tracker.getData(value)) {
-        const event = createEvent({ pathName, value, fieldName, excludedRules });
-        if (event) {
-          tracker.track(value, event);
-        } else {
-          logger.warn({ inputType, sourceName: name, pathName, value }, 'unable to create source event');
-        }
-      }
-    });
+      });
 
-    if (keys) {
-      for (const key of keys) {
-        data[key] = _data[key];
+      if (keys) {
+        for (const key of keys) {
+          data[key] = _data[key];
+        }
       }
-    }
 
-    return data;
-  };
+      return data;
+    };
 
-  return sources;
-};
+    return sources;
+  }
+});
 
 /**
  * A custom traversal function for handling source value tracking efficiently.

package/lib/dataflow/sources/index.js

@@ -20,8 +20,7 @@ const { callChildComponentMethodsSync } = require('@contrast/common');
 module.exports = function (core) {
   const sources = core.assess.dataflow.sources = {};
 
-  require('./handler')(core);
-
+  core.initComponentSync(require('./handler'));
   require('./install/express')(core);
   require('./install/fastify')(core);
   require('./install/hapi')(core);

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

@@ -74,6 +74,9 @@ module.exports = function init(core) {
                 name: 'express.middleware.init.expressInit',
                 patchType,
                 pre(data) {
+                  // no need to patch is assess is off
+                  if (!core.config.getEffectiveValue('assess.enable')) return;
+
                   patcher.patch(data.args, '2', {
                     name: 'express.middleware.init.expressInit.next',
                     patchType,

package/lib/event-factory.js

@@ -16,200 +16,204 @@
 'use strict';
 
 const { InputType, empties, primordials: { StringPrototypeMatch } } = require('@contrast/common');
+const { Core } = require('@contrast/core/lib/ioc/core');
 const ANNOTATION_REGEX = /^(A|O|R|P|P\d+)$/;
 const SOURCE_EVENT_MSG = 'Source event not created: %s';
 const PROPAGATION_EVENT_MSG = 'Propagation event not created: %s';
 
-module.exports = function (core) {
-  const {
-    createSnapshot,
-    config,
-    logger,
-    scopes: { sources },
-  } = core;
-
-  const eventFactory = core.assess.eventFactory = {};
-
-  eventFactory.createdEvents = new WeakSet();
-
-  eventFactory.createSourceEvent = function (data = {}) {
-    if (!data.result?.value) {
-      logger.debug(SOURCE_EVENT_MSG, `invalid result: ${data.name}`);
-      return null;
-    }
-    if (!data.name) {
-      logger.debug(SOURCE_EVENT_MSG, `invalid name: ${data.name}`);
-      return null;
-    }
-    if (!(data.inputType in InputType)) {
-      logger.debug(SOURCE_EVENT_MSG, `invalid inputType: ${data.name}`);
-      return null;
-    }
-    if (!data.tags) {
-      logger.debug(SOURCE_EVENT_MSG, `event has no tags: ${data.name}`);
-      return null;
-    }
-    if (!data.stack || !Array.isArray(data.stack)) {
-      logger.debug(SOURCE_EVENT_MSG, `invalid stack: ${data.name}`);
-      return null;
-    }
-
-    data.time = Date.now();
-    eventFactory.createdEvents.add(data);
-
-    return data;
-  };
-
-  eventFactory.createPropagationEvent = function (data) {
-    const sourceContext = sources.getStore()?.assess;
-
-    if (!sourceContext) {
-      logger.debug('No sourceContext found during Propagation event creation: %s', data.name);
-      return null;
-    }
-    if (sourceContext.propagationEventsCount >= config.assess.max_propagation_events) {
-      logger.debug('Maximum number of Propagation events reached. Event not created: %s', data.name);
-      return null;
-    }
-    if (!data.name) {
-      logger.debug(PROPAGATION_EVENT_MSG, `invalid name (${data.name})`);
-      return null;
-    }
-    if (!data.history.length) {
-      logger.debug(PROPAGATION_EVENT_MSG, `invalid history (${data.name})`);
-      return null;
-    }
-    if (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX)) {
-      logger.debug(PROPAGATION_EVENT_MSG, `invalid source (${data.name})`);
-      return null;
-    }
-    if (!data.target || !StringPrototypeMatch.call(data.target, ANNOTATION_REGEX)) {
-      logger.debug(PROPAGATION_EVENT_MSG, `invalid target (${data.name})`);
-      return null;
-    }
-
-    if (config.assess.stacktraces === 'ALL') {
-      data.stack = createSnapshot(data.stacktraceOpts)();
-    } else {
-      data.stack = empties.ARRAY;
-    }
-
-    data.args ??= empties.ARRAY;
-    data.addedTags ??= empties.ARRAY;
-    data.history ??= empties.ARRAY;
-    data.object ??= empties.UNTRACKED_VALUE_OBJ;
-    data.result ??= empties.UNTRACKED_VALUE_OBJ;
-    data.removedTags ??= empties.ARRAY;
-    data.time = Date.now();
-
-    eventFactory.createdEvents.add(data);
-    sourceContext.propagationEventsCount++;
-
-    return data;
-  };
-
-  eventFactory.createSinkEvent = function (data) {
-    const sourceContext = sources.getStore()?.assess;
-
-    if (!sourceContext) {
-      logger.debug('no sourceContext found during sink event creation: %s', data.name);
-      return null;
-    }
-    if (!data.name) {
-      logger.debug('no sink event name: %s', data.name);
-      return null;
-    }
-    if (!data.history.length) {
-      logger.debug('empty history for sink event: %s', data.name);
-      return null;
-    }
-    if (
-      (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX))
-    ) {
-      logger.debug('malformed or missing sink event source field: %s', data.name);
-      return null;
-    }
-
-    if (config.assess.stacktraces !== 'NONE') {
-      data.stack = createSnapshot(data.stacktraceOpts)();
-    } else {
-      data.stack = empties.ARRAY;
-    }
-
-    data.args ??= empties.ARRAY;
-    data.history ??= empties.ARRAY;
-    data.object ??= empties.ARRAY;
-    data.result ??= empties.UNTRACKED_VALUE_OBJ;
-    data.time = Date.now();
-
-    eventFactory.createdEvents.add(data);
-
-    return data;
-  };
-
-  eventFactory.createSessionEvent = function (data) {
-    if (!data.name) {
-      logger.debug('no sink event name: %s', data.name);
-      return null;
-    }
-    if (
-      (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX))
-    ) {
-      logger.debug('malformed or missing sink event source field: %s', data.name);
-      return null;
-    }
-    if (config.assess.stacktraces !== 'NONE') {
-      data.stack = createSnapshot(data.stacktraceOpts)();
-    } else {
-      data.stack = empties.ARRAY;
-    }
-
-    data.args ??= empties.ARRAY;
-    data.history ??= empties.ARRAY;
-    data.obj ??= empties.UNTRACKED_VALUE_OBJ;
-    data.result ??= empties.UNTRACKED_VALUE_OBJ;
-    data.tags ??= empties.OBJECT;
-    data.time = Date.now();
-
-    eventFactory.createdEvents.add(data);
-
-    return data;
-  };
-
-  /**
-   * @param {{
-   *  context: string,
-   *  name: string,
-   *  moduleName: string,
-   *  methodName: string,
-   *  object: { value: any, tracked: boolean },
-   *  args: any[],
-   *  result: { value: vany, tracked: boolean },
-   *  source: string,
-   *  stacktraceOpts: { constructorOpt?: Function},
-   * }} data
-   * @returns {any}
-   */
-  eventFactory.createCryptoAnalysisEvent = function (data) {
-    if (!data.name) {
-      logger.debug('no sink event name: %s', data.name);
-      return null;
-    }
-    if (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX)) {
-      logger.debug('malformed or missing sink event source field: %s', data.name);
-      return null;
-    }
-    if (config.assess.stacktraces !== 'NONE') {
-      data.stack = createSnapshot(data.stacktraceOpts)();
-    } else {
-      data.stack = empties.ARRAY;
-    }
-
-    data.time = Date.now();
-    eventFactory.createdEvents.add(data);
-
-    return data;
-  };
-
-  return eventFactory;
-};
+module.exports = Core.makeComponent({
+  name: 'assess.eventFactory',
+  factory(core) {
+    const {
+      createSnapshot,
+      config,
+      logger,
+      scopes: { sources },
+    } = core;
+
+    const eventFactory = core.assess.eventFactory = {};
+
+    eventFactory.createdEvents = new WeakSet();
+
+    eventFactory.createSourceEvent = function(data = {}) {
+      if (!data.result?.value) {
+        logger.debug(SOURCE_EVENT_MSG, `invalid result: ${data.name}`);
+        return null;
+      }
+      if (!data.name) {
+        logger.debug(SOURCE_EVENT_MSG, `invalid name: ${data.name}`);
+        return null;
+      }
+      if (!(data.inputType in InputType)) {
+        logger.debug(SOURCE_EVENT_MSG, `invalid inputType: ${data.name}`);
+        return null;
+      }
+      if (!data.tags) {
+        logger.debug(SOURCE_EVENT_MSG, `event has no tags: ${data.name}`);
+        return null;
+      }
+      if (!data.stack || !Array.isArray(data.stack)) {
+        logger.debug(SOURCE_EVENT_MSG, `invalid stack: ${data.name}`);
+        return null;
+      }
+
+      data.time = Date.now();
+      eventFactory.createdEvents.add(data);
+
+      return data;
+    };
+
+    eventFactory.createPropagationEvent = function(data) {
+      const sourceContext = sources.getStore()?.assess;
+
+      if (!sourceContext) {
+        logger.debug('No sourceContext found during Propagation event creation: %s', data.name);
+        return null;
+      }
+      if (sourceContext.propagationEventsCount >= config.assess.max_propagation_events) {
+        logger.debug('Maximum number of Propagation events reached. Event not created: %s', data.name);
+        return null;
+      }
+      if (!data.name) {
+        logger.debug(PROPAGATION_EVENT_MSG, `invalid name (${data.name})`);
+        return null;
+      }
+      if (!data.history.length) {
+        logger.debug(PROPAGATION_EVENT_MSG, `invalid history (${data.name})`);
+        return null;
+      }
+      if (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX)) {
+        logger.debug(PROPAGATION_EVENT_MSG, `invalid source (${data.name})`);
+        return null;
+      }
+      if (!data.target || !StringPrototypeMatch.call(data.target, ANNOTATION_REGEX)) {
+        logger.debug(PROPAGATION_EVENT_MSG, `invalid target (${data.name})`);
+        return null;
+      }
+
+      if (config.assess.stacktraces === 'ALL') {
+        data.stack = createSnapshot(data.stacktraceOpts)();
+      } else {
+        data.stack = empties.ARRAY;
+      }
+
+      data.args ??= empties.ARRAY;
+      data.addedTags ??= empties.ARRAY;
+      data.history ??= empties.ARRAY;
+      data.object ??= empties.UNTRACKED_VALUE_OBJ;
+      data.result ??= empties.UNTRACKED_VALUE_OBJ;
+      data.removedTags ??= empties.ARRAY;
+      data.time = Date.now();
+
+      eventFactory.createdEvents.add(data);
+      sourceContext.propagationEventsCount++;
+
+      return data;
+    };
+
+    eventFactory.createSinkEvent = function(data) {
+      const sourceContext = sources.getStore()?.assess;
+
+      if (!sourceContext) {
+        logger.debug('no sourceContext found during sink event creation: %s', data.name);
+        return null;
+      }
+      if (!data.name) {
+        logger.debug('no sink event name: %s', data.name);
+        return null;
+      }
+      if (!data.history.length) {
+        logger.debug('empty history for sink event: %s', data.name);
+        return null;
+      }
+      if (
+        (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX))
+      ) {
+        logger.debug('malformed or missing sink event source field: %s', data.name);
+        return null;
+      }
+
+      if (config.assess.stacktraces !== 'NONE') {
+        data.stack = createSnapshot(data.stacktraceOpts)();
+      } else {
+        data.stack = empties.ARRAY;
+      }
+
+      data.args ??= empties.ARRAY;
+      data.history ??= empties.ARRAY;
+      data.object ??= empties.ARRAY;
+      data.result ??= empties.UNTRACKED_VALUE_OBJ;
+      data.time = Date.now();
+
+      eventFactory.createdEvents.add(data);
+
+      return data;
+    };
+
+    eventFactory.createSessionEvent = function(data) {
+      if (!data.name) {
+        logger.debug('no sink event name: %s', data.name);
+        return null;
+      }
+      if (
+        (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX))
+      ) {
+        logger.debug('malformed or missing sink event source field: %s', data.name);
+        return null;
+      }
+      if (config.assess.stacktraces !== 'NONE') {
+        data.stack = createSnapshot(data.stacktraceOpts)();
+      } else {
+        data.stack = empties.ARRAY;
+      }
+
+      data.args ??= empties.ARRAY;
+      data.history ??= empties.ARRAY;
+      data.obj ??= empties.UNTRACKED_VALUE_OBJ;
+      data.result ??= empties.UNTRACKED_VALUE_OBJ;
+      data.tags ??= empties.OBJECT;
+      data.time = Date.now();
+
+      eventFactory.createdEvents.add(data);
+
+      return data;
+    };
+
+    /**
+     * @param {{
+     *  context: string,
+     *  name: string,
+     *  moduleName: string,
+     *  methodName: string,
+     *  object: { value: any, tracked: boolean },
+     *  args: any[],
+     *  result: { value: vany, tracked: boolean },
+     *  source: string,
+     *  stacktraceOpts: { constructorOpt?: Function},
+     * }} data
+     * @returns {any}
+     */
+    eventFactory.createCryptoAnalysisEvent = function(data) {
+      if (!data.name) {
+        logger.debug('no sink event name: %s', data.name);
+        return null;
+      }
+      if (!data.source || !StringPrototypeMatch.call(data.source, ANNOTATION_REGEX)) {
+        logger.debug('malformed or missing sink event source field: %s', data.name);
+        return null;
+      }
+      if (config.assess.stacktraces !== 'NONE') {
+        data.stack = createSnapshot(data.stacktraceOpts)();
+      } else {
+        data.stack = empties.ARRAY;
+      }
+
+      data.time = Date.now();
+      eventFactory.createdEvents.add(data);
+
+      return data;
+    };
+
+    return eventFactory;
+  }
+});

package/lib/index.js

@@ -17,6 +17,7 @@
 
 const { inspect } = require('util');
 const { callChildComponentMethodsSync } = require('@contrast/common');
+const { ConfigSource } = require('@contrast/config');
 
 module.exports = function assess(core) {
   const {
@@ -27,7 +28,15 @@ module.exports = function assess(core) {
 
   const assess = core.assess = {
     install() {
-      if (!config.getEffectiveValue('assess.enable')) {
+      // only force instrumentation if assess is explicitly enabled in local config
+      const forceInstrumentation =
+        config.preinstrument &&
+        config.getEffectiveSource('assess.enable') !== ConfigSource.DEFAULT_VALUE;
+
+      if (
+        !forceInstrumentation &&
+        !config.getEffectiveValue('assess.enable')
+      ) {
         core.logger.debug('assess is disabled, skipping installation');
         return;
       }
@@ -52,10 +61,10 @@ module.exports = function assess(core) {
   // ancillary tools used by different features
   require('./sampler')(core);
   require('./get-policy')(core);
-  require('./make-source-context')(core);
+  core.initComponentSync(require('./make-source-context'));
   require('./rule-scopes')(core);
   require('./get-source-context')(core);
-  require('./event-factory')(core);
+  core.initComponentSync(require('./event-factory'));
 
   // various Assess features
   require('./dataflow')(core);

package/lib/make-source-context.js

@@ -16,75 +16,85 @@
 'use strict';
 
 const { primordials: { StringPrototypeToLowerCase, StringPrototypeSlice } } = require('@contrast/common');
+const { Core } = require('@contrast/core/lib/ioc/core');
+
 /**
  * @param {{
  *  assess: import('@contrast/assess').Assess,
  *  logger: import('@contrast/logger').Logger,
  * }} core
  */
-module.exports = function(core) {
-  const { assess, logger } = core;
+module.exports = Core.makeComponent({
+  name: 'assess.makeSourceContext',
+  factory(core) {
+    const { assess, logger } = core;
 
-  /**
-   * @returns {import('@contrast/assess').SourceContext}
-   */
-  return core.assess.makeSourceContext = function (sourceData) {
-    try {
-      // todo: how to handle non-HTTP sources
-      const { incomingMessage: req } = sourceData;
+    /**
+     * @returns {import('@contrast/assess').SourceContext}
+     */
+    return core.assess.makeSourceContext = function(sourceData) {
+      try {
 
-      // minimally process the request data for sampling and exclusions.
-      // more request fields will be appended in final result below.
-      let uriPath;
-      let queries;
-      const idx = req.url.indexOf('?');
-      if (idx >= 0) {
-        uriPath = StringPrototypeSlice.call(req.url, 0, idx);
-        queries = StringPrototypeSlice.call(req.url, idx + 1);
-      } else {
-        uriPath = req.url;
-        queries = '';
-      }
+        const ctx = sourceData.store.assess = {
+          // default policy to `null` until it is set later below. this will cause
+          // all instrumentation to short-circuit, see `./get-source-context.js`.
+          policy: null,
+        };
+
+        if (!core.config.getEffectiveValue('assess.enable')) {
+          return ctx;
+        }
 
-      const ctx = sourceData.store.assess = {
-        // default policy to `null` until it is set later below. this will cause
-        // all instrumentation to short-circuit, see `./get-source-context.js`.
-        policy: null,
-        reqData: {
+        // todo: how to handle non-HTTP sources
+        const { incomingMessage: req } = sourceData;
+
+        // minimally process the request data for sampling and exclusions.
+        // more request fields will be appended in final result below.
+        let uriPath;
+        let queries;
+        const idx = req.url.indexOf('?');
+        if (idx >= 0) {
+          uriPath = StringPrototypeSlice.call(req.url, 0, idx);
+          queries = StringPrototypeSlice.call(req.url, idx + 1);
+        } else {
+          uriPath = req.url;
+          queries = '';
+        }
+        ctx.reqData = {
           method: req.method,
           uriPath,
           queries,
-        },
-      };
+        };
 
-      // check whether sampling allows processing
-      ctx.sampleInfo = assess.sampler?.getSampleInfo(sourceData) ?? null;
-      if (ctx.sampleInfo?.canSample === false) return ctx;
+        // check whether sampling allows processing
+        ctx.sampleInfo = assess.sampler?.getSampleInfo(sourceData) ?? null;
+        if (ctx.sampleInfo?.canSample === false) return ctx;
 
-      // set policy - can be returned as `null` if request is url-excluded.
-      ctx.policy = assess.getPolicy(ctx.reqData);
-      if (!ctx.policy) return ctx;
+        // set policy - can be returned as `null` if request is url-excluded.
+        ctx.policy = assess.getPolicy(ctx.reqData);
+        if (!ctx.policy) return ctx;
 
-      // build remaining reqData
-      ctx.reqData.headers = { ...req.headers }; // copy to avoid storing tracked values
-      ctx.reqData.ip = req.socket.remoteAddress;
-      ctx.reqData.httpVersion = req.httpVersion;
-      if (ctx.reqData.headers['content-type'])
-        ctx.reqData.contentType = StringPrototypeToLowerCase.call(ctx.reqData.headers['content-type']);
+        // build remaining reqData
+        ctx.reqData.headers = { ...req.headers }; // copy to avoid storing tracked values
+        ctx.reqData.ip = req.socket.remoteAddress;
+        ctx.reqData.httpVersion = req.httpVersion;
+        if (ctx.reqData.headers['content-type'])
+          ctx.reqData.contentType = StringPrototypeToLowerCase.call(ctx.reqData.headers['content-type']);
 
-      return {
-        ...ctx,
-        propagationEventsCount: 0,
-        sourceEventsCount: 0,
-        responseData: {},
-        ruleState: {},
-      };
-    } catch (err) {
-      logger.error(
-        { err },
-        'unable to construct assess store. assess will be disabled for request.'
-      );
-      return null;
-    }
-  };
-};
+        return {
+          ...ctx,
+          propagationEventsCount: 0,
+          sourceEventsCount: 0,
+          responseData: {},
+          ruleState: {},
+        };
+      } catch (err) {
+        logger.error(
+          { err },
+          'unable to construct assess store. assess will be disabled for request.'
+        );
+        return null;
+      }
+    };
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "description": "Contrast service providing framework-agnostic Assess support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -20,17 +20,17 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.31.0",
-    "@contrast/config": "1.42.0",
-    "@contrast/core": "1.47.0",
-    "@contrast/dep-hooks": "1.16.0",
+    "@contrast/common": "1.32.0",
+    "@contrast/config": "1.44.0",
+    "@contrast/core": "1.49.0",
+    "@contrast/dep-hooks": "1.18.0",
     "@contrast/distringuish": "^5.1.0",
-    "@contrast/instrumentation": "1.26.0",
-    "@contrast/logger": "1.20.0",
-    "@contrast/patcher": "1.19.0",
-    "@contrast/rewriter": "1.23.0",
-    "@contrast/route-coverage": "1.37.0",
-    "@contrast/scopes": "1.17.0",
+    "@contrast/instrumentation": "1.28.0",
+    "@contrast/logger": "1.22.0",
+    "@contrast/patcher": "1.21.0",
+    "@contrast/rewriter": "1.25.0",
+    "@contrast/route-coverage": "1.39.0",
+    "@contrast/scopes": "1.19.0",
     "semver": "^7.6.0"
   }
 }