@contrast/assess 1.40.0 → 1.42.0

package/lib/dataflow/sources/install/restify/router.js

@@ -16,7 +16,6 @@
 'use strict';
 
 const { InputType: { URL_PARAMETER } } = require('@contrast/common');
-const { InstrumentationType: { SOURCE } } = require('../../../../constants');
 const { patchType } = require('../../common');
 
 module.exports = function init(core) {
@@ -33,16 +32,15 @@ module.exports = function init(core) {
   return core.assess.dataflow.sources.restifyInstrumentation.router = {
     install() {
       depHooks.resolve(
-        { name: 'restify', file: 'lib/router.js', version: '>=8' },
+        { name: 'restify', file: 'lib/router.js', version: '>=8 <12' },
         (Router) => {
           patcher.patch(Router.prototype, 'lookup', {
             name: 'restify.Router.prototype.lookup',
             patchType,
             post({ args: [req], hooked, orig, name, funcKey }) {
-              const sourceContext = getSourceContext(SOURCE);
+              const sourceContext = getSourceContext();
 
               if (!sourceContext) {
-                logger.error({ funcKey }, 'unable to handle source. Missing `sourceContext`');
                 return;
               }
 

package/lib/dataflow/sources/install/restify/router.test.js

@@ -17,7 +17,7 @@ describe('assess dataflow sources restify router', function () {
     req = {};
 
     core.depHooks.resolve
-      .withArgs({ name: 'restify', file: 'lib/router.js', version: '>=8' })
+      .withArgs({ name: 'restify', file: 'lib/router.js', version: '>=8 <12' })
       .yields(Router);
 
     init(core).install();
@@ -27,11 +27,9 @@ describe('assess dataflow sources restify router', function () {
     simulateRequestScope(() => {
       Router.prototype.lookup(req);
 
-      expect(handle).not.to.have.been.called;
-      expect(core.logger.error).to.have.been.calledWith(
-        { funcKey: 'assess-dataflow-source:restify.Router.prototype.lookup' },
-        'unable to handle source. Missing `sourceContext`'
-      );
+      expect(handle).not.called;
+      expect(core.logger.trace.callCount).greaterThan(0);
+      expect(core.logger.trace.lastCall.args[0]).includes('Assess intentionally disabled');
     }, { assess: { policy: null } });
   });
 

package/lib/get-source-context.js

@@ -12,16 +12,17 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-
+// @ts-check
 'use strict';
 
-const { InstrumentationType } = require('./constants');
+/** @typedef {import('@contrast/assess').SourceContext} SourceContext */
 
 /**
  * @param {{
- *  assess: import('@contrast/assess').Assess,
- *  config: import('@contrast/config').Config,
- *  scopes: import('@contrast/scopes').Scopes,
+ *  readonly config: import('@contrast/config').Config;
+ *  readonly logger: import('@contrast/logger').Logger;
+ *  readonly scopes: import('@contrast/scopes').Scopes;
+ *  assess: import('@contrast/assess').Assess;
  * }} core
  */
 module.exports = function(core) {
@@ -32,42 +33,81 @@ module.exports = function(core) {
   } = core;
 
   /**
-   * @param {import('./constants.js').InstrumentationType} type
-   * @returns {import('@contrast/assess').SourceContext|null} the assess store
+   * Used by all propagator 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.
+   * @returns {SourceContext | null}
    */
-  return core.assess.getSourceContext = function getSourceContext(type, ...rest) {
+  core.assess.getPropagatorContext = function getPropagatorContext() {
+    if (instrumentation.isLocked()) return null;
+
+    // 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.
+    const ctx = sources.getStore()?.assess;
+    if (!ctx) 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;
+    }
+
+    if (ctx.propagationEventsCount > config.assess.max_propagation_events) return null;
+
+    return ctx;
+  };
+
+  /**
+   * @param {import('@contrast/common').Rule} ruleId
+   * @returns {SourceContext | null}
+   */
+  core.assess.getSinkContext = function getSinkContext(ruleId) {
+    if (instrumentation.isLocked()) return null;
+
     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
-
-    switch (type) {
-      case InstrumentationType.PROPAGATOR: {
-        if (ctx.propagationEventsCount > config.assess.max_propagation_events) return null;
-        break;
-      }
-      case InstrumentationType.SOURCE: {
-        if (ctx.sourceEventsCount > config.assess.max_context_source_events) return null;
-        break;
-      }
-
-      case InstrumentationType.RULE: {
-        const [ruleId] = rest;
-        if (!ruleId) break;
-        if (!ctx.policy?.enabledRules?.has?.(ruleId) || ruleScopes.isLocked(ruleId)) return null;
-        break;
-      }
+    if (!ctx) return null;
+
+    if (!ctx.policy) {
+      core.logger.trace('Assess intentionally disabled for this request');
+      return null;
     }
 
+    if (ruleId && !ctx.policy?.enabledRules?.has?.(ruleId) || ruleScopes.isLocked(ruleId)) return null;
+
     return ctx;
   };
+
+  /** @returns {SourceContext | null} */
+  core.assess.getSourceContext = function getSourceContext() {
+    if (instrumentation.isLocked()) return null;
+
+    const ctx = sources.getStore()?.assess;
+    if (!ctx) {
+      // 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;
+    }
+
+    if (!ctx.policy) {
+      core.logger.trace('Assess intentionally disabled for this request');
+      return null;
+    }
+
+    if (ctx.sourceEventsCount > config.assess.max_context_source_events) return null;
+
+    return ctx;
+  };
+
 };

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

@@ -3,9 +3,29 @@
 const { expect } = require('chai');
 const { Event } = require('@contrast/common');
 const { initAssessFixture } = require('@contrast/test/fixtures');
-const {
-  InstrumentationType: { SOURCE, PROPAGATOR, RULE }
-} = require('./constants');
+const sinon = require('sinon');
+
+function execStoreAssertions(assessStore) {
+  expect(assessStore).to.be.an('object').and.deep.include({
+    reqData: {
+      ip: '127.0.0.1',
+      httpVersion: '1.1',
+      method: 'get',
+      headers: {
+        'content-type': 'text/html',
+        language: 'en',
+        referer: 'http://fake.url.foo',
+      },
+      uriPath: '/index',
+      queries: '_id=123',
+      contentType: 'text/html'
+    },
+    responseData: {},
+    sourceEventsCount: 0,
+    propagationEventsCount: 0,
+  });
+  expect(assessStore.policy.enabledRules).to.have.length.greaterThan(5);
+}
 
 describe('assess getSourceContext', function () {
   let core, simulateRequestScope;
@@ -14,86 +34,74 @@ describe('assess getSourceContext', function () {
     ({ core, simulateRequestScope } = initAssessFixture());
   });
 
-  function execStoreAssertions(assessStore) {
-    expect(assessStore).to.be.an('object').and.deep.include({
-      reqData: {
-        ip: '127.0.0.1',
-        httpVersion: '1.1',
-        method: 'get',
-        headers: {
-          'content-type': 'text/html',
-          language: 'en',
-          referer: 'http://fake.url.foo',
-        },
-        uriPath: '/index',
-        queries: '_id=123',
-        contentType: 'text/html'
-      },
-      responseData: {},
-      sourceEventsCount: 0,
-      propagationEventsCount: 0,
+  describe('getPropagatorContext()', function() {
+    it('returns null when instrumentation is locked', function () {
+      sinon.stub(core.scopes.instrumentation, 'isLocked').returns(true);
+
+      simulateRequestScope(() => {
+        expect(core.assess.getPropagatorContext()).to.be.null;
+      });
     });
-    expect(assessStore.policy.enabledRules).to.have.length.greaterThan(5);
-  }
 
-  it('returns `null` when not in request scope', function() {
-    expect(core.assess.getSourceContext()).to.be.null;
-  });
+    it('returns null when not in request scope', function() {
+      expect(core.assess.getPropagatorContext()).to.be.null;
+    });
 
-  describe('getSourceContext()', function() {
-    it('returns assess store when in request scope', function() {
+    it('returns null when assess is disabled by policy', function() {
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext());
-      });
+        expect(core.assess.getPropagatorContext()).to.be.null;
+        expect(core.logger.trace).to.have.been.calledWith('Assess intentionally disabled for this request');
+      }, { assess: { policy: undefined } });
     });
-  });
 
-  describe('.getSourceContext(SOURCE?)', function() {
-    it('returns assess store when max source event threshold is not met', function() {
+    it('returns assess store when max propagation event threshold is not met', function() {
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext(SOURCE));
+        execStoreAssertions(core.assess.getPropagatorContext());
       });
     });
 
-    it('returns `null` when max source event threshold is exceeded', function() {
+    it('returns null when max propagation event threshold is exceeded', function() {
+      core.config.setValue('assess.max_propagation_events', 10);
+
       simulateRequestScope(() => {
-        core.config.setValue('assess.max_context_source_events', 10);
-        core.scopes.sources.getStore().assess.sourceEventsCount = 11;
-        expect(core.assess.getSourceContext(SOURCE)).to.be.null;
-      });
+        expect(core.assess.getPropagatorContext()).to.be.null;
+      }, { assess: { propagationEventsCount: 11 } });
     });
   });
 
-  describe('.getSourceContext(PROPAGATOR?)', function() {
-    it('returns assess store when max propagation event threshold is not met', function() {
+  describe('getSinkContext()', function() {
+    it('returns null when instrumentation is locked', function () {
+      sinon.stub(core.scopes.instrumentation, 'isLocked').returns(true);
+
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext(SOURCE));
+        expect(core.assess.getSinkContext()).to.be.null;
       });
     });
 
-    it('returns `null` when max propagation event threshold is exceeded', function() {
+    it('returns null when not in request scope', function() {
+      expect(core.assess.getSinkContext()).to.be.null;
+    });
+
+    it('returns null when assess is disabled by policy', function() {
       simulateRequestScope(() => {
-        core.config.setValue('assess.max_propagation_events', 10);
-        core.scopes.sources.getStore().assess.propagationEventsCount = 11;
-        expect(core.assess.getSourceContext(PROPAGATOR)).to.be.null;
-      });
+        expect(core.assess.getSinkContext()).to.be.null;
+        expect(core.logger.trace).to.have.been.calledWith('Assess intentionally disabled for this request');
+      }, { assess: { policy: undefined } });
     });
-  });
 
-  describe('.getSourceContext(SINK?, ruleId?)', function() {
     it('returns assess store when ruleId is not passed', function() {
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext(RULE));
+        execStoreAssertions(core.assess.getSourceContext());
       });
     });
 
     it('returns assess store when ruleId provided is enabled in the policy', function() {
       simulateRequestScope(() => {
-        execStoreAssertions(core.assess.getSourceContext(RULE, 'reflected-xss'));
+        execStoreAssertions(core.assess.getSinkContext('reflected-xss'));
       });
     });
 
-    it('returns `null` when ruleId provided is not enabled in the policy', function() {
+    it('returns null when ruleId provided is not enabled in the policy', function() {
       core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
         assess: {
           ['reflected-xss']: { enable: false },
@@ -101,8 +109,53 @@ describe('assess getSourceContext', function () {
       });
 
       simulateRequestScope(() => {
-        expect(core.assess.getSourceContext(RULE, 'reflected-xss')).to.be.null;
+        expect(core.assess.getSinkContext('reflected-xss')).to.be.null;
       });
     });
   });
+
+  describe('getSourceContext()', function() {
+    it('returns null when instrumentation is locked', function () {
+      sinon.stub(core.scopes.instrumentation, 'isLocked').returns(true);
+
+      simulateRequestScope(() => {
+        expect(core.assess.getSourceContext()).to.be.null;
+      });
+    });
+
+    it('returns null when not in request scope', function() {
+      expect(core.assess.getSourceContext()).to.be.null;
+      expect(core.logger.warn).to.have.been.calledWithMatch(
+        sinon.match.object,
+        'assess running outside of request scope',
+      );
+    });
+
+    it('returns null when assess is disabled by policy', function() {
+      simulateRequestScope(() => {
+        expect(core.assess.getSourceContext()).to.be.null;
+        expect(core.logger.trace).to.have.been.calledWith('Assess intentionally disabled for this request');
+      }, { assess: { policy: undefined } });
+    });
+
+    it('returns assess store when in request scope', function() {
+      simulateRequestScope(() => {
+        execStoreAssertions(core.assess.getSourceContext());
+      });
+    });
+
+    it('returns assess store when max source event threshold is not met', function() {
+      simulateRequestScope(() => {
+        execStoreAssertions(core.assess.getSourceContext());
+      });
+    });
+
+    it('returns null when max source event threshold is exceeded', function() {
+      core.config.setValue('assess.max_context_source_events', 10);
+
+      simulateRequestScope(() => {
+        expect(core.assess.getSourceContext()).to.be.null;
+      }, { assess: { sourceEventsCount: 11 } });
+    });
+  });
 });

package/lib/index.d.ts

@@ -37,12 +37,6 @@ export interface Core extends _Core {
   metrics: any;
 }
 
-export enum InstrumentationType {
-  SOURCE = 'source',
-  PROPAGATOR = 'propagator',
-  RULE = 'rule',
-}
-
 export interface SourceContext {
   reqData: object,
   responseData: {
@@ -74,14 +68,14 @@ export interface RuleState {
 
 export interface Assess {
   getPolicy(): Policy,
-  getSourceContext(instrType?: InstrumentationType, opts?: any): SourceContext,
+  getPropagatorContext(): SourceContext | null,
+  getSinkContext(ruleId: Rule): SourceContext | null,
+  getSourceContext(): SourceContext | null,
   makeSourceContext(req: IncomingMessage, res: ServerResponse): SourceContext,
   ruleScopes: RuleScopes,
   ruleState: RuleState,
 }
 
-export function getSourceContext(instrType?: InstrumentationType, ops?: any): SourceContext;
-
 declare function init(core: Core): Assess;
 
 export = init;

package/lib/response-scanning/install/http.js

@@ -89,7 +89,7 @@ module.exports = function(core) {
   }
 
   http.install = function() {
-    depHooks.resolve({ name: 'http' }, (http) => {
+    depHooks.resolve({ name: 'http', version: '*' }, (http) => {
       {
         const name = 'http.ServerResponse.prototype.write';
         patcher.patch(http.ServerResponse.prototype, 'write', {
@@ -116,7 +116,7 @@ module.exports = function(core) {
       }
     });
 
-    depHooks.resolve({ name: 'http2' }, (http2) => {
+    depHooks.resolve({ name: 'http2', version: '*' }, (http2) => {
       // todo: NODE-3467
       {
         const name = 'http2.Http2ServerResponse.prototype.write';
@@ -147,7 +147,7 @@ module.exports = function(core) {
       }
     });
 
-    depHooks.resolve({ name: 'spdy', file: 'lib/spdy/response.js' }, (response) => {
+    depHooks.resolve({ name: 'spdy', version: '<5', file: 'lib/spdy/response.js' }, (response) => {
       patcher.patch(response, 'end', {
         name: 'spdy.response.end',
         patchType: 'test',

package/lib/response-scanning/install/http.test.js

@@ -95,10 +95,10 @@ describe('assess response scanning sinks http', function () {
 
     http = require('./http')(core);
     core.depHooks.resolve
-      .withArgs({ name: 'http' })
+      .withArgs(sinon.match({ name: 'http' }))
       .yields(httpModule);
     core.depHooks.resolve
-      .withArgs({ name: 'http2' })
+      .withArgs(sinon.match({ name: 'http2' }))
       .yields(http2Module);
 
     http.install();

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

@@ -41,7 +41,7 @@ module.exports = function (core) {
   const expressSession = core.assess.sessionConfiguration.expressSession = {};
 
   expressSession.install = function () {
-    return depHooks.resolve({ name: 'express-session' }, (session) => {
+    return depHooks.resolve({ name: 'express-session', version: '<2' }, (session) => {
       // Return the hooked function as the export.
       const hooked = patcher.patch(session, {
         name: 'express.hookedSessionConstructor',

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

@@ -16,9 +16,7 @@ describe('assess session-configuration http', function () {
 
   beforeEach(function () {
     ({ core, simulateRequestScope } = initAssessFixture());
-    core.depHooks.resolve
-      .withArgs({ name: 'express-session' })
-      .yields(ExpressSession);
+    core.depHooks.resolve.yields(ExpressSession);
 
     sinon.spy(core.assess.sessionConfiguration, 'handleHttpOnly');
     sinon.spy(core.assess.sessionConfiguration, 'handleSecure');

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

@@ -40,7 +40,7 @@ module.exports = function (core) {
 
   return core.assess.sessionConfiguration.fastifyCookie = {
     install () {
-      depHooks.resolve({ name: '@fastify/cookie' }, (_export) => {
+      depHooks.resolve({ name: '@fastify/cookie', version: '<12' }, (_export) => {
         const patched = patcher.patch(_export, {
           name: 'express.hookedSessionConstructor',
           patchType,

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

@@ -26,9 +26,7 @@ describe('assess session-configuration @fastify/cookie', function () {
       addHook: sinon.stub().yields({}, reply),
     };
 
-    core.depHooks.resolve
-      .withArgs({ name: '@fastify/cookie' })
-      .yields(mockExport);
+    core.depHooks.resolve.yields(mockExport);
 
     sinon.stub(core.assess.sessionConfiguration, 'reportFindings');
     core.assess.sessionConfiguration.fastifyCookie.install();

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

@@ -39,7 +39,7 @@ module.exports = function (core) {
 
   return core.assess.sessionConfiguration.koa = {
     install () {
-      depHooks.resolve({ name: 'koa', version: '>=2.3.0' }, (Koa) => {
+      depHooks.resolve({ name: 'koa', version: '>=2.3.0 <3' }, (Koa) => {
         patcher.patch(Koa.prototype, 'use', {
           name: 'Koa.Application',
           patchType,

package/lib/session-configuration/install/koa.test.js

@@ -30,7 +30,7 @@ describe('assess sessionConfiguration Koa', function () {
     ctxMock.cookies = { set: sinon.stub() };
 
     core.depHooks.resolve
-      .withArgs({ name: 'koa', version: '>=2.3.0' })
+      .withArgs({ name: 'koa', version: '>=2.3.0 <3' })
       .yields(koaMock);
 
     sinon.stub(core.assess.sessionConfiguration, 'reportFindings');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.40.0",
+  "version": "1.42.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,17 +17,17 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.26.0",
-    "@contrast/config": "1.36.0",
-    "@contrast/core": "1.41.0",
-    "@contrast/dep-hooks": "1.9.0",
+    "@contrast/common": "1.27.0",
+    "@contrast/config": "1.37.0",
+    "@contrast/core": "1.42.0",
+    "@contrast/dep-hooks": "1.11.0",
     "@contrast/distringuish": "^5.1.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",
+    "@contrast/instrumentation": "1.21.0",
+    "@contrast/logger": "1.15.0",
+    "@contrast/patcher": "1.14.0",
+    "@contrast/rewriter": "1.18.0",
+    "@contrast/route-coverage": "1.32.0",
+    "@contrast/scopes": "1.12.0",
     "semver": "^7.6.0"
   }
 }

package/lib/constants.js

@@ -1,26 +0,0 @@
-/*
- * 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 InstrumentationType = {
-  SOURCE: 'SOURCE',
-  PROPAGATOR: 'PROPAGATOR',
-  RULE: 'RULE',
-};
-
-module.exports = {
-  InstrumentationType,
-};