@contrast/assess 1.39.0 → 1.40.0

package/lib/make-source-context.js

@@ -50,11 +50,15 @@ module.exports = function(core) {
         // 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: { uriPath, queries },
+        reqData: {
+          method: req.method,
+          uriPath,
+          queries,
+        },
       };
 
       // check whether sampling allows processing
-      ctx.sampleInfo = assess.sampler?.getSampleInfo?.(sourceData) ?? null;
+      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.
@@ -65,7 +69,6 @@ module.exports = function(core) {
       ctx.reqData.headers = { ...req.headers }; // copy to avoid storing tracked values
       ctx.reqData.ip = req.socket.remoteAddress;
       ctx.reqData.httpVersion = req.httpVersion;
-      ctx.reqData.method = req.method;
       if (ctx.reqData.headers['content-type'])
         ctx.reqData.contentType = StringPrototypeToLowerCase.call(ctx.reqData.headers['content-type']);
 

package/lib/sampler/common.js

@@ -0,0 +1,156 @@
+/*
+ * Copyright: 2024 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 SamplingStrategies = {
+  AssessTurnedOff: 1,
+  Probabilistic: 2,
+};
+
+class RouteAnalysisMonitor {
+  constructor(core) {
+    this._core = core;
+    // default behavior is to sample
+    this._defaultAnalysisInfo = { paused: false };
+    // cache keys come from discovered route `normalizedUrl`s, so size is controlled
+    this._normalCache = new Map();
+    this._ttl = core.config.assess.probabilistic_sampling.route_monitor.ttl_ms;
+  }
+
+  /**
+   * @param {object} reqData
+   * @param {string} reqData.uriPath
+   * @returns {AnalysisInfo}
+   */
+  getAnalysisInfo({ method, uriPath }) {
+    const normalizedUrl = this._core.routeCoverage.uriPathToNormalizedUrl(uriPath);
+    const now = Date.now();
+
+    if (normalizedUrl) {
+      const key = `${method}:${normalizedUrl}`;
+      let routeMeta = this._normalCache.get(key);
+
+      // not in cache, not paused
+      if (!routeMeta) {
+        routeMeta = {
+          pauseEnd: now + this._ttl,
+          normalizedUrl,
+        };
+        this._normalCache.set(key, routeMeta);
+
+        return { paused: false, ...routeMeta };
+      }
+
+      // unpause if pauseEnd expired
+      if (routeMeta.pauseEnd < now) {
+        // update so route lookup will be paused next time
+        routeMeta.pauseEnd = now + this._ttl;
+
+        return { paused: false, ...routeMeta };
+      }
+
+      // was in cache and still paused
+      return { paused: true, ...routeMeta };
+    } else {
+      // todo - handle "dynamic" routes
+    }
+
+    return this._defaultAnalysisInfo;
+  }
+}
+
+class BaseSampler {
+  constructor(strategy, opts) {
+    // save strategy and opts on instance so they can be checked before re-initializing
+    this.strategy = strategy;
+    this.opts = opts;
+  }
+}
+
+// Allows Assess to turn off at runtime e.g. disabled via TeamServer DTM
+class AssessTurnedOffSampler extends BaseSampler {
+  constructor() {
+    super(SamplingStrategies.AssessTurnedOff);
+    this._sampleInfo = Object.seal({ canSample: false });
+  }
+
+  getSampleInfo() {
+    return this._sampleInfo;
+  }
+}
+
+class ProbabilisticSampler extends BaseSampler {
+  constructor(opts) {
+    super(SamplingStrategies.Probabilistic, opts);
+  }
+
+  getSampleInfo(sourceInfo) {
+    const { base_probability } = this.opts;
+    const { reqData } = sourceInfo.store.assess;
+
+    // base caclulation
+    const rand = Math.random();
+    const canSample = rand < base_probability;
+    const sampleInfo = { canSample, base_probability, rand };
+
+    // check route monitoring before sampling
+    if (canSample) {
+      const routeInfo = this.routeMonitor?.getAnalysisInfo(reqData);
+
+      if (routeInfo) {
+        // don't sample if analysis is paused
+        routeInfo.paused && (sampleInfo.canSample = false);
+
+        // append any additional metadata to sample info
+        routeInfo.pauseEnd && (sampleInfo.pauseEnd = routeInfo.pauseEnd);
+        routeInfo.normalizedUrl && (sampleInfo.normalizedUrl = routeInfo.normalizedUrl);
+      }
+    }
+
+    return sampleInfo;
+  }
+}
+
+class SamplerBuilder {
+  constructor(core) {
+    this.builders = new Map([
+      //
+      [SamplingStrategies.AssessTurnedOff, () => new AssessTurnedOffSampler()],
+      //
+      [SamplingStrategies.Probabilistic, (opts) => {
+        const sampler = new ProbabilisticSampler(opts);
+
+        if (opts?.route_monitor?.enable)
+          sampler.routeMonitor = new RouteAnalysisMonitor(core);
+
+        return sampler;
+      }],
+    ]);
+  }
+
+  build(strategy, opts) {
+    return this.builders.get(strategy)(opts);
+  }
+}
+
+module.exports = {
+  RouteAnalysisMonitor,
+  BaseSampler,
+  AssessTurnedOffSampler,
+  ProbabilisticSampler,
+  SamplerBuilder,
+  SamplingStrategies,
+};

