@contrast/assess 1.35.0 → 1.36.0

package/lib/sampler.js

@@ -0,0 +1,136 @@
+/*
+ * 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 { Event } = require('@contrast/common');
+
+/**
+ * @param {{
+ *  assess: import('.').Assess,
+ *  config: import('@contrast/config').Config,
+ *  logger: import('@contrast/logger').Logger,
+ *  messages: import('@contrast/common').Messages,
+ * }} core
+ * @returns {import('@contrast/common').Installable}
+ */
+module.exports = function assess(core) {
+  const {
+    assess,
+    config,
+    logger,
+    messages,
+  } = 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 baseProbability = config.getEffectiveValue('assess.probabilistic_sampling.base_probability');
+
+    let strategy;
+    let opts;
+
+    if (!config.getEffectiveValue('assess.enable') || baseProbability === 0) {
+      // if Assess was disabled by TS use disabled sampler
+      strategy = 'disabled';
+    } else if (baseProbability < 1) {
+      if (
+        config.getEffectiveValue('assess.probabilistic_sampling.enable') ||
+        config.getEffectiveValue('server.environment') === 'PRODUCTION'
+      ) {
+        // strategy and opts can be more dynamic in the future
+        strategy = 'probabilistic';
+        opts = {
+          base_probability: baseProbability
+        };
+      }
+    }
+
+    if (strategy) {
+      // only re-init if the strategy and options are different than current sampler
+      if (
+        assess.sampler?.strategy !== strategy ||
+        assess.sampler?.opts?.base_probability !== opts?.base_probability
+      ) {
+        logger.info({ strategy, opts }, 'updating assess sampler');
+        assess.sampler = SamplerFactory[strategy](opts);
+      }
+    } else {
+      // disable sampling by setting sampler to null
+      assess.sampler = null;
+      logger.info('assess sampling disabled');
+    }
+  }
+
+  // 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).
+  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

