@contrast/assess 1.20.2 → 1.21.0

package/lib/dataflow/propagation/install/url/searchParams.js

@@ -72,9 +72,11 @@ module.exports = function(core) {
 
             if (isString(params)) {
               params.split('&').forEach((query) => {
-                const startIdx = query.indexOf('?') + 1;
                 const endIdx = query.indexOf('=');
-                const key = query.substring(startIdx, endIdx);
+                // this is pretty ugly because we don't want to create a propagation
+                // event by splitting off the '?'. so we count on if it's there, we
+                // skip it and if it's not there, we start at index 0.
+                const key = query.substring(query.indexOf('?') + 1, endIdx);
                 const param = query.substring(endIdx + 1, query.length);
 
                 const keyInfo = tracker.getData(key);

package/lib/dataflow/tag-utils.js

@@ -12,25 +12,90 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-
 'use strict';
 
-function ensureTagsImmutable(obj, tagName) {
-  return obj[tagName] ? [...obj[tagName]] : [];
-}
+//
+// This module implements tag range manipulation functions. There are generally
+// two types of functions:
+//
+// wrappers (create*Tags) - these functions take a set of tags and return a new
+// new set of tags. The new set of tags is *always* a new object with new tag
+// ranges, i.e., the input argument is considered immutable. Tag ranges are
+// *always* returned in "resolved" form, meaning adjacent or overlapping ranges
+// have been merged.
+//
+// core functions - these functions are used by the wrappers to implement their
+// function on a single tag's tag ranges.
+//
+// Tag ranges are represented as an array of integers that must be an even
+// length. The even indices are the start of a tag range and the odd indices
+// are the end of a range. *Unlike most JavaScript string functions*, the end
+// index is inclusive. [0, 0] is a tag range of length 1.
+//
+// All tag ranges are expected to be in "resolved" form, meaning adjacent or
+// overlapping ranges have been merged:
+// - [0, 1] not [0, 0, 1, 1]
+// - [0, 10] not [0, 7, 5, 10]
+//
 
-function ensureObject(tags) {
-  return tags ? { ...tags } : {};
-}
+/**
+ * Appends one set of tags to another set of tags.
+ *
+ * @param {object} firstTags base set of tags
+ * @param {object} secondTags tags to be added
+ * @param {number} offset offset to apply to the second set of tags. It is
+ *        the length of the string that firstTags is associated with.
+ *
+ * @returns {object} - the resulting tag ranges or null if there were no tags.
+ *
+ * @examples (args => return)
+ * - {},null,9 => null
+ * - {},{"UNTRUSTED":[0,2]},3 => {"UNTRUSTED":[3,5]}
+ * - {"untrusted":[12,18]},{"untrusted":[0,13]},38 => {"untrusted":[12,18,38,51]}
+ * - {"untrusted":[0,2]},{},3 => {"untrusted":[0,2]}
+ */
+function createAppendTags(firstTags, secondTags, offset) {
+  if (!firstTags && !secondTags) {
+    return null;
+  }
 
-function atomicAppend(firstTagRanges, secondTagRanges, offset) {
-  if (!firstTagRanges.length) {
-    const ret = secondTagRanges.map((v) => v + offset);
-    return ret;
+  const ret = Object.create(null);
+
+  let tagNames;
+  if (!firstTags) {
+    tagNames = new Set([...Object.keys(secondTags)]);
+    firstTags = {};
+  } else if (!secondTags) {
+    tagNames = new Set([...Object.keys(firstTags)]);
+    secondTags = {};
+  } else {
+    tagNames = new Set([...Object.keys(firstTags), ...Object.keys(secondTags)]);
+  }
+
+  let any = null;
+  for (const tagName of tagNames) {
+    const newTagRanges = appendCore(firstTags[tagName], secondTags[tagName], offset);
+
+    if (newTagRanges) {
+      ret[tagName] = newTagRanges;
+      any = ret;
+    }
   }
 
+  return any;
+}
+
+function appendCore(firstTagRanges, secondTagRanges, offset) {
+  if (!firstTagRanges?.length && !secondTagRanges?.length) {
+    return null;
+  } else if (!firstTagRanges?.length) {
+    return secondTagRanges.map((v) => v + offset);
+  } else if (!secondTagRanges?.length) {
+    return [...firstTagRanges];
+  }
 
   const newTagRanges = [...firstTagRanges];
+  secondTagRanges = [...secondTagRanges];
 
   for (let i = 0; i < secondTagRanges.length; i++) {
     secondTagRanges[i] += offset;
@@ -38,7 +103,7 @@ function atomicAppend(firstTagRanges, secondTagRanges, offset) {
 
   const firstTagRangesLastEnd = firstTagRanges[firstTagRanges.length - 1];
 
-  if (firstTagRangesLastEnd === secondTagRanges[0] || firstTagRangesLastEnd === secondTagRanges[0] - 1) {
+  if (firstTagRangesLastEnd >= secondTagRanges[0] - 1) {
     newTagRanges.pop();
     secondTagRanges.shift();
   }
@@ -48,10 +113,85 @@ function atomicAppend(firstTagRanges, secondTagRanges, offset) {
   return newTagRanges;
 }
 
-function atomicSubset(tags, subsetStart, len) {
+/**
+ * Return the tag ranges that overlap the given range. The overlap does not
+ * need to be complete, i.e., an intersection causes the entire tag range
+ * to match.
+ *
+ * @param {object} tags tags
+ * @param {number} startIndex
+ * @param {number} endIndex
+ *
+ * @returns {object} the overlapping tag ranges. It can be an empty object
+ * when there no tags overlap. NOTE: it does not return null when there are
+ * no overlapping tags AND it returns tag ranges as arrays of 2-element
+ * arrays. Why is lost to history.
+ *
+ * @examples
+ * - {x: [10, 20]}, 15, 17 => { x: [ [ 10, 20 ] ] }
+ * - {x: [17, 20]}, 90, 100 => {}
+ * - {x: [17, 20]}, 15, 17 => { x: [ [ 17, 20 ] ] }
+ *
+ */
+function createOverlappingTags(tags, startIndex, endIndex) {
+  const overlappingTags = {};
+
+  for (const [tag, tagRanges] of Object.entries(tags)) {
+    const overlappingRanges = [];
+
+    for (let i = 0; i < tagRanges.length; i += 2) {
+      if (tagRanges[i + 1] >= startIndex && tagRanges[i] <= endIndex) {
+        overlappingRanges.push([tagRanges[i], tagRanges[i + 1]]);
+      }
+    }
+
+    if (overlappingRanges.length > 0) {
+      overlappingTags[tag] = overlappingRanges;
+    }
+  }
+
+  return overlappingTags;
+}
+
+/**
+ * this is not intuitive in that it not only returns the subset of tags that exist
+ * within the subsetStart/len range, but it also adjusts the tag ranges to be relative
+ * to the subsetStart.
+ *
+ * @param tags tag ranges to adjust
+ * @param subsetStart start index of the subset range
+ * @param len length of the subset range (subsetStop = subsetStart + len - 1)
+ *
+ * @returns {object} tags with adjusted ranges or null if no tags overlapped
+ * the subset range.
+ *
+ * @examples (args => return)
+ * - {"UNTRUSTED":[0,16]}, 13, 4 => {"UNTRUSTED":[0,3]}
+ * - {"x":[0,1],"ampersand":[6,6], "y":[7,8]}, 0, 1 => {"x":[0,0]}
+ */
+function createSubsetTags(tags, subsetStart, len) {
+  if (!tags) {
+    return null;
+  }
+  const ret = Object.create(null);
+
+  let some = null;
+  for (const tagName of Object.keys(tags)) {
+    const newTagRanges = subsetCore(tags[tagName], subsetStart, len);
+    if (newTagRanges) {
+      ret[tagName] = newTagRanges;
+      some = ret;
+    }
+  }
+
+  return some;
+}
+
+function subsetCore(tags, subsetStart, len) {
   const ret = [];
   const subsetStop = subsetStart + len - 1;
 
+  let some = null;
   for (let idx = 0; idx < tags.length - 1; idx += 2) {
     const tagStart = tags[idx];
     const tagStop = tags[idx + 1];
@@ -69,12 +209,97 @@ function atomicSubset(tags, subsetStart, len) {
       Math.max(tagStart, subsetStart) - subsetStart,
       Math.min(tagStop, subsetStop) - subsetStart,
     );
+    some = ret;
+  }
+
+  return some;
+}
+
+/**
+ * Create new tags from 0 to the specified length for each tag name in the
+ * input tags.
+ *
+ * @param {object} tags tags names to use
+ * @param {number} resultLength length for new tag ranges.
+ *
+ * @returns {object} new tags or null if no tags
+ *
+ * @examples (args => return)
+ * - {"UNTRUSTED":[0,18]}, 24 => {"UNTRUSTED":[0,23]}
+ * - {"UNTRUSTED":[0,4], "URL_ENCODED":[0,0]}, 33 => {"UNTRUSTED":[0,32],"URL_ENCODED":[0,32]}
+ */
+function createFullLengthCopyTags(tags, resultLength) {
+  if (!resultLength || resultLength < 0 || !tags) {
+    return null;
+  }
+
+  const tagNames = Object.keys(tags);
+  if (!tagNames.length) {
+    // no need to check result after the loop
+    return null;
+  }
+
+  resultLength = resultLength - 1;
+
+  const ret = Object.create(null);
+  for (const tagName of tagNames) {
+    ret[tagName] = [0, resultLength];
   }
 
   return ret;
 }
 
-function atomicMerge(firstTagRanges, secondTagRanges) {
+/**
+ * Create the union of two sets of tags.
+ *
+ * @param {object} firstTags first set of tags
+ * @param {object} secondTags second set of tags
+ *
+ * @returns {object} new tags or null if no tags
+ *
+ * @examples (args => return)
+ * - {},null => null
+ * - {}, {} => null
+ * - {},{"UNTRUSTED":[5,7]} => {"UNTRUSTED":[5,7]}
+ * - {"UNTRUSTED":[14,22]},{"UNTRUSTED":[11,13]} => {"UNTRUSTED":[11,22]}
+ * - {"UNTRUSTED":[5,20]},{"UNTRUSTED":[0,4]} => {"UNTRUSTED":[0,20]}
+ */
+function createMergedTags(firstTags, secondTags) {
+  const ret = Object.create(null);
+
+  if (!firstTags && !secondTags) {
+    return null;
+  } else if (!firstTags) {
+    return copyTags(secondTags);
+  } else if (!secondTags) {
+    return copyTags(firstTags);
+  }
+
+  // only do set building and merging if both sets of tags are not empty
+  const tagNames = new Set([...Object.keys(firstTags), ...Object.keys(secondTags)]);
+
+  let some = null;
+  for (const tagName of tagNames) {
+    const newTagRanges = mergeCore(firstTags[tagName], secondTags[tagName]);
+
+    if (newTagRanges.length) {
+      some = ret;
+      ret[tagName] = newTagRanges;
+    }
+  }
+
+  return some;
+}
+
+function mergeCore(firstTagRanges, secondTagRanges) {
+  if (!firstTagRanges && !secondTagRanges) {
+    return [];
+  } else if (!firstTagRanges) {
+    return [...secondTagRanges];
+  } else if (!secondTagRanges) {
+    return [...firstTagRanges];
+  }
+
   const mergedRanges = [];
   let i = 0;
   let j = 0;
@@ -125,7 +350,52 @@ function atomicMerge(firstTagRanges, secondTagRanges) {
   return finalMergedRanges;
 }
 
-function atomicExclude(tags, exclusionRange) {
+function copyTags(tags) {
+  const ret = Object.create(null);
+
+  let some = null;
+  for (const tagName of Object.keys(tags)) {
+    ret[tagName] = [...tags[tagName]];
+    some = ret;
+  }
+  return some;
+}
+
+/**
+ * Create new tags that exclude the given range.
+ *
+ * @param {object} tags tags used to create new tags
+ * @param {number} exclusionRange the new tags will not include this range
+ *
+ * @returns {object} new tags or null if no tags after excluding the range
+ *
+ * @examples (args => return)
+ * - {},[13,13] => null
+ * - {"UNTRUSTED":[0,8]},[6,6] => {"UNTRUSTED":[0,5,7,8]}
+ * - {"UNTRUSTED":[13,16]},[13,13] => {"UNTRUSTED":[14,16]}
+ */
+function createTagsWithExclusion(tags, exclusionRange) {
+  // if no exclusionRange or no tags, there's nothing to do
+  if (!exclusionRange.length || !tags) {
+    return null;
+  }
+
+  const ret = Object.create(null);
+  let some = null;
+
+  for (const tagName of Object.keys(tags)) {
+    const newTagRanges = excludeRangeCore(tags[tagName], exclusionRange);
+
+    if (newTagRanges.length) {
+      ret[tagName] = newTagRanges;
+      some = ret;
+    }
+  }
+
+  return some;
+}
+
+function excludeRangeCore(tags, exclusionRange) {
   const ret = [];
   const [exclusionStart, exclusionStop] = exclusionRange;
 
@@ -134,17 +404,18 @@ function atomicExclude(tags, exclusionRange) {
     const tagStop = tags[idx + 1];
 
     if (tagStop < exclusionStart) {
+      // exclusion is below - continue to check next range
       ret.push(tagStart, tagStop);
-      // exlusion is below - continue to check next range
       continue;
     }
 
     if (tagStart > exclusionStop) {
-      ret.push(...tags.slice(idx));
       // all other ranges are above exclusion so we can stop
+      ret.push(...tags.slice(idx));
       break;
     }
 
+    // this tag range overlaps the exclusion range
     if (exclusionStart <= tagStart && exclusionStop < tagStop) {
       ret.push(exclusionStop + 1, tagStop);
     }
@@ -161,122 +432,57 @@ function atomicExclude(tags, exclusionRange) {
   return ret;
 }
 
-function createAppendTags(firstTags, secondTags, offset) {
-  const ret = Object.create(null);
-  const firstTagsObject = ensureObject(firstTags);
-  const secondTagsObject = ensureObject(secondTags);
-  const tagNames = new Set([...Object.keys(firstTagsObject), ...Object.keys(secondTagsObject)]);
-
-  for (const tagName of tagNames) {
-    const newTagRanges = atomicAppend(ensureTagsImmutable(firstTagsObject, tagName), ensureTagsImmutable(secondTagsObject, tagName), offset);
-
-    newTagRanges.length && (ret[tagName] = newTagRanges);
-  }
-
-  return Object.keys(ret).length ? ret : null;
-}
-
-function createOverlappingTags(tags, startIndex, endIndex) {
-  const overlappingTags = {};
-
-  Object.entries(tags).forEach(([tag, tagRanges]) => {
-    const overlappingRanges = [];
-
-    for (let i = 0; i < tagRanges.length; i += 2) {
-      const start = tagRanges[i];
-      const end = tagRanges[i + 1];
-
-      if (end >= startIndex && start <= endIndex) {
-        overlappingRanges.push([start, end]);
-      }
-    }
-
-    if (overlappingRanges.length > 0) {
-      overlappingTags[tag] = overlappingRanges;
-    }
-  });
-
-  return overlappingTags;
-}
-
 /**
- * assumes:
- *  - no mutation of arguments
- *  - input ranges will be in non-decreasing order
- *  - input ranges are "merged"
- *      i.e. no ranges are adjacent
- *      i.e. [0, 0, 1, 1] should be [0, 1]
- *  - return ranges will be merged and in non-decreasing order
-*/
-function createSubsetTags(tags, subsetStart, len) {
-  const ret = Object.create(null);
-
-  for (const tagName of Object.keys(ensureObject(tags))) {
-    const newTagRanges = atomicSubset(ensureTagsImmutable(tags, tagName), subsetStart, len);
-
-    newTagRanges.length && (ret[tagName] = newTagRanges);
-  }
-
-  return Object.keys(ret).length ? ret : null;
-}
-
-function createFullLengthCopyTags(tags, resultLength) {
-  if (!resultLength || resultLength <= 0) return null;
-  const ret = Object.create(null);
-
-  for (const tagName of Object.keys(ensureObject(tags))) {
-    ret[tagName] = [0, resultLength - 1];
-  }
-
-  return Object.keys(ret).length ? ret : null;
-}
-
-function createMergedTags(firstTags, secondTags) {
-  const ret = Object.create(null);
-  const firstTagsObject = ensureObject(firstTags);
-  const secondTagsObject = ensureObject(secondTags);
-  const tagNames = new Set([...Object.keys(firstTagsObject), ...Object.keys(secondTagsObject)]);
-
-  for (const tagName of tagNames) {
-    const newTagRanges = atomicMerge(ensureTagsImmutable(firstTagsObject, tagName), ensureTagsImmutable(secondTagsObject, tagName));
-
-    newTagRanges.length && (ret[tagName] = newTagRanges);
-  }
-
-  return Object.keys(ret).length ? ret : null;
-}
-
-function createTagsWithExclusion(tags, exclusionRange) {
-  if (!exclusionRange.length) return;
-
-  const ret = Object.create(null);
-  const tagsObject = ensureObject(tags);
-
-  for (const tagName of Object.keys(tagsObject)) {
-    const newTagRanges = atomicExclude(ensureTagsImmutable(tagsObject, tagName), exclusionRange);
-
-    newTagRanges.length && (ret[tagName] = newTagRanges);
-  }
-
-  return Object.keys(ret).length ? ret : null;
-}
-
+ * Create tags for strings inserted into mongo queries.
+ * It also appears in vm but that is not evaluated during testing.
+ *
+ * @param {array | ?} path sequence of keys
+ * @param {object} tags tags to adjust. They refer to the user input.
+ * @param {string} value the user input
+ * @param {string} argString string incorporating the user input. The tag ranges
+ *       in the returned tags refer to this string.
+ *
+ * @returns {object} new tags or null if no tags
+ *
+ * @examples
+ * - ["query"],{"UNTRUSTED":[0,2]},"foo","{ query: 'foo' }" => {"UNTRUSTED":[10,12]}
+ * - ["val"],{"UNTRUSTED":[0,3],"CUSTOM_VALIDATED":[0,3]},"SAFE","{ val: 'SAFE' }" => {"UNTRUSTED":[8,11],"CUSTOM_VALIDATED":[8,11]}
+ *
+ */
 function createAdjustedQueryTags(path, tags, value, argString) {
   let idx = -1;
   for (const str of [...path, value]) {
-    // This is the case where the argument is an array
+    // This is the case where the input is an array
     if (str === 0) continue;
 
     idx = argString.indexOf(str, idx);
-    if (idx == -1) {
+    if (idx < 0) {
       idx = -1;
       break;
     }
   }
 
-  return idx > 0 ? createAppendTags([], tags, idx) : [...tags];
+  return idx >= 0 ? createAppendTags([], tags, idx) : [...tags];
 }
 
+/**
+ * Adjust tag ranges for escaped characters in original text. This typically
+ * involves splitting a tag range into multiple ranges. I'm not sure this is
+ * particularly useful, because the "vulnerable" text has been escaped so, even
+ * if the original text is present it's unlikely to be vulnerable.
+ *
+ * @param {string} input original text
+ * @param {string} result escaped text
+ * @param {object} tags tags to adjust by removing escaped characters from
+ *       the tag ranges.
+ *
+ * @returns {object} new tags
+ *
+ * @examples (args => return)
+ * - "foo","bar",{"untrusted":[0,2]} => [] // wtf?
+ * - "<foo>","&lt;foo&gt;",{"untrusted":[1,3]} => {"untrusted":[4,6]}
+ * - "?test=str","%3Ftest%3Dstr",{"UNTRUSTED":[0,8]} => {"UNTRUSTED":[3,6,10,12]}
+ */
 function createEscapeTagRanges(input, result, tags) {
   const inputArr = input.split('');
   const escapedArr = result.split('');
@@ -285,8 +491,10 @@ function createEscapeTagRanges(input, result, tags) {
       return x;
     }
   });
+  const ret = Object.create(null);
+
   if (overlap.length === 0) {
-    return [];
+    return ret;
   }
   const newTagRanges = [];
   let firstIndex = escapedArr.indexOf(overlap[0]);
@@ -304,13 +512,14 @@ function createEscapeTagRanges(input, result, tags) {
     currIndex = nextIndex;
   }
 
-  const ret = Object.create(null);
   for (const tagName of Object.keys(tags)) {
     ret[tagName] = newTagRanges;
   }
+
   return ret;
 }
 
+
 module.exports = {
   createSubsetTags,
   createAppendTags,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/assess",
-  "version": "1.20.2",
+  "version": "1.21.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,7 +17,7 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.16.1",
+    "@contrast/common": "1.17.0",
     "@contrast/distringuish": "^4.4.0",
     "@contrast/scopes": "1.4.0"
   }