package/lib/sampler/common.test.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const { devNull } = require('node:os');
+const { expect } = require('chai');
+const { EventEmitter } = require('events');
+const mocks = require('@contrast/test/mocks');
+const { RouteAnalysisMonitor } = require('./common');
+const frameworkData = require('@contrast/test/data/framework-routing-data')();
+
+describe('assess sampler classes', function() {
+  describe('RouteAnalysisMonitor', function() {
+    it('getAnalysisInfo returns null when no discovery data was registered', function() {
+      const monitor = new RouteAnalysisMonitor(initMockCore());
+      [
+        ['/user/1', '/user/2', '/user/3', '/user/4'],
+        ['/user/1/cart', '/user/2/cart', '/user/3/cart', '/user/4/cart'],
+        ['/products/all', '/products/all'],
+        ['/products/1', '/products/2', '/products/3', '/products/4'],
+      ].forEach((uriPaths) => {
+        for (const uriPath of uriPaths) {
+          expect(monitor.getAnalysisInfo({ uriPath })).to.deep.equal({ paused: false });
+        }
+      });
+    });
+
+    for (const [framework, testData] of Object.entries(frameworkData)) {
+      describe(`${framework} framework route monitoring`, function() {
+        let core, monitor;
+
+        before(function() {
+          core = initMockCore();
+          core.config.setValue('assess.probabilistic_sampling.route_monitor.ttl_ms', 500, 'CONFIGURATION_FILE');
+          monitor = new RouteAnalysisMonitor(core);
+          testData.forEach((d) => {
+            core.routeCoverage._normalizedUrlMapper.handleDiscover(d.routeInfo);
+          });
+        });
+
+        testData.forEach(({ paths, routeInfo, skip, hasMapping }) => {
+          it(`${skip ? 'does not monitor' : 'monitors'} for normalizedUrl '${routeInfo.normalizedUrl}'`, async function() {
+            const groups = { paused: [], notPaused: [] };
+            let calls = 0;
+
+            // iterate at least twice if paths array has 1 element
+            [...paths, ...paths].forEach((uriPath, i) => {
+              const result = monitor.getAnalysisInfo({ uriPath, method: routeInfo.method });
+              calls++;
+              // update bucket
+              groups[result.paused ? 'paused' : 'notPaused'].push({ index: i, uriPath, ...result });
+            });
+
+            if (hasMapping !== false) {
+              // first call was unpaused
+              expect(groups.notPaused).to.have.lengthOf(1);
+              expect(groups.notPaused[0]).to.have.property('index', 0);
+              // all other calls were paused
+              expect(groups.paused).to.have.lengthOf(calls - 1);
+              for (const result of groups.paused) {
+                expect(result.index).to.be.greaterThan(0);
+              }
+            } else {
+              expect(groups.paused).to.have.lengthOf(0);
+            }
+          });
+        });
+      });
+    }
+  });
+});
+
+function initMockCore() {
+  const { CONTRAST_CONFIG_PATH } = process.env;
+  process.env.CONTRAST_CONFIG_PATH = devNull;
+
+  let core;
+
+  try {
+    core = {
+      // sampler needs this namespace to exist
+      assess: {},
+      // mocks
+      messages: new EventEmitter(),
+      logger: mocks.logger(),
+    };
+    // use actual config so we can get dynamic effective values with TS message
+    // updates (mock doesn't). we can also test new effective config mappings.
+    require('@contrast/config')(core);
+    require('@contrast/route-coverage')(core);
+    core.config.setValue('assess.enable', true, 'CONTRAST_UI');
+  } catch (err) {
+    process.env.CONTRAST_CONFIG_PATH = CONTRAST_CONFIG_PATH;
+
+    console.dir(err);
+    throw err;
+  }
+
+  // reset to orig value
+  process.env.CONTRAST_CONFIG_PATH = CONTRAST_CONFIG_PATH;
+
+  return core;
+}

