@contrast/protect 1.7.0 → 1.8.0

package/lib/input-analysis/handlers.js

@@ -15,7 +15,13 @@
 
 'use strict';
 
-const { BLOCKING_MODES, simpleTraverse, Rule, isString } = require('@contrast/common');
+const {
+  BLOCKING_MODES,
+  simpleTraverse,
+  Rule,
+  isString,
+  ProtectRuleMode: { OFF },
+} = require('@contrast/common');
 const address = require('ipaddr.js');
 
 //
@@ -57,6 +63,14 @@ module.exports = function(core) {
     config,
   } = core;
 
+  const jsonInputTypes = {
+    keyType: agentLib.InputType.JsonKey, inputType: agentLib.InputType.JsonValue
+  };
+
+  const parameterInputTypes = {
+    keyType: agentLib.InputType.ParameterKey, inputType: agentLib.InputType.ParameterValue
+  };
+
   // all handlers will be invoked with two arguments:
   // 1) sourceContext object containing:
   //   - reqData, the abstract request object containing only what is needed
@@ -112,8 +126,6 @@ module.exports = function(core) {
    * @returns {undefined|[String]} undefined to permit else [mode, rule] to block.
    */
   inputAnalysis.handleConnect = function handleConnect(sourceContext, connectInputs) {
-    if (!sourceContext || sourceContext.allowed) return;
-
     const { policy: { rulesMask } } = sourceContext;
 
     inputAnalysis.handleVirtualPatches(sourceContext, { URLS: connectInputs.rawUrl, HEADERS: connectInputs.headers });
@@ -122,84 +134,13 @@ module.exports = function(core) {
     let block = undefined;
     if (rulesMask !== 0) {
       const findings = agentLib.scoreRequestConnect(rulesMask, connectInputs, preferWW);
+
       block = mergeFindings(sourceContext, findings);
     }
 
     return block;
   };
 
-  /**
-   * handleRequestEnd()
-   *
-   * Invoked when the request is complete.
-   *
-   * @param {Object} sourceContext
-   */
-  inputAnalysis.handleRequestEnd = function handleRequestEnd(sourceContext) {
-    if (!config.protect.probe_analysis.enable) return;
-
-    const { resultsMap } = sourceContext.findings;
-    const probesRules = [Rule.CMD_INJECTION, Rule.PATH_TRAVERSAL, Rule.SQL_INJECTION, Rule.XXE];
-    const props = {};
-
-    // Detecting probes
-    Object.values(resultsMap).forEach(resultsByRuleId => {
-      resultsByRuleId.forEach((resultByRuleId) => {
-        const {
-          ruleId,
-          blocked,
-          details,
-          value,
-          inputType
-        } = resultByRuleId;
-        if (blocked || !blocked && details.length > 0 || !probesRules.some(rule => rule === ruleId)) return;
-
-        const { policy: { rulesMask } } = sourceContext;
-
-        const results = (agentLib.scoreAtom(
-          rulesMask,
-          value,
-          agentLib.InputType[inputType],
-          {
-            preferWorthWatching: false
-          }
-        ) || []).filter(({ score }) => score >= 90);
-
-        if (!results.length) return;
-
-        results.forEach(result => {
-          const isAlreadyBlocked = (resultsMap[result.ruleId] || []).some(element =>
-            element.blocked && element.inputType === inputType && element.value === value
-          );
-
-          if (isAlreadyBlocked) return;
-
-          const probe = Object.assign({}, resultByRuleId, result, {
-            mappedId: result.ruleId
-          });
-          const key = [probe.ruleId, probe.inputType, ...probe.path, probe.value].join('|');
-          props[key] = probe;
-        });
-      });
-    });
-
-    Object.values(props).forEach(prop => {
-      if (!resultsMap[prop.ruleId]) {
-        resultsMap[prop.ruleId] = [];
-      }
-
-      resultsMap[prop.ruleId].push(prop);
-    });
-  };
-
-  const jsonInputTypes = {
-    keyType: agentLib.InputType.JsonKey, inputType: agentLib.InputType.JsonValue
-  };
-
-  const parameterInputTypes = {
-    keyType: agentLib.InputType.ParameterKey, inputType: agentLib.InputType.ParameterValue
-  };
-
   /**
    * handleQueryParams()
    *
@@ -225,7 +166,6 @@ module.exports = function(core) {
       return;
     }
 
-
     inputAnalysis.handleVirtualPatches(sourceContext, { PARAMETERS: queryParams });
 
     const block = commonObjectAnalyzer(sourceContext, queryParams, parameterInputTypes);
@@ -264,10 +204,13 @@ module.exports = function(core) {
       if (type !== 'Value') {
         return;
       }
+
       const items = agentLib.scoreAtom(rulesMask, value, UrlParameter, preferWW);
+
       if (!items) {
         return;
       }
+
       for (const item of items) {
         resultsList.push({
           ruleId: item.ruleId,
@@ -312,14 +255,15 @@ module.exports = function(core) {
     if (sourceContext.analyzedCookies) return;
     sourceContext.analyzedCookies = true;
 
+    inputAnalysis.handleVirtualPatches(sourceContext, { HEADERS: cookies });
+
+    const { policy: { rulesMask } } = sourceContext;
+
     const cookiesArr = Object.entries(cookies).reduce((acc, [key, value]) => {
       acc.push(key, value);
       return acc;
     }, []);
 
-    inputAnalysis.handleVirtualPatches(sourceContext, { HEADERS: cookies });
-
-    const { policy: { rulesMask } } = sourceContext;
     const cookieFindings = agentLib.scoreRequestConnect(rulesMask, { cookies: cookiesArr }, preferWW);
 
     const block = mergeFindings(sourceContext, cookieFindings);
@@ -340,6 +284,7 @@ module.exports = function(core) {
    */
   inputAnalysis.handleParsedBody = function(sourceContext, parsedBody) {
     if (sourceContext.analyzedBody) return;
+
     sourceContext.analyzedBody = true;
 
     if (typeof parsedBody !== 'object') {
@@ -358,6 +303,7 @@ module.exports = function(core) {
       bodyType = 'urlencoded';
       inputTypes = parameterInputTypes;
     }
+
     const block = commonObjectAnalyzer(sourceContext, parsedBody, inputTypes);
 
     sourceContext.findings.bodyType = bodyType;
@@ -478,6 +424,70 @@ module.exports = function(core) {
     }
   };
 
+  /**
+   * handleRequestEnd()
+   *
+   * Invoked when the request is complete.
+   *
+   * @param {Object} sourceContext
+   */
+  inputAnalysis.handleRequestEnd = function handleRequestEnd(sourceContext) {
+    if (!config.protect.probe_analysis.enable || sourceContext.allowed) return;
+
+    const { resultsMap } = sourceContext.findings;
+    const probesRules = [Rule.CMD_INJECTION, Rule.PATH_TRAVERSAL, Rule.SQL_INJECTION, Rule.XXE];
+    const props = {};
+
+    // Detecting probes
+    Object.values(resultsMap).forEach(resultsByRuleId => {
+      resultsByRuleId.forEach((resultByRuleId) => {
+        const {
+          ruleId,
+          blocked,
+          details,
+          value,
+          inputType
+        } = resultByRuleId;
+        if (blocked || !blocked && details.length > 0 || !probesRules.some(rule => rule === ruleId)) return;
+
+        const { policy: { rulesMask } } = sourceContext;
+
+        const results = (agentLib.scoreAtom(
+          rulesMask,
+          value,
+          agentLib.InputType[inputType],
+          {
+            preferWorthWatching: false
+          }
+        ) || []).filter(({ score }) => score >= 90);
+
+        if (!results.length) return;
+
+        results.forEach(result => {
+          const isAlreadyBlocked = (resultsMap[result.ruleId] || []).some(element =>
+            element.blocked && element.inputType === inputType && element.value === value
+          );
+
+          if (isAlreadyBlocked) return;
+
+          const probe = Object.assign({}, resultByRuleId, result, {
+            mappedId: result.ruleId
+          });
+          const key = [probe.ruleId, probe.inputType, ...probe.path, probe.value].join('|');
+          props[key] = probe;
+        });
+      });
+    });
+
+    Object.values(props).forEach(prop => {
+      if (!resultsMap[prop.ruleId]) {
+        resultsMap[prop.ruleId] = [];
+      }
+
+      resultsMap[prop.ruleId].push(prop);
+    });
+  };
+
   /**
    * commonObjectAnalyzer() walks an object supplied by the end-user and checks
    * it for vulnerabilities.
@@ -532,7 +542,9 @@ module.exports = function(core) {
       } else {
         itemType = inputType;
       }
+
       let items = agentLib.scoreAtom(rulesMask, value, itemType, preferWW);
+
       if (!items && !isMongoQueryType) {
         return;
       }
@@ -628,6 +640,66 @@ module.exports = function(core) {
   }
 };
 
+/**
+ * Reads the source context's policy and compares to result item to check whether to ignore it.
+ * @param {ProtectMessage} sourceContext
+ * @param {Result} result
+ * @returns {boolean} whether result should be excluded
+ */
+function isResultExcluded(sourceContext, result) {
+  const { policy: { exclusions } } = sourceContext;
+  const { ruleId, path, inputType, value } = result;
+  const inputName = path ? path[path.length - 1] : null;
+
+  let checkCookiesInHeader = false;
+  let inputExclusions;
+  switch (inputType) {
+    case 'JsonKey':
+    case 'JsonValue':
+    case 'MultipartName': {
+      return exclusions.ignoreBody || exclusions.bodyPolicy?.[ruleId] === OFF;
+    }
+    case 'ParameterKey':
+    case 'ParameterValue': {
+      const qsExcluded = exclusions.ignoreQuerystring || exclusions.querystringPolicy?.[ruleId] === OFF;
+      if (qsExcluded) return true;
+      inputExclusions = exclusions.parameter;
+      break;
+    }
+    case 'CookieValue': {
+      inputExclusions = exclusions.cookie;
+      break;
+    }
+    case 'HeaderKey':
+    case 'HeaderValue': {
+      if (path?.[0]?.toLowerCase() === 'cookie') {
+        inputExclusions = exclusions.cookie;
+        checkCookiesInHeader = true;
+      } else {
+        inputExclusions = exclusions.header;
+      }
+      break;
+    }
+  }
+
+  if (!inputName || !inputExclusions) return false;
+
+  for (const excl of inputExclusions) {
+    let nameCheck = false;
+    if (checkCookiesInHeader) {
+      nameCheck = excl.checkCookiesInHeader(value);
+    } else {
+      nameCheck = excl.matchesInputName(inputName);
+    }
+    if (!nameCheck) continue;
+    if (!excl.policy || excl.policy[ruleId] === OFF) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * merge new findings into the existing findings
  *
@@ -641,6 +713,11 @@ function mergeFindings(sourceContext, newFindings) {
   if (!newFindings.trackRequest) {
     return findings.securityException;
   }
+
+  newFindings.resultsList = newFindings.resultsList.filter(
+    (result) => !isResultExcluded(sourceContext, result)
+  );
+
   normalizeFindings(policy, newFindings);
 
   findings.trackRequest = findings.trackRequest || newFindings.trackRequest;

package/lib/input-analysis/install/http.js

@@ -176,8 +176,13 @@ class HttpInstrumentation {
         setImmediate(() => method.call(instance, ...args));
         return;
       }
-
       store.protect = this.makeSourceContext(req, res);
+
+      if (store.protect.allowed) {
+        setImmediate(() => method.call(instance, ...args));
+        return;
+      }
+
       const { reqData } = store.protect;
 
       res.on('finish', () => {

package/lib/input-analysis/virtual-patches.js

@@ -26,7 +26,7 @@ module.exports = (core) => {
   const virtualPatchesEvaluators = inputAnalysis.virtualPatchesEvaluators = [];
 
   messages.on(Event.SERVER_SETTINGS_UPDATE, (serverUpdate) => {
-    const virtualPatches = serverUpdate.settings?.defend.virtualPatches;
+    const virtualPatches = serverUpdate.settings?.defend?.virtualPatches;
     if (virtualPatches) {
       buildVPEvaluators(virtualPatches, virtualPatchesEvaluators);
     }

package/lib/make-source-context.js

@@ -16,7 +16,9 @@
 'use strict';
 
 module.exports = function(core) {
-  const { protect } = core;
+  const {
+    protect: { getPolicy }
+  } = core;
 
   function makeSourceContext(req, res) {
     // make the abstract request. it is an abstraction of a request that
@@ -27,8 +29,10 @@ module.exports = function(core) {
     // or res objects so that all data coupling is all defined here.
 
     // separate path and search params
-    const ix = req.url.indexOf('?');
+
     let uriPath, queries;
+    const ix = req.url.indexOf('?');
+
     if (ix >= 0) {
       uriPath = req.url.slice(0, ix);
       queries = req.url.slice(ix + 1);
@@ -36,6 +40,14 @@ module.exports = function(core) {
       uriPath = req.url;
       queries = '';
     }
+
+    const policy = getPolicy({ uriPath });
+
+    // URL exclusions can disable all rules
+    if (!policy) {
+      return { allowed: true };
+    }
+
     // lowercase header keys and capture content-type
     let contentType = '';
     const headers = Array(req.rawHeaders.length);
@@ -80,7 +92,7 @@ module.exports = function(core) {
       // block closure captures res so it isn't exposed to beyond here
       block: core.protect.makeResponseBlocker(res),
 
-      policy: protect.getPolicy(),
+      policy,
 
       exclusions: [],
       virtualPatchesEvaluators: [],

package/lib/policy.js

@@ -27,14 +27,72 @@ const {
   Event: { SERVER_SETTINGS_UPDATE },
 } = require('@contrast/common');
 
-
 module.exports = function(core) {
-  const { config, logger, messages, protect } = core;
-  const policy = protect.policy = {};
+  const {
+    config,
+    logger,
+    messages,
+    protect,
+    protect: { agentLib }
+  } = core;
+
+  const compiled = {
+    url: [],
+    querystring: [],
+    header: [],
+    body: [],
+    cookie: [],
+    parameter: [],
+  };
+
+  const policy = protect.policy = {
+    exclusions: compiled
+  };
+
+  function regExpCheck(str) {
+    return str.indexOf('*') > 0 ||
+      str.indexOf('.') > 0 ||
+      str.indexOf('+') > 0 ||
+      str.indexOf('?') > 0 ||
+      str.indexOf('\\') > 0;
+  }
+
+  function buildUriPathRegExp(urls) {
+    let regExpNeeded = false;
+    for (const url of urls) {
+      if (regExpCheck(url)) {
+        regExpNeeded = true;
+      }
+    }
+    if (regExpNeeded) {
+      const rx = new RegExp(`^${urls.join('|')}$`);
+
+      return (uriPath) => rx ? rx.test(uriPath) : false;
+    }
+
+    return (uriPath) => urls.some((url) => url === uriPath);
+  }
+
+  function createUriPathMatcher(urls) {
+    if (urls.length) {
+      return buildUriPathRegExp(urls);
+    } else {
+      return () => true;
+    }
+  }
+
+  function createInputNameMatcher(dtmInputName) {
+    if (regExpCheck(dtmInputName)) {
+      const rx = new RegExp(`^${dtmInputName}$`);
+      return (inputName) => rx ? rx.test(inputName) : false;
+    }
+
+    return (inputName) => inputName === dtmInputName;
+  }
 
   function getModeFromConfig(ruleId) {
     if (config.protect.disabled_rules.includes(ruleId)) {
-      return 'off';
+      return OFF;
     }
     return config.protect.rules?.[ruleId]?.mode;
   }
@@ -84,11 +142,20 @@ module.exports = function(core) {
    */
   function updateRulesMask() {
     let rulesMask = 0;
-    for (const [ruleId, mode] of Object.entries(policy)) {
+
+    for (const entry of Object.entries(policy)) {
+      let [ruleId] = entry;
+      const [, mode] = entry;
+
+      if (ruleId === 'nosql-injection') {
+        ruleId = 'nosql-injection-mongo';
+      }
+
       if (protect.agentLib.RuleType[ruleId] && mode !== OFF) {
         rulesMask = rulesMask | protect.agentLib.RuleType[ruleId];
       }
     }
+
     policy.rulesMask = rulesMask;
   }
 
@@ -96,13 +163,83 @@ module.exports = function(core) {
    * This gets called by protect.makeSourceContext(). We return copy of policy to avoid
    * inconsistent behavior if policy is updated during request handling.
    */
-  function getPolicy() {
-    return { ...policy };
-  }
+  function getPolicy({ uriPath } = {}) {
+    const requestPolicy = {
+      exclusions: {
+        ignoreQuerystring: false,
+        querystringPolicy: null,
+        ignoreBody: false,
+        bodyPolicy: null,
+        header: [],
+        cookie: [],
+        parameter: [],
+      },
+      rulesMask: policy.rulesMask,
+    };
 
-  initPolicy();
+    for (const ruleId of Object.values(Rule)) {
+      requestPolicy[ruleId] = policy[ruleId];
+    }
 
-  messages.on(SERVER_SETTINGS_UPDATE, (remoteSettings) => {
+    // handle exclusions
+    for (const [inputType, exclusions] of Object.entries(compiled)) {
+      for (const e of exclusions) {
+        if (!e.matchesUriPath(uriPath)) continue;
+
+        // url exclusions
+        if (inputType === 'url') {
+          // if applies to all rules, there is no policy for the request i.e. disable protect
+          if (!e.policy) {
+            return null;
+          }
+
+          // merge exclusion's policy into the request's policy
+          for (const key of Object.keys(e.policy)) {
+            const value = e.policy[key];
+            if (key === 'rulesMask') {
+              // this is how to disable rules bitwise
+              requestPolicy.rulesMask = requestPolicy.rulesMask & ~value;
+            } else {
+              requestPolicy[key] = value;
+            }
+          }
+        } else if (inputType === 'querystring') {
+          if (!e.policy) {
+            requestPolicy.exclusions.ignoreQuerystring = true;
+          } else {
+            // merge exclusion's policy into the querystring's policy
+            requestPolicy.exclusions.querystringPolicy = requestPolicy.exclusions.querystringPolicy || {};
+            for (const key of Object.keys(e.policy)) {
+              const value = e.policy[key];
+              if (key !== 'rulesMask') {
+                requestPolicy.exclusions.querystringPolicy[key] = value;
+              }
+            }
+          }
+        } else if (inputType === 'body') {
+          if (!e.policy) {
+            requestPolicy.exclusions.ignoreBody = true;
+          } else {
+            // merge exclusion's policy into the querystring's policy
+            requestPolicy.exclusions.bodyPolicy = requestPolicy.exclusions.bodyPolicy || {};
+            for (const key of Object.keys(e.policy)) {
+              const value = e.policy[key];
+              if (key !== 'rulesMask') {
+                requestPolicy.exclusions.bodyPolicy[key] = value;
+              }
+            }
+          }
+        } else {
+          // copy matching input exclusions into request policy
+          requestPolicy.exclusions[inputType].push(e);
+        }
+      }
+    }
+
+    return requestPolicy;
+  }
+
+  function updateGlobalPolicy(remoteSettings) {
     let update;
 
     const protectionRules = remoteSettings?.settings?.defend?.protectionRules;
@@ -128,7 +265,79 @@ module.exports = function(core) {
       updateRulesMask();
       logger.info({ policy: protect.policy }, `protect policy updated from ${update}`);
     }
+  }
+
+  function updateExclusions(serverUpdate) {
+    const exclusions = [
+      ...(serverUpdate.settings?.exceptions?.inputExceptions || []),
+      ...(serverUpdate.settings?.exceptions?.urlExceptions || [])
+    ].filter((exclusion) => exclusion.modes.includes('defend'));
+
+    if (!exclusions.length) return;
+
+    for (const exclusionDtm of exclusions) {
+      exclusionDtm.inputType = exclusionDtm.inputType || 'URL';
+
+      const { name, rules, inputName, urls, inputType } = exclusionDtm;
+      const key = inputType.toLowerCase();
+
+      if (!compiled[key]) continue;
+
+      try {
+        const e = { name };
+        e.matchesUriPath = createUriPathMatcher(urls);
+
+        if (inputName) {
+          e.matchesInputName = createInputNameMatcher(inputName);
+        }
+
+        if (rules.length) {
+          let rulesMask = 0;
+          const exclusionPolicy = {};
+
+          for (let ruleId of rules) {
+            // todo: this doesn't seem to make a difference?
+            if (ruleId === 'nosql-injection') {
+              ruleId = 'nosql-injection-mongo';
+            }
+
+            if (agentLib.RuleType[ruleId]) {
+              Object.assign(exclusionPolicy, { [ruleId]: OFF });
+              if (inputType === 'URL') {
+                rulesMask = rulesMask | agentLib.RuleType[ruleId];
+                exclusionPolicy.rulesMask = rulesMask;
+              }
+            }
+          }
+
+          e.policy = exclusionPolicy;
+        }
+        if (key === 'cookie') {
+          e.checkCookieInHeader = (cookieHeader) => {
+            for (const cookiePair of cookieHeader.split(';')) {
+              const cookieKey = cookiePair.split('=')[0];
+              if (e.matchesInputName(cookieKey)) {
+                return true;
+              }
+            }
+
+            return false;
+          };
+        }
+
+        compiled[key].push(e);
+      } catch (err) {
+        logger.error({ err, exclusionDtm }, 'failed to process exclusion');
+      }
+    }
+  }
+
+  messages.on(SERVER_SETTINGS_UPDATE, (msg) => {
+    updateGlobalPolicy(msg);
+    updateExclusions(msg);
   });
 
+  initPolicy();
+
   return protect.getPolicy = getPolicy;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Contrast service providing framework-agnostic Protect support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",