@contrast/assess 1.18.0 → 1.20.0

package/lib/dataflow/sources/install/querystring.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -28,17 +28,14 @@ module.exports = (core) => {
         (querystring) => patcher.patch(querystring, 'parse', {
           name,
           patchType,
-          post({ args, hooked, orig, result }) {
+          post({ args, hooked, orig, result, funcKey }) {
             const sourceContext = core.scopes.sources.getStore()?.assess;
             const inputType = InputType.QUERYSTRING;
 
-            if (!sourceContext) {
-              logger.error({ name }, 'unable to handle source. Missing `sourceContext`');
-              return;
-            }
+            if (!sourceContext) return;
 
             if (sourceContext.parsedQuery) {
-              logger.trace({ name }, 'values already tracked');
+              logger.trace({ funcKey }, 'values already tracked');
               return;
             }
 
@@ -61,7 +58,7 @@ module.exports = (core) => {
                 // we do not set the `parsedQuery` value here so that frameworks
                 // may handle queries in their own more specific manner.
               } catch (err) {
-                logger.error({ err, name }, 'unable to handle source');
+                logger.error({ err, funcKey }, 'unable to handle source');
               }
             }
           }

package/lib/dataflow/tag-utils.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 

package/lib/dataflow/tracker.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 

package/lib/dataflow/utils/is-safe-content-type.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 

package/lib/dataflow/utils/is-vulnerable.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 

package/lib/event-factory.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -16,9 +16,11 @@
 'use strict';
 
 const { InputType, match } = require('@contrast/common');
-const annotationRegExp = /^(A|O|R|P|P\d+)$/;
+const ANNOTATION_REGEX = /^(A|O|R|P|P\d+)$/;
+const SOURCE_EVENT_MSG = 'Source event not created: %s';
+const PROPAGATION_EVENT_MSG = 'Propagation event not created: %s';
 
-module.exports = function(core) {
+module.exports = function (core) {
   const {
     createSnapshot,
     config,
@@ -30,7 +32,7 @@ module.exports = function(core) {
 
   eventFactory.createdEvents = new WeakSet();
 
-  eventFactory.createSourceEvent = function(data = {}) {
+  eventFactory.createSourceEvent = function (data = {}) {
     const {
       name,
       result = { value: null, tracked: false },
@@ -39,31 +41,29 @@ module.exports = function(core) {
       stack,
     } = data;
 
-    const baseMessage = 'Source event not created: %s';
-
     if (!result.value) {
-      logger.debug({ result }, baseMessage, 'invalid result');
+      logger.debug({ data }, SOURCE_EVENT_MSG, 'invalid result');
       return null;
     }
 
     if (!name) {
-      logger.debug({ data }, baseMessage, 'invalid name');
+      logger.debug({ data }, SOURCE_EVENT_MSG, 'invalid name');
       return null;
     }
 
     if (!(inputType in InputType)) {
-      logger.debug({ inputType }, baseMessage, 'invalid inputType');
+      logger.debug({ data }, SOURCE_EVENT_MSG, 'invalid inputType');
       return null;
     }
 
     if (!tags) {
-      logger.debug({ data }, baseMessage, 'event has no tags');
+      logger.debug({ data }, SOURCE_EVENT_MSG, 'event has no tags');
       return null;
     }
 
 
     if (!stack || !Array.isArray(stack)) {
-      logger.debug({ data }, baseMessage, 'invalid stack');
+      logger.debug({ data }, SOURCE_EVENT_MSG, 'invalid stack');
       return null;
     }
 
@@ -73,7 +73,7 @@ module.exports = function(core) {
     return data;
   };
 
-  eventFactory.createPropagationEvent = function(data) {
+  eventFactory.createPropagationEvent = function (data) {
     const {
       name = '',
       moduleName,
@@ -94,30 +94,32 @@ module.exports = function(core) {
     const sourceContext = sources.getStore()?.assess;
 
     if (!sourceContext) {
-      logger.debug({ name }, 'No sourceContext found during Propagation event creation');
+      logger.debug({ data }, 'No sourceContext found during Propagation event creation');
       return null;
     }
 
     if (sourceContext.propagationEventsCount >= config.assess.max_propagation_events) {
-      logger.debug({ name }, 'Maximum number of Propagation events reached. Event not created');
+      logger.debug({ data }, 'Maximum number of Propagation events reached. Event not created');
       return null;
     }
 
     if (!name) {
-      logger.debug({ name }, 'Propagation event not created: invalid name');
+      logger.debug({ data }, PROPAGATION_EVENT_MSG, 'invalid name');
       return null;
     }
 
     if (!history.length) {
-      logger.debug({ name, history }, 'Propagation event not created: invalid history');
+      logger.debug({ data }, PROPAGATION_EVENT_MSG, 'invalid history');
       return null;
     }
 
-    if (
-      (!source || !match(source, annotationRegExp)) ||
-      (!target || !match(target, annotationRegExp))
-    ) {
-      logger.debug({ name, source, target }, 'Propagation event not created: %s', 'invalid source/target');
+    if (!source || !match(source, ANNOTATION_REGEX)) {
+      logger.debug({ data }, PROPAGATION_EVENT_MSG, 'invalid source');
+      return null;
+    }
+
+    if (!target || !match(target, ANNOTATION_REGEX)) {
+      logger.debug({ data }, PROPAGATION_EVENT_MSG, 'invalid target');
       return null;
     }
 
@@ -152,7 +154,7 @@ module.exports = function(core) {
     return event;
   };
 
-  eventFactory.createSinkEvent = function(data) {
+  eventFactory.createSinkEvent = function (data) {
     const {
       context,
       name = '',
@@ -169,7 +171,7 @@ module.exports = function(core) {
 
     const sourceContext = sources.getStore()?.assess;
     if (!sourceContext) {
-      logger.debug('no sourceContext found during sink event creation');
+      logger.debug({ data }, 'no sourceContext found during sink event creation');
       return null;
     }
     if (!name) {
@@ -181,7 +183,7 @@ module.exports = function(core) {
       return null;
     }
     if (
-      (!source || !source.match(annotationRegExp))
+      (!source || !source.match(ANNOTATION_REGEX))
     ) {
       logger.debug({ data }, 'malformed or missing sink event source field');
       return null;
@@ -214,7 +216,7 @@ module.exports = function(core) {
     return event;
   };
 
-  eventFactory.createSessionEvent = function(data) {
+  eventFactory.createSessionEvent = function (data) {
     const {
       context,
       name = '',
@@ -235,7 +237,7 @@ module.exports = function(core) {
     }
 
     if (
-      (!source || !source.match(annotationRegExp))
+      (!source || !source.match(ANNOTATION_REGEX))
     ) {
       logger.debug({ data }, 'malformed or missing sink event source field');
       return null;
@@ -270,5 +272,52 @@ module.exports = function(core) {
     return event;
   };
 
+
+  /**
+   * @param {{
+   *  context: string,
+   *  name: string,
+   *  moduleName: string,
+   *  methodName: string,
+   *  object: { value: any, tracked: boolean },
+   *  args: any[],
+   *  result: { value: vany, tracked: boolean },
+   *  source: string,
+   *  stacktraceOpts: { constructorOpt?: Function},
+   * }} data
+   * @returns {any}
+   */
+  eventFactory.createCryptoAnalysisEvent = function (data) {
+    const {
+      name = '',
+      source,
+      stacktraceOpts,
+    } = data;
+
+    if (!name) {
+      logger.debug({ data }, 'no sink event name');
+      return null;
+    }
+
+    if (!source || !source.match(ANNOTATION_REGEX)) {
+      logger.debug({ data }, 'malformed or missing sink event source field');
+      return null;
+    }
+
+    let stack;
+    if (config.assess.stacktraces !== 'NONE') {
+      stack = createSnapshot(stacktraceOpts)();
+    } else {
+      stack = [];
+    }
+
+    data.stack = stack;
+    data.time = Date.now();
+
+    eventFactory.createdEvents.add(data);
+
+    return data;
+  };
+
   return eventFactory;
 };

package/lib/get-policy.js

@@ -0,0 +1,68 @@
+/*
+ * 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 {
+  Rule,
+  ResponseScanningRule,
+  SessionConfigurationRule,
+  Event,
+} = require('@contrast/common');
+
+const rulesIds = Object.values({
+  ...Rule,
+  ...ResponseScanningRule,
+  ...SessionConfigurationRule,
+});
+
+/**
+ * @param {{
+ *  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 { logger, messages } = core;
+
+  const enabledRules = new Set(rulesIds);
+
+  messages.on(Event.SERVER_SETTINGS_UPDATE, (msg) => {
+    if (!msg.assess) return;
+
+    for (const ruleId of rulesIds) {
+      const enable = msg.assess[ruleId]?.enable;
+      if (enable === true) {
+        enabledRules.add(ruleId);
+        if (ruleId === Rule.NOSQL_INJECTION) enabledRules.add(Rule.NOSQL_INJECTION_MONGO);
+      } else if (enable === false) {
+        if (ruleId === Rule.NOSQL_INJECTION) enabledRules.delete(Rule.NOSQL_INJECTION_MONGO);
+        enabledRules.delete(ruleId);
+      }
+    }
+    logger.info({
+      enabledRules: Array.from(enabledRules)
+    }, 'Assess policy updated');
+  });
+
+  return core.assess.getPolicy = function getPolicy() {
+    // creates copy of local policy for request store
+    return {
+      enabledRules: new Set(enabledRules),
+    };
+  };
+};

package/lib/get-source-context.js

@@ -0,0 +1,62 @@
+/*
+ * 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 } = require('./constants');
+
+/**
+ * @param {{
+ *  assess: import('@contrast/assess').Assess,
+ *  config: import('@contrast/config').Config,
+ *  scopes: import('@contrast/scopes').Scopes,
+ * }} core
+ */
+module.exports = function(core) {
+  const {
+    config,
+    scopes: { sources, instrumentation },
+    assess: { ruleScopes },
+  } = core;
+
+  /**
+   * @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;
+
+    if (!ctx || instrumentation.isLocked()) return null;
+
+    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;
+      }
+    }
+
+    return ctx;
+  };
+};

package/lib/index.d.ts

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+import { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  Rule,
+  SessionConfigurationRule,
+} from '@contrast/common';
+
+export enum InstrumentationType {
+  SOURCE = 'source',
+  PROPAGATOR = 'propagator',
+  RULE = 'rule',
+}
+
+export interface SourceContext {
+  reqData: object,
+  responseData: {
+    contentType: string,
+  },
+  policy: {
+    enabledRules: Set<string>,
+  }
+}
+
+export interface Policy {
+  enabledRules: Set<Rule>,
+}
+
+export interface RuleScopes {
+  run(ruleId: Rule, cb: void): void;
+  isLocked(ruleId: Rule): boolean;
+}
+
+export interface SessionRuleState {
+  reported: boolean,
+  valuesAnalyzed: Set<string>,
+}
+
+export interface RuleState {
+  [SessionConfigurationRule.HTTPONLY]?: SessionRuleState,
+  [SessionConfigurationRule.SECURE_FLAG_MISSING]?: SessionRuleState,
+}
+
+export interface Assess {
+  getPolicy(): Policy,
+  getSourceContext(instrType?: InstrumentationType, opts?: any): SourceContext,
+  makeSourceContext(req: IncomingMessage, res: ServerResponse): SourceContext,
+  ruleScopes: RuleScopes,
+  ruleState: RuleState,
+}
+
+export function getSourceContext(instrType?: InstrumentationType, ops?: any): SourceContext;

package/lib/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -16,32 +16,33 @@
 'use strict';
 
 const { callChildComponentMethodsSync } = require('@contrast/common');
-const sessionConfiguration = require('./session-configuration');
-const dataflow = require('./dataflow');
-const responseScanning = require('./response-scanning');
-const eventFactory = require('./event-factory');
 
 module.exports = function assess(core) {
-  const assess = core.assess = {};
+  const assess = core.assess = {
+    install() {
+      if (!core.config.getEffectiveValue('assess.enable')) {
+        core.logger.debug('assess is disabled, skipping installation');
+        return;
+      }
+
+      core.rewriter.install('assess');
+      callChildComponentMethodsSync(core.assess, 'install');
+    },
+  };
 
-  eventFactory(core);
-  dataflow(core);
-  responseScanning(core);
-  sessionConfiguration(core);
+  require('./rule-scopes')(core);
+  require('./get-policy')(core);
+  require('./make-source-context')(core);
+  require('./get-source-context')(core);
+  require('./event-factory')(core);
+  require('./crypto-analysis')(core);
+  require('./dataflow')(core);
+  require('./response-scanning')(core);
+  require('./session-configuration')(core);
 
   // todo
   // crypto rule implementations
   // static rule implementations in coordination with (CLI) rewriter
 
-  assess.install = function() {
-    if (!core.config.getEffectiveValue('assess.enable')) {
-      core.logger.debug('assess is disabled, skipping installation');
-      return;
-    }
-
-    core.rewriter.install('assess');
-    callChildComponentMethodsSync(core.assess, 'install');
-  };
-
   return assess;
 };

package/lib/make-source-context.js

@@ -0,0 +1,78 @@
+/*
+ * 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 { toLowerCase } = require('@contrast/common');
+
+/**
+ * @param {{
+ *  assess: import('@contrast/assess').Assess,
+ *  logger: import('@contrast/logger').Logger,
+ * }} core
+ */
+module.exports = function(core) {
+  const {
+    assess: { getPolicy },
+    logger,
+  } = core;
+
+  /**
+   * @returns {import('@contrast/assess').SourceContext}
+   */
+  return core.assess.makeSourceContext = function (req, res) {
+    let contentType, queries, uriPath;
+
+    try {
+      const ix = req.url.indexOf('?');
+      if (ix >= 0) {
+        uriPath = req.url.slice(0, ix);
+        queries = req.url.slice(ix + 1);
+      } else {
+        uriPath = req.url;
+        queries = '';
+      }
+
+      // copy to avoid storing tracked values
+      const headers = { ...req.headers };
+      if (headers['content-type']) {
+        contentType = toLowerCase(headers['content-type']);
+      }
+
+      return {
+        propagationEventsCount: 0,
+        sourceEventsCount: 0,
+        policy: getPolicy(),
+        reqData: {
+          ip: req.socket.remoteAddress,
+          httpVersion: req.httpVersion,
+          method: req.method,
+          headers,
+          uriPath,
+          queries,
+          contentType,
+        },
+        responseData: {},
+        ruleState: {},
+      };
+    } catch (err) {
+      logger.error(
+        { err },
+        'unable to construct assess store. assess will be disabled for request.'
+      );
+      return null;
+    }
+  };
+};