package/lib/{sampler.js → sampler/index.js}

@@ -16,6 +16,8 @@
 'use strict';
 
 const { Event } = require('@contrast/common');
+const { ConfigSource } = require('@contrast/config');
+const { SamplerBuilder, SamplingStrategies } = require('./common');
 
 /**
  * @param {{
@@ -34,29 +36,40 @@ module.exports = function assess(core) {
     messages,
   } = core;
 
+  const samplerBuilder = new SamplerBuilder(core);
+
   /**
    * Initializes the Assess sampler only if there's a need, otherwise sets it to null.
    * Clients will call the instance methods optionally: assess.sampler?.getSampleInfo().
    * Determines sampler strategy and options based on effective config values.
    */
   function initSampler() {
+    const isProd = config.getEffectiveValue('server.environment') === 'PRODUCTION';
+    const enableAssess = config.getEffectiveValue('assess.enable');
     const baseProbability = config.getEffectiveValue('assess.probabilistic_sampling.base_probability');
+    const {
+      value: enableSampling,
+      source: samplingConfigSource
+    } = config._effectiveMap.get('assess.probabilistic_sampling.enable');
 
     let strategy;
     let opts;
 
-    if (!config.getEffectiveValue('assess.enable') || baseProbability === 0) {
-      // if Assess was disabled by TS use disabled sampler
-      strategy = 'disabled';
+    // determine strategy and options
+    if (!enableAssess || baseProbability === 0) {
+      // if Assess was disabled by TS turn assess off i.e. sample 0% of requests
+      strategy = SamplingStrategies.AssessTurnedOff;
     } else if (baseProbability < 1) {
+      // in PRODUCTION environments turn on sampling unless explicitly disabled
       if (
-        config.getEffectiveValue('assess.probabilistic_sampling.enable') ||
-        config.getEffectiveValue('server.environment') === 'PRODUCTION'
+        enableSampling ||
+        (isProd && samplingConfigSource === ConfigSource.DEFAULT_VALUE)
       ) {
         // strategy and opts can be more dynamic in the future
-        strategy = 'probabilistic';
+        strategy = SamplingStrategies.Probabilistic;
         opts = {
-          base_probability: baseProbability
+          base_probability: baseProbability,
+          route_monitor: config.assess.probabilistic_sampling.route_monitor,
         };
       }
     }
@@ -68,7 +81,7 @@ module.exports = function assess(core) {
         assess.sampler?.opts?.base_probability !== opts?.base_probability
       ) {
         logger.info({ strategy, opts }, 'updating assess sampler');
-        assess.sampler = SamplerFactory[strategy](opts);
+        assess.sampler = samplerBuilder.build(strategy, opts);
       }
     } else {
       if (assess.sampler) logger.info('assess sampling disabled');
@@ -79,58 +92,11 @@ module.exports = function assess(core) {
 
   // initialize a first time
   initSampler();
-  // and re-init again upon settings updates. we don't use the settings message argument, since all
-  // effective sampling configs will have have been updated by @contrast/config (it registers
-  // listeners first).
+
+  // and re-init again upon settings updates. we don't use the settings
+  // message argument, since all effective sampling configs will have
+  // been updated by @contrast/config (it registers listeners first).
   messages.on(Event.SERVER_SETTINGS_UPDATE, initSampler);
 
   return core.assess.sampler;
 };
-
-class BaseSampler {
-  constructor(strategy, opts) {
-    // save strategy and opts on instance so they can be checked before re-initializing
-    this.strategy = strategy;
-    this.opts = opts;
-  }
-}
-
-class DisabledSampler extends BaseSampler {
-  constructor() {
-    super('disabled');
-    this._sampleInfo = Object.seal({ canSample: false });
-  }
-
-  getSampleInfo() {
-    return this._sampleInfo;
-  }
-}
-
-class ProbabilisticSampler extends BaseSampler {
-  constructor(opts) {
-    super('probabilistic', opts);
-  }
-
-  getSampleInfo() {
-    const { base_probability } = this.opts;
-    const rand = Math.random();
-    const canSample = rand < base_probability;
-    return { canSample, base_probability, rand };
-  }
-}
-
-class SamplerFactory {
-  /**
-   * Used when Assess is disabled by TS; always returns value instructing not to sample
-   */
-  static disabled() {
-    return new DisabledSampler();
-  }
-
-  /**
-   * Each request has fixed chance e.g. 0.05.
-   */
-  static probabilistic(opts = {}) {
-    return new ProbabilisticSampler(opts);
-  }
-}

package/lib/{sampler.test.js → sampler/index.test.js}

@@ -6,26 +6,29 @@ const { Event } = require('@contrast/common');
 const mocks = require('@contrast/test/mocks');
 const { devNull } = require('node:os');
 
+const initSampler = require('.');
+const { SamplingStrategies: { AssessTurnedOff, Probabilistic } } = require('./common');
+
 const TRIALS = 1000;
 const ZSCORE = 3.891; // 99.99% confidence
 
 describe('assess sampler', function() {
   it('sampling is disabled by default and assess.sampler is null', function() {
     const core = initMockCore();
-    require('./sampler')(core);
+    initSampler(core);
     expect(core.assess.sampler).to.be.null;
   });
 
-  it('samples at default rate of 0.01', function() {
+  it('samples at default rate of 0.10', function() {
     const core = initMockCore();
     core.config.setValue('assess.enable', true, 'CONTRAST_UI');
     core.config.setValue('assess.probabilistic_sampling.enable', true, 'CONTRAST_UI');
     // initialize after configs are set
-    const sampler = require('./sampler')(core);
+    const sampler = initSampler(core);
 
     // verify configs set in before setup
-    expect(sampler).to.have.property('strategy', 'probabilistic');
-    expect(sampler.opts).to.have.property('base_probability', 0.01);
+    expect(sampler).to.have.property('strategy', Probabilistic);
+    expect(sampler.opts).to.have.property('base_probability', 0.10);
     expect(sampler).to.have.property('getSampleInfo').to.be.a('function');
     // test behavior
     testProbabilisticSampler(sampler);
@@ -36,10 +39,10 @@ describe('assess sampler', function() {
     core.config.setValue('assess.probabilistic_sampling.enable', true, 'CONTRAST_UI');
     core.config.setValue('assess.probabilistic_sampling.base_probability', 0.25, 'CONTRAST_UI');
     // initialize after configs are set
-    const sampler = require('./sampler')(core);
+    const sampler = initSampler(core);
 
     // verify configs
-    expect(sampler).to.have.property('strategy', 'probabilistic');
+    expect(sampler).to.have.property('strategy', Probabilistic);
     expect(sampler.opts).to.have.property('base_probability', 0.25);
     expect(sampler).to.have.property('getSampleInfo').to.be.a('function');
     // test behavior
@@ -51,12 +54,12 @@ describe('assess sampler', function() {
     core.config.setValue('assess.probabilistic_sampling.enable', true, 'CONTRAST_UI');
     core.config.setValue('assess.probabilistic_sampling.base_probability', 0.25, 'CONTRAST_UI');
     // initialize after configs are set
-    require('./sampler')(core);
+    initSampler(core);
     // don't destructure to just { sampler } since the value of assess.sampler changes on update.
     const { assess } = core;
 
     // verify configs
-    expect(assess.sampler).to.have.property('strategy', 'probabilistic');
+    expect(assess.sampler).to.have.property('strategy', Probabilistic);
     expect(assess.sampler.opts).to.have.property('base_probability', 0.25);
     expect(assess.sampler).to.have.property('getSampleInfo').to.be.a('function');
     // test behavior
@@ -81,12 +84,12 @@ describe('assess sampler', function() {
     expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
       // when initialized
       [
-        { strategy: 'probabilistic', opts: { base_probability: 0.25 } },
+        { strategy: Probabilistic, opts: { base_probability: 0.25, route_monitor: { enable: true, ttl_ms: 1800000 } } },
         'updating assess sampler'
       ],
       // update 1
       [
-        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        { strategy: Probabilistic, opts: { base_probability: 0.5, route_monitor: { enable: true, ttl_ms: 1800000 } } },
         'updating assess sampler'
       ]
     ]);
@@ -98,12 +101,12 @@ describe('assess sampler', function() {
     core.config.setValue('assess.probabilistic_sampling.enable', true, 'CONTRAST_UI');
     core.config.setValue('assess.probabilistic_sampling.base_probability', 0.50, 'CONTRAST_UI');
     // initializes after configs are set
-    require('./sampler')(core);
+    initSampler(core);
     // don't destructure to just { sampler } since the value of assess.sampler changes on update.
     const { assess } = core;
 
     // verify configs set in before setup
-    expect(assess.sampler).to.have.property('strategy', 'probabilistic');
+    expect(assess.sampler).to.have.property('strategy', Probabilistic);
     expect(assess.sampler.opts).to.have.property('base_probability', 0.50);
     expect(assess.sampler).to.have.property('getSampleInfo').to.be.a('function');
     // test behavior
@@ -115,7 +118,7 @@ describe('assess sampler', function() {
     });
 
     // verify updated sampling strategy
-    expect(assess.sampler.strategy).to.equal('disabled');
+    expect(assess.sampler.strategy).to.equal(AssessTurnedOff);
     // test behavior
     testDisabledSampler(assess.sampler);
 
@@ -123,12 +126,12 @@ describe('assess sampler', function() {
     expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
       // when initialized
       [
-        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        { strategy: Probabilistic, opts: { base_probability: 0.5, route_monitor: { enable: true, ttl_ms: 1800000 } } },
         'updating assess sampler'
       ],
       // update 1
       [
-        { strategy: 'disabled', opts: undefined },
+        { strategy: AssessTurnedOff, opts: undefined },
         'updating assess sampler'
       ]
     ]);
@@ -142,11 +145,13 @@ describe('assess sampler', function() {
     process.env.CONTRAST_CONFIG_PATH = cfgPath;
 
     core.config.setValue('assess.enable', true, 'CONTRAST_UI');
-    core.config.setValue('assess.probabilistic_sampling.enable', false, 'DEFAULT_VALUE');
+    // core.config.setValue('assess.probabilistic_sampling.enable', true, 'DEFAULT_VALUE');
     core.config.setValue('assess.probabilistic_sampling.base_probability', 0.50, 'CONTRAST_UI');
+
     // initializes after configs are set
-    require('./sampler')(core);
-    // don't destructure to just { sampler } since the value of assess.sampler changes on update.
+    initSampler(core);
+
+    // don't destructure to just { sampler } since the value of assess.sampler changes on update
     const { assess } = core;
 
     // disabled by config
@@ -176,7 +181,7 @@ describe('assess sampler', function() {
     });
 
     // verify updated sampling strategy
-    expect(assess.sampler.strategy).to.equal('disabled');
+    expect(assess.sampler.strategy).to.equal(AssessTurnedOff);
     // test behavior
     testDisabledSampler(assess.sampler);
 
@@ -200,19 +205,19 @@ describe('assess sampler', function() {
     expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
       // update 1: env=PRODUCTION enables sampling
       [
-        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        { strategy: Probabilistic, opts: { base_probability: 0.5, route_monitor: { enable: true, ttl_ms: 1800000 } } },
         'updating assess sampler'
       ],
       // update 2: env = DEVELOPMENT disables sampling
       ['assess sampling disabled'],
       // update 3: assess.enable=false sets disabled sampling strategy
       [
-        { strategy: 'disabled', opts: undefined },
+        { strategy: AssessTurnedOff, opts: undefined },
         'updating assess sampler'
       ],
       // update 5: assess.enable=true and request_frequency=50 re-enables assess and new sampling probability
       [
-        { strategy: 'probabilistic', opts: { base_probability: 0.02 } },
+        { strategy: Probabilistic, opts: { base_probability: 0.02, route_monitor: { enable: true, ttl_ms: 1800000 } } },
         'updating assess sampler'
       ]
     ]);
@@ -236,6 +241,8 @@ function initMockCore() {
     // use actual config so we can get dynamic effective values with TS message
     // updates (mock doesn't). we can also test new effective config mappings.
     require('@contrast/config')(core);
+    require('@contrast/route-coverage')(core);
+
     core.config.setValue('assess.enable', true, 'CONTRAST_UI');
   } catch (err) {
     process.env.CONTRAST_CONFIG_PATH = CONTRAST_CONFIG_PATH;
@@ -274,15 +281,20 @@ function getStats(p) {
 
 function testProbabilisticSampler(sampler) {
   const { opts } = sampler;
+  const store = {
+    assess: {
+      reqData: { uriPath: '/foo' }
+    }
+  };
 
   // run trials and count how many times sampler says okay to analyze
   let observedSampleCount = 0;
   for (let n = 0; n < TRIALS; n++) {
-    const info = sampler.getSampleInfo();
+    const info = sampler.getSampleInfo({ store });
     if (info.canSample) observedSampleCount++;
   }
 
-  const stats = getStats(opts.base_probability, observedSampleCount);
+  const stats = getStats(opts.base_probability);
   const { confidenceInterval: [low, high] } = stats;
 
   // for debugging/visibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Contrast service providing framework-agnostic Assess support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -18,15 +18,16 @@
   },
   "dependencies": {
     "@contrast/common": "1.26.0",
-    "@contrast/config": "1.35.0",
-    "@contrast/core": "1.40.0",
-    "@contrast/dep-hooks": "1.8.0",
+    "@contrast/config": "1.36.0",
+    "@contrast/core": "1.41.0",
+    "@contrast/dep-hooks": "1.9.0",
     "@contrast/distringuish": "^5.1.0",
-    "@contrast/instrumentation": "1.18.0",
-    "@contrast/logger": "1.13.0",
-    "@contrast/patcher": "1.12.0",
-    "@contrast/rewriter": "1.16.0",
-    "@contrast/scopes": "1.9.0",
+    "@contrast/instrumentation": "1.19.0",
+    "@contrast/logger": "1.14.0",
+    "@contrast/patcher": "1.13.0",
+    "@contrast/rewriter": "1.17.0",
+    "@contrast/route-coverage": "1.30.0",
+    "@contrast/scopes": "1.10.0",
     "semver": "^7.6.0"
   }
 }