@contrast/assess 1.1.0

package/lib/dataflow/event-factory.js

@@ -0,0 +1,256 @@
+/*
+ * Copyright: 2022 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 { InputType } = require('@contrast/common');
+const annotationRegExp = /^(A|O|R|P|P\d+)$/;
+
+module.exports = function(core) {
+  const {
+    createSnapshot,
+    config,
+    logger,
+    scopes: { sources },
+    assess: {
+      dataflow: { signatures }
+    }
+  } = core;
+  const eventFactory = core.assess.dataflow.eventFactory = {};
+
+  eventFactory.createdEvents = new WeakSet();
+
+  eventFactory.createSourceEvent = function(data = {}) {
+    const {
+      name,
+      result = { value: null, isTracked: false },
+      tags,
+      inputType,
+    } = data;
+
+    const baseMessage = 'Source event not created: %s';
+
+    if (!result.value) {
+      logger.debug({ result }, baseMessage, 'invalid result');
+      return null;
+    }
+
+    if (!name) {
+      logger.debug({ name }, baseMessage, 'invalid name');
+      return null;
+    }
+
+    if (!(inputType in InputType)) {
+      logger.debug({ inputType }, baseMessage, 'invalid inputType');
+      return null;
+    }
+
+    if (!tags) {
+      logger.debug({ data }, baseMessage, 'event has no tags');
+      return null;
+    }
+
+    eventFactory.createdEvents.add(data);
+
+    return data;
+  };
+
+  eventFactory.createPropagationEvent = function(data) {
+    const {
+      name = '',
+      history = [],
+      object = { value: null, isTracked: false },
+      args = [],
+      result = { value: null, isTracked: false },
+      tags = {},
+      addedTags = [],
+      removedTags = [],
+      source,
+      target,
+      stacktraceOpts
+    } = data;
+
+    const sourceContext = sources.getStore()?.assess;
+
+    if (!sourceContext) {
+      logger.debug({ name }, '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');
+      return null;
+    }
+
+    const signature = signatures.get(name);
+
+    if (!signature) {
+      logger.debug({ name }, 'Propagation event not created: no signature found for this name');
+      return null;
+    }
+
+    if (!history.length) {
+      logger.debug({ name, history }, 'Propagation event not created: invalid history');
+      return null;
+    }
+
+    if (
+      ((source && !source.match(annotationRegExp)) || (!source && !signature.source)) ||
+      ((target && !target.match(annotationRegExp)) || (!target && !signature.target))
+    ) {
+      logger.debug({ name, source, target }, 'Propagation event not created: %s', 'invalid source/target');
+      return null;
+    }
+
+    let stack;
+    if (config.assess.stacktraces === 'ALL') {
+      stack = createSnapshot(stacktraceOpts)();
+    } else {
+      stack = [];
+    }
+
+    const event = {
+      time: Date.now(),
+      history,
+      name,
+      object,
+      args,
+      result,
+      tags,
+      addedTags,
+      removedTags,
+      source,
+      target,
+      stack
+    };
+
+    eventFactory.createdEvents.add(event);
+    sourceContext.propagationEventsCount++;
+
+    return event;
+  };
+
+  eventFactory.createSinkEvent = function(data) {
+    const {
+      name = '',
+      history = [],
+      object = { value: null, isTracked: false },
+      args = [],
+      result = { value: null, isTracked: false },
+      tags = {},
+      source,
+      stacktraceOpts
+    } = data;
+    const sourceContext = sources.getStore()?.assess;
+
+    if (!sourceContext) {
+      logger.debug('No sourceContext found during Sink event creation');
+      return null;
+    }
+
+    const signature = signatures.get(name);
+
+    if (
+      !signature ||
+      !history.length ||
+      ((source && !source.match(annotationRegExp)) || (!source && !signature.source))
+    ) {
+      logger.debug({ data }, 'Wrong sink event data submited. Sink event not created');
+      return null;
+    }
+
+    let stack;
+    if (config.assess.stacktraces !== 'NONE') {
+      stack = createSnapshot(stacktraceOpts);
+    } else {
+      stack = [];
+    }
+
+    const event = {
+      time: Date.now(),
+      history,
+      name,
+      object,
+      args,
+      result,
+      tags,
+      source,
+      stack
+    };
+
+    eventFactory.createdEvents.add(event);
+
+    return event;
+  };
+
+  return eventFactory;
+};
+
+
+// Sample event data
+// const e = {
+//   // we need the time the event occurred
+//   time: '1234',
+//   history: ['argsTrackedInfo'],
+//   name: 'ContrastMethods.add', // as this method is used to rewrite not only `+` but `+=` too
+//   context: {
+//     obj: null,
+//     args: ['...args'],
+//     resultTracked: 'result'
+//   },
+//   stack: 'createSnapshot()',
+//   tags: 'newTags',
+//   // we need a property with add/removed tags
+//   addedTags: [],
+//   removedTags: [],
+//   // we need info for the source and the targeto
+//   source: 'A | P | O | R',
+//   target: 'A | P | O | R',
+//   // optional code property for the propagation through the ContrastMethods
+//   code: 'const a = b + c',
+//   // we need a signature property
+//   signature: {
+//     // in v4 we are storing all the signatures in a json file,
+//     // so we get the values from there and format them accordingly
+//   }
+// };
+
+// Sample payload for a discovered vulnerability
+// const payload = {
+//   created: Date.now(),
+//   events: [
+//     {
+//       action: e.addedTags.length || e.removedTags.length ? 'TAG' : `${e.source}2${e.target}`,
+//       args: e.context.args, // they will be "expanded" before reporting
+//       code: e.code,
+//       eventSources: [], // only for SourceEvents
+//       fieldName: '', // we don't set it in v4
+//       object: e.context.obj, // again it will be expanded later
+//       parentObjectsIds: [], // we don't set it in v4
+//       properties: [], // not needed for dataflow
+//       ret: e.context.resultTracked,
+//       signature: e.signature,
+//       source: e.source,
+//       stacktrace: e.stack,
+//       tags: e.addedTags.join(), // in v4 we set all tags here, idk why
+//       taintRanges: e.tags.map(), // the tag ranges we want highlighted in ContrastUI
+//       target: e.target,
+//       thread: process.pid,
+//       time: e.time,
+//       type: e.addedTags.length || e.removedTags.length ? 'TAG' : 'PROPAGATION'
+//     }
+//   ]
+// };

package/lib/dataflow/index.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright: 2022 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 { callChildComponentMethodsSync } = require('@contrast/common');
+
+module.exports = function(core) {
+  const dataflow = core.assess.dataflow = {};
+
+  require('./signatures')(core);
+  require('./event-factory')(core);
+  require('./tracker')(core);
+  require('./sources')(core);
+  require('./propagation')(core);
+  require('./sinks')(core);
+
+  dataflow.install = function() {
+    callChildComponentMethodsSync(dataflow, 'install');
+  };
+
+  return dataflow;
+};

package/lib/dataflow/propagation/common.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright: 2022 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';
+
+module.exports = {
+  patchType: 'assess-dataflow-propagator',
+  createModuleLabel(name, version = '1.0.0') {
+    return `Module<${name}@${version}>`;
+  },
+  createObjectLabel(name, id = '0001') {
+    return `Object<${name}@${id}>`;
+  }
+};

package/lib/dataflow/propagation/index.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright: 2022 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 { callChildComponentMethodsSync } = require('@contrast/common');
+
+module.exports = function(core) {
+  const propagation = core.assess.dataflow.propagation = {};
+
+  require('./install/string')(core);
+  require('./install/array-prototype-join')(core);
+  require('./install/pug')(core);
+  require('./install/contrast-methods')(core);
+  require('./install/validator')(core);
+  require('./install/url')(core);
+  require('./install/ejs')(core);
+  require('./install/encode-uri-component')(core);
+  require('./install/decode-uri-component')(core);
+  require('./install/escape-html')(core);
+  require('./install/escape')(core);
+  require('./install/handlebars-utils-escape-expression')(core);
+  require('./install/mysql-connection-escape')(core);
+  require('./install/pug-runtime-escape')(core);
+  require('./install/sql-template-strings')(core);
+  require('./install/unescape')(core);
+
+
+  propagation.install = function() {
+    callChildComponentMethodsSync(propagation, 'install');
+  };
+
+  propagation.uninstall = function() {
+    callChildComponentMethodsSync(propagation, 'uninstall');
+  };
+
+  return propagation;
+};

package/lib/dataflow/propagation/install/array-prototype-join.js

@@ -0,0 +1,125 @@
+/*
+ * Copyright: 2022 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 {
+  createAppendTags
+} = require('../../tag-utils');
+const { patchType } = require('../common');
+const { isString } = require('@contrast/common');
+
+module.exports = function(core) {
+  const {
+    scopes: { sources, instrumentation },
+    patcher,
+    assess: {
+      dataflow: { tracker, eventFactory: { createPropagationEvent } }
+    }
+  } = core;
+
+  function accumulateTags(array, tags, offset, history, delimiterLength = 1, delimiterTags = {}) {
+    let globalOffset = offset;
+    let newTags = tags;
+    let newHistory = history;
+    for (let i = 0; i < array.length; i++) {
+      const elem = array[i];
+      if ((!isString(elem) && !Array.isArray(elem)) || !elem) continue;
+
+      if (Array.isArray(elem)) {
+        ({ newTags, newHistory, globalOffset } = accumulateTags(elem, newTags, globalOffset, newHistory));
+      } else {
+        const elInfo = tracker.getData(elem);
+        if (elInfo) {
+          const elTags = elInfo.tags || {};
+          newHistory.add(elInfo);
+          Object.assign(newTags, createAppendTags(newTags, elTags, globalOffset));
+        }
+
+        globalOffset += elem.length;
+      }
+
+      if (i !== array.length - 1) {
+        Object.keys(delimiterTags).length && Object.assign(newTags, createAppendTags(newTags, delimiterTags, globalOffset));
+
+        globalOffset += delimiterLength;
+      }
+    }
+
+    return { newTags, newHistory, globalOffset };
+  }
+
+  return core.assess.dataflow.propagation.arrayJoin = {
+    install() {
+      const originalJoin = Array.prototype.join;
+      patcher.patch(Array.prototype, 'join', {
+        name: 'Array.prototype.join',
+        patchType,
+        post(data) {
+          const { args, obj, result, hooked, orig } = data;
+          if (!result || !sources.getStore()?.assess || instrumentation.isLocked()) return;
+
+          const resultInfo = tracker.getData(result);
+          const delimiter = args[0] === undefined ? ',' : args[0];
+          const delimiterLength = delimiter.length;
+          const delimiterInfo = tracker.getData(delimiter);
+          const initHistory = delimiterInfo ? new Set([delimiterInfo]) : new Set();
+          const { newTags, newHistory: history } = accumulateTags(obj, {}, 0, initHistory, delimiterLength, delimiterInfo?.tags);
+
+          if (history.size) {
+            const event = createPropagationEvent({
+              name: 'Array.prototype.join',
+              object: {
+                value: originalJoin.call(obj),
+                isTracked: false
+              },
+              result: {
+                value: resultInfo ? resultInfo.value : result,
+                isTracked: true
+              },
+              args: [{
+                value: delimiterInfo ? delimiterInfo.value : delimiter,
+                isTracked: !!delimiterInfo
+              }],
+              tags: newTags,
+              history: Array.from(history),
+              source: delimiterInfo ? (history.size > 1 ? 'A' : 'P') : 'O',
+              target: 'R',
+              stacktraceOpts: {
+                constructorOpt: hooked,
+                prependFrames: [orig]
+              },
+            });
+
+            if (!event) return;
+
+            if (resultInfo) {
+              Object.assign(resultInfo, event);
+            }
+
+            const { extern } = resultInfo || tracker.track(result, event);
+
+            if (extern) {
+              data.result = extern;
+            }
+          }
+        }
+      });
+    },
+    uninstall() {
+      Array.prototype.join = patcher.unwrap(Array.prototype.join);
+    },
+  };
+};

package/lib/dataflow/propagation/install/contrast-methods/add.js

@@ -0,0 +1,104 @@
+/*
+ * Copyright: 2022 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 {
+  createAppendTags
+} = require('../../../tag-utils');
+const { patchType, createObjectLabel } = require('../../common');
+
+module.exports = function(core) {
+  const {
+    scopes: { instrumentation, sources },
+    patcher,
+    assess: {
+      dataflow: { tracker, eventFactory: { createPropagationEvent } }
+    }
+  } = core;
+
+  return core.assess.dataflow.propagation.contrastMethodsInstrumentation.add = {
+    install() {
+      patcher.patch(global.ContrastMethods, 'add', {
+        name: 'ContrastMethods.add',
+        patchType,
+        post(data) {
+          const { args, result, hooked, orig } = data;
+          if (!result || !sources.getStore()?.assess || instrumentation.isLocked()) return;
+
+          const rInfo = tracker.getData(result);
+          if (rInfo) {
+            // this may happen w/ '' + 'tracked' => 'tracked'
+            return;
+          }
+
+          const leftStringInfo = tracker.getData(args[0]);
+          const rightStringInfo = tracker.getData(args[1]);
+
+          let newTags = {};
+          const history = [];
+
+          if (leftStringInfo) {
+            history.push(leftStringInfo);
+            newTags = leftStringInfo.tags || {};
+          }
+
+          if (rightStringInfo) {
+            history.push(rightStringInfo);
+            newTags = createAppendTags(newTags, rightStringInfo.tags, args[0].length);
+          }
+
+          if (history.length) {
+            const event = createPropagationEvent({
+              name: 'ContrastMethods.add',
+              history,
+              object: {
+                value: createObjectLabel('ContrastMethods'),
+                isTracked: false
+              },
+              args: [
+                {
+                  value: args[0],
+                  isTracked: !!leftStringInfo
+                },
+                {
+                  value: args[1],
+                  isTracked: !!rightStringInfo
+                }
+              ],
+              result: {
+                value: result,
+                isTracked: true
+              },
+              tags: newTags,
+              stacktraceOpts: {
+                constructorOpt: hooked,
+                prependFrames: [orig]
+              }
+            });
+            const { extern } = tracker.track(result, event);
+
+            if (extern) {
+              data.result = extern;
+            }
+          }
+        }
+      });
+    },
+    uninstall() {
+      global.ContrastMethods.add = patcher.unwrap(global.ContrastMethods.add);
+    },
+  };
+};

package/lib/dataflow/propagation/install/contrast-methods/index.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright: 2022 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 { callChildComponentMethodsSync } = require('@contrast/common');
+
+module.exports = function(core) {
+  const contrastMethodsInstrumentation = core.assess.dataflow.propagation.contrastMethodsInstrumentation = {
+    install() {
+      callChildComponentMethodsSync(contrastMethodsInstrumentation, 'install');
+    },
+    uninstall() {
+      callChildComponentMethodsSync(contrastMethodsInstrumentation, 'uninstall');
+    },
+  };
+
+  require('./add')(core);
+  require('./tag')(core);
+
+  return contrastMethodsInstrumentation;
+};