@contrast/agent 4.24.2 → 4.25.1

package/lib/assess/express/sources.js

@@ -15,21 +15,22 @@ Copyright: 2022 Contrast Security, Inc
 'use strict';
 
 const agentEmitter = require('../../agent-emitter');
-const Helpers = require('../../core/express/utils');
+const { EVENTS } = require('../../core/express/utils');
 const {
-  prototype: { decorateRequest }
+  prototype: { decorateRequest },
 } = require('../../hooks/frameworks/base');
-const { EVENTS } = Helpers;
 
 class ExpressSources {
   constructor() {
     agentEmitter.on(EVENTS.REQUEST_READY, ExpressSources.handleReady);
     agentEmitter.on(EVENTS.BODY_PARSED, ExpressSources.handleBody);
     agentEmitter.on(EVENTS.COOKIES_PARSED, ExpressSources.handleCookies);
-    agentEmitter.on(EVENTS.PARAM_PARSED, ExpressSources.handleParams);
+    agentEmitter.on(EVENTS.PARAMS_PARSED, ExpressSources.handleParams);
   }
 
   static handleReady(req, res, inputType) {
+    agentEmitter.emit('assess.url', req, '_parsedUrl');
+    req.originalUrl !== '/' && agentEmitter.emit('assess.url', req, 'originalUrl');
     agentEmitter.emit('assess.query', req, 'query');
     agentEmitter.emit('assess.headers', req, 'headers');
   }

package/lib/assess/membrane/source-membrane.js

@@ -133,7 +133,7 @@ module.exports = class SourceMembrane extends Membrane {
    * @return {string} returns tracked string with proper contrastProps
    */
   onString(str, metadata) {
-    if (!this.ensureMetadata(metadata)) {
+    if (!this.ensureMetadata(metadata) && !metadata.rootLevelString) {
       return str;
     }
     const tracked = tracker.track(str);

package/lib/assess/models/call-context.js

@@ -18,9 +18,9 @@ const util = require('util');
 const CleanStack = require('../../util/clean-stack');
 const tracker = require('../../tracker');
 const stackFactory = require('../../core/stacktrace').singleton;
-const distringuish = require('@contrast/distringuish-prebuilt');
 const { PROXY_TARGET } = require('../../../lib/constants');
 const TagRange = require('../models/tag-range');
+const { toUntrackedString } = require('../utils');
 
 /**
  * Holds information about the call context of a function
@@ -116,12 +116,13 @@ module.exports = class CallContext {
         }
         if (arg[key] && typeof arg[key] === 'object' && iteration < 100) {
           return CallContext.hasTrackedArg(arg[key], iteration += 1);
-        }  
+        }
       }
     }
     return false;
   }
 
+  // eslint-disable-next-line complexity
   static getDisplayRange(arg, orgArg = arg, iteration = 0) {
     if (tracker.getData(arg)) {
       return new TagRange(0, arg.length - 1, 'untrusted');
@@ -188,17 +189,7 @@ module.exports = class CallContext {
    */
   static valueString(value) {
     if (_.isString(value)) {
-      // NODE-933 - we need to be careful not to assign
-      // external strings to something that is referenced by its'
-      // own properties.  For source strings we were creating
-      // a CallContext with the string, adding it to the SourceEvent,
-      // and then that SourceEvent was added to the external strings
-      // props.  So there was a circular ref between the string
-      // and it's props, preventing either from being freed.
-      if (distringuish.isExternal(value.valueOf())) {
-        return distringuish.internalize(value.valueOf());
-      }
-      return value.valueOf();
+      return toUntrackedString(value);
     }
 
     if (_.isNumber(value)) {

package/lib/assess/sources/index.js

@@ -12,277 +12,236 @@ Copyright: 2022 Contrast Security, Inc
   engineered, modified, repackaged, sold, redistributed or otherwise used in a
   way not consistent with the End User License Agreement.
 */
-/**
- * @module /lib/assess/sources
- */
-
 'use strict';
-const logger = require('../../core/logger')('contrast:assess:sources');
-const FormidableSource = require('./formidable');
+
+const parseurl = require('parseurl');
 const agentEmitter = require('../../agent-emitter');
-const SourceMembrane = require('../membrane/source-membrane');
 const { AsyncStorage, KEYS } = require('../../core/async-storage');
-const parseurl = require('parseurl');
-const {
-  EXCLUSION_INPUT_TYPES: { BODY, HEADER, PARAMETER, QUERYSTRING, COOKIE }
-} = require('../../constants');
+const logger = require('../../core/logger')('contrast:assess:sources');
+const { EXCLUSION_INPUT_TYPES } = require('../../constants');
+const SourceMembrane = require('../membrane/source-membrane');
 const { Signature } = require('../models');
-
-const sources = module.exports;
-
 const { SourceEventHandler } = require('./event-handler');
+const FormidableSource = require('./formidable');
 
 /**
- * Registers sources for assess instrumentation
- */
-sources.init = function(agent) {
-  new FormidableSource(agent);
-};
-
-/**
- * @param {string} type name of source type (headers, params, etc)
- * @param {Object} parent object to watch property on, e.g., req
- * @param {string} key name of property (for req.query, 'query')
- * @param {Membrane} membrane used in testing to provide a custom membrane instance
+ * Shared logging for when URL/Input exclusions thwart handling of sources.
+ * @param {string} type the source type e.g. BODY, PARAMETER, HEADER
  */
-sources.track = function(type, parent, key, membrane) {
-  const object = parent[key];
-  if (!object) {
-    return;
-  }
-  const metadata = Object.create(null);
-  metadata.sourceType = type;
-  parent[key] = membrane.wrap(object, metadata);
+const logExclusionMessage = (type, exclusion) => {
+  const { name } = exclusion;
+  logger.debug(
+    'excluding %s inputs from all assess rules (%s)',
+    type.toLowerCase(),
+    name
+  );
 };
 
-/**
- * Chooses a strategy for tracking the source events
- * @param {any} config Current configuration for the agent
- * @param {Logger} logger A logger instance
- * @returns {Boolean} whether lazy tracking is enabled or not
- */
-sources.getLazyTrackingConfig = function(config, logger) {
-  if (config._default['agent.traverse_and_track']) {
-    return config.assess.enable_lazy_tracking;
-  }
-  if (config._default['assess.enable_lazy_tracking']) {
-    logger.error('agent.traverse_and_track option is deprecated. Please use assess.enable_lazy_tracking from now on. It\'s value should be the opposite of this one');
-    return !config.agent.traverse_and_track;
-  }
-
-  logger.error('Conflicting options set: `agent.traverse_and_track` and `assess.enable_lazy_tracking`. `agent.traverse_and_track` is deprecated, so `assess.enable_lazy_tracking` takes precedence');
-  return config.assess.enable_lazy_tracking;
-};
+module.exports = {
+  /**
+   * Registers sources for assess instrumentation
+   */
+  init(agent) {
+    new FormidableSource(agent);
+  },
+
+  /**
+   * @param {string} type name of source type (headers, params, etc)
+   * @param {Object} parent object to watch property on, e.g., req
+   * @param {string} key name of property (for req.query, 'query')
+   * @param {Membrane} membrane used in testing to provide a custom membrane instance
+   */
+  track(type, parent, key, membrane) {
+    const object = parent[key];
+    if (!object) {
+      return;
+    }
+    const metadata = Object.create(null);
+    metadata.sourceType = type;
 
-/**
- * Registers an event to add URL and input exclusions to async storage if they
- * pertain to the current request path. Also registers all the source events
- * that are emitted in the framework instrumentation sources. This wraps an
- * object in a membrane
- */
-sources.registerListeners = function({ config, exclusions }) {
-  const isLazyTrackingEnabled = sources.getLazyTrackingConfig(config, logger);
+    // We set this flag for string properties that are direct properties
+    // of the request object. Unlike parsed querystring values like
+    // { input: 'userInput' } these properties have an empty path, but still
+    // need to be tracked
+    metadata.rootLevelString = false;
 
-  agentEmitter.on('assess.body', (obj, prop) => {
-    if (isLazyTrackingEnabled) {
-      return sources.handleSourceEvent(config, exclusions, BODY, obj, prop);
+    if (key === 'originalUrl') {
+      metadata.rootLevelString = true;
     }
 
-    agentEmitter.emit('assess.source', {
-      config,
-      exclusions,
-      obj,
-      prop,
-      data: obj[prop],
-      type: BODY
-    });
-  });
-  agentEmitter.on('assess.headers', (obj, prop) => {
-    if (isLazyTrackingEnabled) {
-      return sources.handleSourceEvent(config, exclusions, HEADER, obj, prop);
+    parent[key] = membrane.wrap(object, metadata);
+  },
+
+  /**
+   * Chooses a strategy for tracking the source events
+   * @param {any} config Current configuration for the agent
+   * @param {Logger} logger A logger instance
+   * @returns {Boolean} whether lazy tracking is enabled or not
+   */
+  getLazyTrackingConfig(config, logger) {
+    if (config._default['agent.traverse_and_track']) {
+      return config.assess.enable_lazy_tracking;
     }
 
-    agentEmitter.emit('assess.source', {
-      obj,
-      prop,
-      data: obj[prop],
-      type: HEADER
-    });
-  });
-  agentEmitter.on('assess.params', (obj, prop) => {
-    if (isLazyTrackingEnabled) {
-      return sources.handleSourceEvent(
-        config,
-        exclusions,
-        PARAMETER,
-        obj,
-        prop
+    if (config._default['assess.enable_lazy_tracking']) {
+      logger.error(
+        "agent.traverse_and_track option is deprecated. Please use assess.enable_lazy_tracking from now on. It's value should be the opposite of this one"
       );
+      return !config.agent.traverse_and_track;
     }
 
-    agentEmitter.emit('assess.source', {
-      obj,
-      prop,
-      data: obj[prop],
-      type: PARAMETER
-    });
-  });
-  agentEmitter.on('assess.query', (obj, prop) => {
-    if (isLazyTrackingEnabled) {
-      return sources.handleSourceEvent(
+    logger.error(
+      'Conflicting options set: `agent.traverse_and_track` and `assess.enable_lazy_tracking`. `agent.traverse_and_track` is deprecated, so `assess.enable_lazy_tracking` takes precedence'
+    );
+    return config.assess.enable_lazy_tracking;
+  },
+
+  /**
+   * Registers an event to add URL and input exclusions to async storage if they
+   * pertain to the current request path. Also registers all the source events
+   * that are emitted in the framework instrumentation sources. This wraps an
+   * object in a membrane
+   */
+  registerListeners({ config, exclusions }) {
+    const isLazyTrackingEnabled = this.getLazyTrackingConfig(config, logger);
+
+    const handleAssessEvent = (event, type) => {
+      agentEmitter.on(event, (obj, prop) => {
+        if (isLazyTrackingEnabled) {
+          return this.handleSourceEvent(config, exclusions, type, obj, prop);
+        }
+
+        const signature = new Signature({
+          moduleName: 'Object',
+          methodName: 'getter',
+          args: [prop],
+          return: 'String',
+          isModule: false,
+        });
+
+        new SourceEventHandler({ config, exclusions, signature, type }).handle({
+          obj,
+          prop,
+        });
+      });
+    };
+
+    handleAssessEvent('assess.url', EXCLUSION_INPUT_TYPES.PARAMETER);
+    handleAssessEvent('assess.body', EXCLUSION_INPUT_TYPES.BODY);
+    handleAssessEvent('assess.headers', EXCLUSION_INPUT_TYPES.HEADER);
+    handleAssessEvent('assess.params', EXCLUSION_INPUT_TYPES.PARAMETER);
+    handleAssessEvent('assess.query', EXCLUSION_INPUT_TYPES.QUERYSTRING);
+    handleAssessEvent('assess.cookies', EXCLUSION_INPUT_TYPES.COOKIE);
+
+    // might be helpful for clients to send add'l values in event arg
+    //   - stackOpts: elide frames from function ref in client instrumentation
+    //   - signature: rather than create shared one in the handler
+    //   - or stack snapshot function - could share among SourceEvents
+    //   - call context to share among SourceEvents
+    agentEmitter.on('assess.source', ({ obj, prop, type, signature }) => {
+      if (!signature) {
+        signature = new Signature({
+          moduleName: 'Object',
+          methodName: 'getter',
+          args: [prop],
+          return: 'String',
+          isModule: false,
+        });
+      }
+
+      new SourceEventHandler({
         config,
         exclusions,
-        QUERYSTRING,
-        obj,
+        signature,
+        type,
+        stackOpts: undefined,
+        snapshot: undefined,
+      }).handle({ obj, prop });
+    });
+  },
+
+  /**
+   * Checks whether exclusions settings should prevent wrapping of the untrusted
+   * data in membrane. If we should wrap, we create a membrane and provide it with
+   * active input exclusions to modify onString behaviors.
+   * @param {object} config agent config used to create membrane
+   * @param {ExclusionFactory} exclusions exclusions applicable to current req url
+   * @param {string} type source type
+   * @param {*} obj proxy target
+   * @param {string} prop property name
+   */
+  handleSourceEvent(config, exclusions, type, obj, prop) {
+    const req = AsyncStorage.get(KEYS.REQ);
+    // NODE-1431: prevents crashing when req is not present in AsyncStorage.
+    if (!req) {
+      logger.error(
+        'failed to handle source event for type: %s, property: %s; req not present in async storage',
+        type,
         prop
       );
+      return;
     }
 
-    agentEmitter.emit('assess.source', {
-      obj,
-      prop,
-      data: obj[prop],
-      type: QUERYSTRING
-    });
-  });
-
-  agentEmitter.on('assess.cookies', (obj, prop) => {
-    if (isLazyTrackingEnabled) {
-      return sources.handleSourceEvent(config, exclusions, COOKIE, obj, prop);
-    }
-
-    agentEmitter.emit('assess.source', {
-      obj,
-      prop,
-      type: COOKIE
-    });
-  });
-
-  // might be helpful for clients to send add'l values in event arg
-  //   - stackOpts: elide frames from function ref in client instrumentation
-  //   - signature: rather than create shared one in the handler
-  //   - or stack snapshot function - could share among SourceEvents
-  //   - call context to share among SourceEvents
-  agentEmitter.on('assess.source', ({ obj, prop, type, signature }) => {
-    if (!signature) {
-      signature = new Signature({
-        moduleName: 'Object',
-        methodName: 'getter',
-        args: [prop],
-        return: 'String',
-        isModule: false
-      });
+    const { pathname } = parseurl(req);
+    const urlExclusions = exclusions
+      .getUrlExclusions('assess')
+      .filter((e) => e.matchesUrl(pathname));
+    const inputExclusions = exclusions
+      .getInputExclusions('assess')
+      .filter((e) => e.matchesUrl(pathname) && e.appliesToInputType(type));
+
+    if (
+      this.exclusionSourceEventFilter({
+        type,
+        urlExclusions,
+        inputExclusions,
+      })
+    ) {
+      return;
     }
 
-    new SourceEventHandler({
-      config,
-      exclusions,
-      signature,
-      type,
-      stackOpts: undefined,
-      snapshot: undefined
-    }).handle({ obj, prop });
-  });
-};
-
-/**
- * Checks whether exclusions settings should prevent wrapping of the untrusted
- * data in membrane. If we should wrap, we create a membrane and provide it with
- * active input exclusions to modify onString behaviors.
- * @param {object} config agent config used to create membrane
- * @param {ExclusionFactory} exclusions exclusions applicable to current req url
- * @param {string} type source type
- * @param {*} obj proxy target
- * @param {string} prop property name
- */
-sources.handleSourceEvent = function(config, exclusions, type, obj, prop) {
-  const req = AsyncStorage.get(KEYS.REQ);
-  // NODE-1431: prevents crashing when req is not present in AsyncStorage.
-  if (!req) {
-    logger.error(
-      'failed to handle source event for type: %s, property: %s; req not present in async storage',
+    const sourceParams = {
       type,
-      prop
+      object: obj[prop],
+      constructorOpt: agentEmitter.emit,
+      inputExclusions,
+    };
+
+    const membrane = new SourceMembrane(config, sourceParams);
+    this.track(type.toLowerCase(), obj, prop, membrane);
+  },
+
+  /**
+   * Event filter function returns `false` if source event shouldn't be published.
+   * If there is a URL Exclusion for all rules, then don't bother tracking inputs.
+   * Otherwise, we have logic in TSReporter to skip reporting for URL Exclusions
+   * for specific rules.
+   * And some Input Exclusions apply broadly to the type. If they also apply to
+   * all rules we can skip the source event outright.
+   * @param {object} params
+   * @param {string} params.type
+   * @param {object[]} params.urlExclusions
+   * @param {object[]} params.inputExclusions
+   * @returns {boolean}
+   */
+  exclusionSourceEventFilter({ type, urlExclusions, inputExclusions }) {
+    const urlMatch = urlExclusions.find((e) => e.appliesToAllAssessRules());
+    if (urlMatch) {
+      logExclusionMessage(type, urlMatch);
+      return true;
+    }
+    // `isNamed` is false for exclusion types such as BODY and QUERYSTRING which
+    // apply to the entire set of params not only those by a specified name. Also
+    // is true if the input name is set to wildcard "*" meaning it should apply to
+    // all values. In each case there's no need to wrap if all rules are excluded.
+    const inputMatch = inputExclusions.find(
+      (e) => e.appliesToAllAssessRules() && !e.isNamed
     );
-    return;
-  }
-
-  const { pathname } = parseurl(req);
-  const urlExclusions = exclusions
-    .getUrlExclusions('assess')
-    .filter((e) => e.matchesUrl(pathname));
-  const inputExclusions = exclusions
-    .getInputExclusions('assess')
-    .filter((e) => e.matchesUrl(pathname) && e.appliesToInputType(type));
-
-  if (
-    sources.exclusionSourceEventFilter({
-      type,
-      urlExclusions,
-      inputExclusions
-    })
-  ) {
-    return;
-  }
-
-  const sourceParams = {
-    type,
-    object: obj[prop],
-    constructorOpt: agentEmitter.emit,
-    inputExclusions
-  };
-
-  const membrane = new SourceMembrane(config, sourceParams);
-  sources.track(type.toLowerCase(), obj, prop, membrane);
-};
-
-/**
- * Event filter function returns `false` if source event shouldn't be published.
- * If there is a URL Exclusion for all rules, then don't bother tracking inputs.
- * Otherwise, we have logic in TSReporter to skip reporting for URL Exclusions
- * for specific rules.
- * And some Input Exclusions apply broadly to the type. If they also apply to
- * all rules we can skip the source event outright.
- * @param {object} params
- * @param {string} params.type
- * @param {object[]} params.urlExclusions
- * @param {object[]} params.inputExclusions
- * @returns {boolean}
- */
-sources.exclusionSourceEventFilter = function({
-  type,
-  urlExclusions,
-  inputExclusions
-}) {
-  const urlMatch = urlExclusions.find((e) => e.appliesToAllAssessRules());
-  if (urlMatch) {
-    logExclusionMessage(type, urlMatch);
-    return true;
-  }
-  // `isNamed` is false for exclusion types such as BODY and QUERYSTRING which
-  // apply to the entire set of params not only those by a specified name. Also
-  // is true if the input name is set to wildcard "*" meaning it should apply to
-  // all values. In each case there's no need to wrap if all rules are excluded.
-  const inputMatch = inputExclusions.find(
-    (e) => e.appliesToAllAssessRules() && !e.isNamed
-  );
-  if (inputMatch) {
-    logExclusionMessage(type, inputMatch);
-    return true;
-  }
+    if (inputMatch) {
+      logExclusionMessage(type, inputMatch);
+      return true;
+    }
 
-  return false;
+    return false;
+  },
 };
-
-/**
- * Shared logging for when URL/Input exclusions thwart handling of sources.
- * @param {string} type the source type e.g. BODY, PARAMETER, HEADER
- */
-function logExclusionMessage(type, exclusion) {
-  const { name } = exclusion;
-  logger.debug(
-    'excluding %s inputs from all assess rules (%s)',
-    type.toLowerCase(),
-    name
-  );
-}

package/lib/core/express/index.js

@@ -376,14 +376,16 @@ class ExpressFramework {
   createMiddlewareWatchers() {
     this.useAfter(function ContrastRequestReady(req, res, next) {
       setFrameworkRequest(req, ExpressRequest);
+
       agentEmitter.emit(
         EVENTS.REQUEST_READY,
         req,
         res,
         INPUT_TYPES.QUERYSTRING,
       );
+
       next();
-    }, 'query');
+    }, 'expressInit');
 
     // ... multer(multi-part form uploads) ...........................
     this.useAfter(function ContrastMultiPartParsed(req, res, next) {
@@ -455,7 +457,7 @@ class ExpressFramework {
           const params = new Object(this.params);
           if (Object.keys(params).length) {
             agentEmitter.emit(
-              EVENTS.PARAM_PARSED,
+              EVENTS.PARAMS_PARSED,
               req,
               res,
               INPUT_TYPES.URL_PARAMETER,

package/lib/hooks/encoding.js

@@ -14,7 +14,7 @@ Copyright: 2022 Contrast Security, Inc
 */
 'use strict';
 
-const distringuish = require('@contrast/distringuish-prebuilt');
+const distringuish = require('@contrast/distringuish');
 const logger = require('../core/logger')('contrast:hooks');
 
 // some functions in the standard library allow users to specify a string
@@ -74,7 +74,7 @@ function hardPatchEncoding(obj, objName, methodName, strIndex) {
       // check each possible index (encoding can be a number of arguments and)
       // it depends on the function.
       // force to desired encoding by decoding to a buffer and then re-encoding.
-      if (distringuish.isExternal(args[strIndex])) {
+      if (typeof args[strIndex] === 'string' && distringuish.isExternal(args[strIndex])) {
         args[strIndex] = copy(args[strIndex]);
       }
     } catch (err) {

package/lib/list-installed.js

@@ -38,6 +38,7 @@ const execFile = util.promisify(require('child_process').execFile);
  * @param {*} logger
  * @returns {Promise<Result>}
  */
+// eslint-disable-next-line complexity
 module.exports = async function listInstalled(cwd, logger) {
   const execFileOpts = {
     cwd,

package/lib/protect/express/sources.js

@@ -28,7 +28,7 @@ class ExpressSources {
     agentEmitter.on(EVENTS.REQUEST_READY, ExpressSources.handleReady);
     agentEmitter.on(EVENTS.BODY_PARSED, ExpressSources.handleBody);
     agentEmitter.on(EVENTS.COOKIES_PARSED, ExpressSources.handleCookies);
-    agentEmitter.on(EVENTS.PARAM_PARSED, ExpressSources.handleParams);
+    agentEmitter.on(EVENTS.PARAMS_PARSED, ExpressSources.handleParams);
   }
 
   static handleReady(req, res, inputType) {

package/lib/reporter/speedracer/index.js

@@ -169,7 +169,7 @@ class Speedracer {
     this.logger.info('starting contrast-service');
     this.startTime = Date.now();
 
-    const speedracerPath = path.resolve(
+    let speedracerPath = path.resolve(
       __dirname,
       '..',
       '..',
@@ -179,6 +179,10 @@ class Speedracer {
       `contrast-service-${process.platform}-${process.arch}`
     );
 
+    if (process.platform === 'win32') {
+      speedracerPath = `${speedracerPath}.exe`;
+    }
+
     try {
       fs.statSync(speedracerPath);
     } catch (error) {

package/lib/tracker.js

@@ -12,188 +12,137 @@ Copyright: 2022 Contrast Security, Inc
   engineered, modified, repackaged, sold, redistributed or otherwise used in a
   way not consistent with the End User License Agreement.
 */
-/**
- * Tracker for objects we want to persist contrastProperties for.
- *
- * @module lib/tracker
- */
 'use strict';
 
 const logger = require('./core/logger')('contrast:tracker');
-const distringuish = require('@contrast/distringuish-prebuilt');
-
-const defaultContrastProperties = {
-  get tracked() {
-    return false;
-  },
-  set tracked(arg) {
-    logger.warn('tracked assigned to default contrastProperties');
-  },
-  get tagRanges() {
-    logger.warn('tagRanges referenced from default contrastProperties');
-    return [];
-  },
-  set tagRanges(arg) {
-    logger.warn('tagRanges assigned to default contrastProperties');
-  },
-  get event() {
-    logger.warn('event referenced from default contrastProperties');
-    return null;
-  },
-  set event(arg) {
-    logger.warn('event assigned to default contrastProperties');
-  }
-};
-
-// i'm not sure why this is a class. there are no methods, and externalized
-// strings don't have an instance of the class; they have an object with the
-// same property names.
-class ContrastProperties {
-  constructor() {
-    this.event = null;
-    this.tagRanges = [];
-    this.tracked = true;
-  }
-  // this is used to populate the object created by externalize.
-  static populate(obj) {
-    obj.event = null;
-    obj.tagRanges = [];
-    obj.tracked = true;
-  }
-}
+const distringuish = require('@contrast/distringuish');
 
 class Tracker {
   constructor() {
-    // map target --> ContrastProperties
+    /** @type {WeakMap<String, ContrastProperties>} */
     this.metadata = new WeakMap();
   }
 
+  /**
+   * Externalizes a given primitive string, attaching a ContrastProperties
+   * object. Returns null if the string is unable to be externalized.
+   * @param {string} str
+   * @returns {{ str: str | string, props: ContrastProperties} | null}
+   */
   trackString(str) {
-    if (str.length === 0) {
-      return str;
+    let props = distringuish.getProperties(str);
+    if (props) {
+      return { str, props };
     }
 
-    // XXX: this is the closest we have to a dedup.
-    // it may be kind of expensive. we need to consider whether or not
-    // this is worthwhile
-    if (this.getData(str)) {
-      return str;
+    str = distringuish.externalize(str);
+
+    if (typeof str === 'number') {
+      switch (str) {
+        case distringuish.ExternalizeErrorCode.ZERO_LENGTH_STRING:
+          logger.warn('Cannot externalize and track empty strings.'); // we should never see this error
+          return null;
+        case distringuish.ExternalizeErrorCode.INVALID_STRING_ENCODING:
+          logger.error('Unable to externalize non-two-byte strings.');
+          return null;
+        case distringuish.ExternalizeErrorCode.TO_LOCAL_FAILURE:
+          logger.error(
+            'An error occurred when creating a new external string.'
+          );
+          return null;
+        case distringuish.ExternalizeErrorCode.EXTERNALIZATION_FAILURE:
+          logger.error('The provided string was unable to be externalized.');
+          return null;
+        default:
+          logger.error('An unknown error occurred');
+          return null;
+      }
     }
 
-    const ext = distringuish.externalize(str);
-
-    // XXX this was causing SourceEvent not to get GC'd, for some reason
-    // const data = new ContrastProperties(ext, parent, sourceType, parentKey);
-    const data = new ContrastProperties();
-    const props = distringuish.getProperties(ext);
-    Object.assign(props, data);
+    props = distringuish.getProperties(str);
+    Object.assign(props, {
+      event: null,
+      tagRanges: [],
+      tracked: true,
+    });
 
-    return ext;
+    return { str, props };
   }
 
-  trackStringObject(value) {
-    if (value.length === 0) {
-      return value;
-    }
-
-    // no duplicates
-    if (this.metadata.has(value)) {
-      return value;
+  /**
+   * Tracks a given String object using the `metadata` WeakMap.
+   * @param {String} str
+   * @returns {str}
+   */
+  trackStringObject(str) {
+    if (!this.metadata.has(str)) {
+      this.metadata.set(str, {
+        event: null,
+        tagRanges: [],
+        tracked: true,
+      });
     }
 
-    this.metadata.set(value, new ContrastProperties());
-
-    return value;
+    return { str, props: this.metadata.get(str) };
   }
 
-
   /**
-   * Associate properties with a string. Returns null if str is not a string,
-   * is a zero-length string, or any internal error takes place.
-   *
-   * @param {*} str a value to track.
-   * @returns {Object|null} {str, props} or null on error.
+   * Return the properties associated with a given string. Returns null if the
+   * string has not previously been tracked.
+   * @param {string | String} str
+   * @return {ContrastProperties | null}
    */
-  track(str) {
+  getData(str) {
+    let prop;
     if (typeof str === 'string') {
-      // is the string already tracked?
-      let props = distringuish.getProperties(str);
-      if (props) {
-        return { str, props };
-      }
-
-      str = distringuish.externalize(str);
-      if (!str) {
-        return null;
-      }
-      props = distringuish.getProperties(str);
-      if (!props) {
-        return null;
-      }
-      ContrastProperties.populate(props);
-
-      return { str, props };
+      prop = distringuish.getProperties(str);
+    } else if (str instanceof String) {
+      prop = this.metadata.get(str);
     }
 
-    if (str instanceof String && str.length) {
-      // no duplicates
-      let props = this.metadata.get(str);
-      if (props) {
-        return { str, props };
-      }
-
-      props = new ContrastProperties();
-      this.metadata.set(str, props);
-
-      return { str, props };
-    }
-
-    return null;
+    return prop || null;
   }
 
   /**
-   * Return the properties associated with a value or null.
-   *
-   * @param {*} str any value
-   * @return {ContrastProperties|null}
+   * Associate properties with a string. Returns null if str is not a string,
+   * is a zero-length string, or any internal error takes place.
+   * @param {string | String} str
+   * @returns {{ str: str | string, props: ContrastProperties} | null}
    */
-  getData(str) {
-    if (typeof str === 'string') {
-      return distringuish.getProperties(str);
+  track(str) {
+    if (typeof str === 'string' && str.length > 0) {
+      return this.trackString(str);
     }
-    if (str instanceof String) {
-      return this.metadata.get(str) || null;
+
+    if (str instanceof String && str.length > 0) {
+      return this.trackStringObject(str);
     }
+
     return null;
   }
 
   /**
-   * Resets a string's tracking metadata to the default contrast properties.
-   * This will effectively untrack the associated string, but it will still be
-   * the externalized value.
-   * @param {object} trackingData A tracked string's metadata
+   * Resets a string's tracked data metadata to the default contrast properties.
+   * If the string is a primitive, we return a new, non-externalized copy of the
+   * string.
+   * If the string was an Object, we remove the properties from the `metadata`
+   * WeakMap.
+   * @param {string | String} str
+   * @returns {str | null}
    */
   untrack(str) {
     if (typeof str === 'string') {
-      let props = distringuish.getProperties(str);
-      if (!props) {
-        return null;
-      }
-      // return an untracked version of the string
-      Object.assign(props, {event: null, tagRanges: [], tracked: false})
       return distringuish.internalize(str);
     }
+
     if (str instanceof String) {
-      if (!this.metadata.delete(str)) {
-        return null;
-      }
+      this.metadata.delete(str);
       return str;
     }
+
     return null;
   }
 }
 
-const tracker = new Tracker();
-module.exports = tracker;
+module.exports = new Tracker();
 module.exports.Tracker = Tracker;
-module.exports.defaultContrastProperties = defaultContrastProperties;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agent",
-  "version": "4.24.2",
+  "version": "4.25.1",
   "description": "Node.js security instrumentation by Contrast Security",
   "keywords": [
     "security",
@@ -77,7 +77,7 @@
     "@babel/traverse": "^7.12.1",
     "@babel/types": "^7.12.1",
     "@contrast/agent-lib": "^4.3.0",
-    "@contrast/distringuish-prebuilt": "^3.2.0",
+    "@contrast/distringuish": "^4.0.0",
     "@contrast/flat": "^4.1.1",
     "@contrast/fn-inspect": "^3.1.0",
     "@contrast/protobuf-api": "^3.2.5",
@@ -193,7 +193,7 @@
     "test": "test"
   },
   "engines": {
-    "node": ">=12.13.0 <13 || >=14.15.0 <15 || >=16.9.1 <17",
+    "node": ">=12.13.0 <13 || >=14.15.0 <15 || >=16.9.1 <17 || >=18.7.0 <19",
     "npm": ">=6.13.7 <7 || >=7.11.0"
   },
   "bundleDependencies": [