@@ -0,0 +1,296 @@
+'use strict';
+
+const { EventEmitter } = require('events');
+const { expect } = require('chai');
+const { Event } = require('@contrast/common');
+const mocks = require('@contrast/test/mocks');
+
+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);
+    expect(core.assess.sampler).to.be.null;
+  });
+
+  it('samples at default rate of 0.01', 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);
+
+    // 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('getSampleInfo').to.be.a('function');
+    // test behavior
+    testProbabilisticSampler(sampler);
+  });
+
+  it('samples at p=base_probability', function() {
+    const core = initMockCore();
+    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);
+
+    // verify configs
+    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
+    testProbabilisticSampler(sampler);
+  });
+
+  it('probability is dynamic and set by TS server setting: assess.sampling.request_frequency', function() {
+    const core = initMockCore();
+    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);
+    // 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.opts).to.have.property('base_probability', 0.25);
+    expect(assess.sampler).to.have.property('getSampleInfo').to.be.a('function');
+    // test behavior
+    testProbabilisticSampler(assess.sampler);
+
+    // update
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      assess: {
+        sampling: {
+          enable: true,
+          request_frequency: 2, // 1 / 2 = 0.50 base_probability
+        }
+      }
+    });
+
+    // verify sampler was updated
+    expect(assess.sampler.opts.base_probability).to.equal(0.50);
+    // test behavior
+    testProbabilisticSampler(assess.sampler);
+
+    // test logging throughout init/updates
+    expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
+      // when initialized
+      [
+        { strategy: 'probabilistic', opts: { base_probability: 0.25 } },
+        'updating assess sampler'
+      ],
+      // update 1
+      [
+        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        'updating assess sampler'
+      ]
+    ]);
+  });
+
+  it('sampler always returns `canSample: false` if TS `assess.enable` setting is false', function() {
+    const core = initMockCore();
+    core.config.setValue('assess.enable', true, 'CONTRAST_UI');
+    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);
+    // 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.opts).to.have.property('base_probability', 0.50);
+    expect(assess.sampler).to.have.property('getSampleInfo').to.be.a('function');
+    // test behavior
+    testProbabilisticSampler(assess.sampler);
+
+    // runtime update that says to disable assess
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      assess: { enable: false }
+    });
+
+    // verify updated sampling strategy
+    expect(assess.sampler.strategy).to.equal('disabled');
+    // test behavior
+    testDisabledSampler(assess.sampler);
+
+    // test logging throughout init/updates
+    expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
+      // when initialized
+      [
+        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        'updating assess sampler'
+      ],
+      // update 1
+      [
+        { strategy: 'disabled', opts: undefined },
+        'updating assess sampler'
+      ]
+    ]);
+  });
+
+  it('sampler behavior adjusts to series of TS updates', function() {
+    // setup
+    const core = initMockCore();
+    core.config.setValue('assess.enable', true, 'CONTRAST_UI');
+    core.config.setValue('assess.probabilistic_sampling.enable', false, '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.
+    const { assess } = core;
+
+    // disabled by config
+    expect(assess.sampler).to.be.null;
+
+    // set to PRODUCTION to enable sampling
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      environment: 'PRODUCTION',
+    });
+
+    // verify sampler was updated
+    expect(assess.sampler.opts.base_probability).to.equal(0.50);
+    // test behavior
+    testProbabilisticSampler(assess.sampler);
+
+    // disable sampling by setting to DEVELOPMENT
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      environment: 'DEVELOPMENT',
+    });
+
+    // since assess.probabilistic_sampling is off and env is no longer PRODUCTION
+    expect(assess.sampler).to.be.null;
+
+    // disable Assess
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      assess: { enable: false },
+    });
+
+    // verify updated sampling strategy
+    expect(assess.sampler.strategy).to.equal('disabled');
+    // test behavior
+    testDisabledSampler(assess.sampler);
+
+    // re-enable Assess and set new probability via request_frequency
+    core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+      assess: {
+        enable: true,
+        sampling: {
+          enable: true,
+          request_frequency: 50, //
+        }
+      },
+    });
+
+    // verify sampler was updated
+    expect(assess.sampler.opts.base_probability).to.equal(1 / 50);
+    // test behavior
+    testProbabilisticSampler(assess.sampler);
+
+    // test logging throughout init/updates
+    expect(core.logger.info.getCalls().map(c => c.args)).to.deep.equal([
+      // when initialized
+      ['assess sampling disabled'],
+      // update 1: env=PRODUCTION enables sampling
+      [
+        { strategy: 'probabilistic', opts: { base_probability: 0.5 } },
+        '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 },
+        '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 } },
+        'updating assess sampler'
+      ]
+    ]);
+  });
+});
+
+function initMockCore() {
+  const { CONTRAST_CONFIG_PATH } = process.env;
+  let core;
+
+  try {
+    // ensure default config if devs use this
+    process.env.CONTRAST_CONFIG_PATH = '';
+    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);
+    core.config.setValue('assess.enable', true, 'CONTRAST_UI');
+  } catch (err) {
+    console.dir(err);
+    throw err;
+  }
+
+  // reset to orig value
+  if (CONTRAST_CONFIG_PATH) process.env.CONTRAST_CONFIG_PATH = CONTRAST_CONFIG_PATH;
+
+  return core;
+}
+
+// https://en.wikipedia.org/wiki/Binomial_distribution
+function getStats(p) {
+  const mean = TRIALS * p;
+  const variance = mean * (1 - p);
+  const standardDev = Math.sqrt(variance);
+  const marginOfError = ZSCORE * standardDev;
+  const confidenceInterval = [
+    Math.max(0, mean - marginOfError),
+    mean + marginOfError
+  ];
+
+  return {
+    p,
+    mean,
+    variance,
+    standardDev,
+    confidenceInterval,
+    trials: TRIALS,
+    zscore: ZSCORE,
+  };
+}
+
+function testProbabilisticSampler(sampler) {
+  const { opts } = sampler;
+
+  // 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();
+    if (info.canSample) observedSampleCount++;
+  }
+
+  const stats = getStats(opts.base_probability, observedSampleCount);
+  const { confidenceInterval: [low, high] } = stats;
+
+  // for debugging/visibility
+  // console.log({ observedSampleCount, ...stats })
+  expect(observedSampleCount).to.be.greaterThan(low).and.lessThan(high);
+}
+
+function testDisabledSampler(sampler) {
+  // 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();
+    if (info.canSample) observedSampleCount++;
+  }
+  expect(observedSampleCount).to.equal(0);
+}

package/lib/session-configuration/install/express-session.js

@@ -14,7 +14,7 @@
  */
 'use strict';
 
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { primordials: { StringPrototypeToLowerCase } } = require('@contrast/common');
 const { patchType } = require('../common');
 
 /**

package/lib/session-configuration/install/fastify-cookie.js

@@ -14,7 +14,7 @@
  */
 'use strict';
 
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { primordials: { StringPrototypeToLowerCase } } = require('@contrast/common');
 const { patchType } = require('../common');
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "Contrast service providing framework-agnostic Assess support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -17,16 +17,16 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.25.0",
-    "@contrast/config": "1.33.0",
-    "@contrast/core": "1.37.0",
-    "@contrast/dep-hooks": "1.5.0",
+    "@contrast/common": "1.26.0",
+    "@contrast/config": "1.34.0",
+    "@contrast/core": "1.38.0",
+    "@contrast/dep-hooks": "1.6.0",
     "@contrast/distringuish": "^5.1.0",
-    "@contrast/instrumentation": "1.15.0",
-    "@contrast/logger": "1.10.0",
-    "@contrast/patcher": "1.9.0",
-    "@contrast/rewriter": "1.13.0",
-    "@contrast/scopes": "1.6.0",
+    "@contrast/instrumentation": "1.16.0",
+    "@contrast/logger": "1.11.0",
+    "@contrast/patcher": "1.10.0",
+    "@contrast/rewriter": "1.14.0",
+    "@contrast/scopes": "1.7.0",
     "semver": "^7.6.0"
   }
 }