@contrast/assess 1.39.0 → 1.41.0

package/lib/get-source-context.js

@@ -32,23 +32,44 @@ module.exports = function(core) {
   } = core;
 
   /**
+   * getSourceContext must be used by all instrumentation to make sure that the
+   * - assess store is available
+   * - assess is enabled for this request
+   * - instrumentation is not locked
+   *
+   * Any code that does not use this function and directly accesses the assess
+   * source context will recurse until the stack is blown if the following
+   * checks are not correctly made.
+   *
    * @param {import('./constants.js').InstrumentationType} type
    * @returns {import('@contrast/assess').SourceContext|null} the assess store
    */
   return core.assess.getSourceContext = function getSourceContext(type, ...rest) {
     const ctx = sources.getStore()?.assess;
-    // <unsafe>
-    // This method is expected to be called by all Assess instrumentation components prior to doing work.
-    // Until we check policy, and whether instrumentation is locked, any instrumentation that is called before
-    // the </unsafe> section below will result in infinite recursion.
-    //
-    // E.g. Uncommenting any line below will cause a stack overflow:
-    // 'asdf'.concat()
-    // console.log() // even though this is deadzoned, we haven't checked whether instrumentation is locked yet
-    //
-    // policy will not exist if assess is altogether disabled for the active request e.g. url exclusion
-    if (!ctx?.policy || instrumentation.isLocked()) return null;
-    // </unsafe> but still be careful
+
+    // the following logging used to be done by the caller, but has been moved
+    // here as opposed to overloading `ctx.policy` with a special value so the
+    // caller could determine whether no source context was available or the
+    // request is being intentionally excluded. A negative of this is that the
+    // function name is not available to be included in the log.
+    if (!ctx) {
+      if (type === InstrumentationType.SOURCE) {
+        // because this is a real error, and we don't have the function name
+        // that the caller previously logged, we generate a stack trace to
+        // capture that information.
+        const err = new Error('No source context found');
+        core.logger.warn({ err }, 'assess running outside of request scope');
+      }
+      return null;
+    }
+    // there is a context, but if policy is null then assess is intentionally
+    // disabled (i.e., url exclusion or the request is not sampled).
+    if (!ctx.policy) {
+      core.logger.trace('Assess intentionally disabled for this request');
+      return null;
+    } else if (instrumentation.isLocked()) {
+      return null;
+    }
 
     switch (type) {
       case InstrumentationType.PROPAGATOR: {

package/lib/get-source-context.test.js

@@ -3,6 +3,7 @@
 const { expect } = require('chai');
 const { Event } = require('@contrast/common');
 const { initAssessFixture } = require('@contrast/test/fixtures');
+const sinon = require('sinon');
 const {
   InstrumentationType: { SOURCE, PROPAGATOR, RULE }
 } = require('./constants');
@@ -36,8 +37,35 @@ describe('assess getSourceContext', function () {
     expect(assessStore.policy.enabledRules).to.have.length.greaterThan(5);
   }
 
-  it('returns `null` when not in request scope', function() {
+  it('return null when not in request scope', function() {
     expect(core.assess.getSourceContext()).to.be.null;
+    expect(core.logger.warn.callCount).equal(0);
+  });
+
+  it('return null and log when getSourceContext(SOURCE) not in request scope', function() {
+    expect(core.assess.getSourceContext(SOURCE)).to.be.null;
+    expect(core.logger.warn.callCount).equal(1);
+    expect(core.logger.warn.args[0][1]).to.include('outside of request scope');
+  });
+
+  it('return null and log when intentionally disabled (policy === null)', function() {
+    simulateRequestScope(() => {
+      core.scopes.sources.getStore().assess.policy = null;
+      expect(core.assess.getSourceContext()).null;
+      // lots of code writes trace logs
+      const last = core.logger.trace.lastCall;
+      expect(last.args[0]).to.include('Assess intentionally disabled');
+    });
+  });
+
+  it('return null and do not log when instrumentation is locked', function() {
+    simulateRequestScope(() => {
+      core.scopes.instrumentation.isLocked = sinon.stub().returns(true);
+      expect(core.assess.getSourceContext()).null;
+      if (core.logger.trace.called) {
+        expect(core.logger.trace.lastCall.args[0]).not.include('Assess intentionally disabled');
+      }
+    });
   });
 
   describe('getSourceContext()', function() {
@@ -48,7 +76,7 @@ describe('assess getSourceContext', function () {
     });
   });
 
-  describe('.getSourceContext(SOURCE?)', function() {
+  describe('.getSourceContext(SOURCE)', function() {
     it('returns assess store when max source event threshold is not met', function() {
       simulateRequestScope(() => {
         execStoreAssertions(core.assess.getSourceContext(SOURCE));
@@ -64,10 +92,10 @@ describe('assess getSourceContext', function () {
     });
   });
 
-  describe('.getSourceContext(PROPAGATOR?)', function() {
+  describe('.getSourceContext(PROPAGATOR)', function() {
     it('returns assess store when max propagation event threshold is not met', function() {
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext(SOURCE));
+        execStoreAssertions(core.assess.getSourceContext(PROPAGATOR));
       });
     });
 
@@ -80,7 +108,7 @@ describe('assess getSourceContext', function () {
     });
   });
 
-  describe('.getSourceContext(SINK?, ruleId?)', function() {
+  describe('.getSourceContext(RULE, ruleId?)', function() {
     it('returns assess store when ruleId is not passed', function() {
       simulateRequestScope(() => {
         execStoreAssertions(core.assess.getSourceContext(RULE));

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);
-  }
-}