@contrast/protect 1.0.1

package/lib/input-analysis/handlers.js

@@ -0,0 +1,462 @@
+'use strict';
+
+const { simpleTraverse } = require('../utils');
+
+//
+// these rules are not implemented by agent-lib, but are being considered for
+// implementation:
+// - semantic SQL injection: chaining, dangerous functions, suspicious unions, tautologies
+// - malformed header
+//
+// the following rules are out-of-scope for agent-lib and should be implemented in
+// the agent:
+// - cmd-injection-backdoors (simple indexing)
+// - expression-language-injection (java specific)
+// - method-tampering
+// - ReDOS (java specific)
+// - untrusted-deserialization (agent/framework specific)
+// - xxe (agent/framework specific)
+//
+// of the rules not implemented by agent-lib, only method-tampering and xxe check
+// input and make a decision immediately (i.e., there is no sink). so these two
+// rules will need to be implemented by the agent and called from these handlers.
+
+
+// agent-lib treats each type of nosql database as a separate
+// rule. they are all mapped to 'nosql-injection' in the agent.
+// maybe this will need to change.
+const agentLibRuleTypeToName = {
+  'nosql-injection-mongo': 'nosql-injection'
+};
+
+const preferWW = { preferWorthWatching: true };
+
+module.exports = function(core) {
+  const {
+    logger,
+    protect: {
+      agentLib,
+      inputAnalysis,
+    },
+  } = core;
+
+  // all handlers will be invoked with two arguments:
+  // 1) sourceContext object containing:
+  //   - reqData, the abstract request object containing only what is needed
+  //   - protect, the protect context
+  //     - rules, exclusions, virtual patches (TS data). what was in effect for this
+  //       url *at the time the request was started*. these will not change.
+  //     - block(), function that executes block for this specific request
+  //     - findings{}, consolidated collection of findings returned by score functions
+  //       and augmented with disposition and additional information as needed.
+  // 2) input or inputs specific to that handler
+  //
+  // exclusions
+  // - url exclusions are applied at the level above the connect handler, if no rules
+  //   are applicable to a given URL then it's not processed in any way by handlers.
+  // - input exclusions are applied **after** analysis. The rationale is that checking
+  //   inputs against rules 1) is very fast and 2) dramatically pares down the number
+  //   of exclusion checks that need to be made.
+
+  /**
+   * handleConnect()
+   *
+   * handle the inputs that are available when the HTTP 'request' event is emitted.
+   *
+   * this should *always* be the first handler called; it does setup that other
+   * handlers require.
+   *
+   * the specific data that is available to be processed at this time:
+   * - URI
+   * - queries
+   * - url params
+   * - headers (should exclude cookies header)
+   * - cookies (special handling of the header)
+   *
+   * but it really only makes sense to process:
+   * - URI
+   * - headers except cookies
+   *
+   * why? because the query string will (probably) be interpreted by the framework using
+   * 'qs' and that could result in creating an array or an object instead of a simple text
+   * value. and the cookies need to be parsed into individual cookies by the framework so
+   * that our code doesn't have to guess at the format, encoding, and other permutations.
+   * and for url params - only the framework knows that a portion of the url is a param.
+   *
+   * if it is known that 'qs' is not being used, then passing the query string in the
+   * 'connectInputs' makes sense; a flag similar to 'contentType' can be set and it can be
+   * used later to avoid calling 'handleQueryParams()'
+   *
+   * @param {Object} sourceContext { reqData, protect } that will be supplied to
+   *   all handlers and sinks for this request. It will always be supplied by the caller
+   *   to a handler; the handler is not aware of the implementation.
+   * @param {Object} connectInputs each property is an input to be evaluated by this
+   *   handler.
+   * @returns {undefined|[String]} undefined to permit else [mode, rule] to block.
+   */
+  inputAnalysis.handleConnect = function handleConnect(sourceContext, connectInputs) {
+    const { rules: { agentLibRules, agentLibRulesMask: mask } } = sourceContext;
+
+    // initialize findings to the basics
+    let block = undefined;
+    if (mask !== 0) {
+      const findings = agentLib.scoreRequestConnect(mask, connectInputs, preferWW);
+      block = mergeFindings(agentLibRules, sourceContext.findings, findings);
+    }
+
+    return block;
+  };
+
+  // this is called before the request goes away. this is where probe detection takes
+  // place. basically loop through findings.resultsList and, for all those that weren't
+  // blocked, run scoreAtom() with preferWorthWatching: false. for any that have a score
+  // >= 90 report them as probes.
+  inputAnalysis.handleRequestEnd = function handleRequestEnd(sourceContext) {
+    throw new Error('nyi', sourceContext);
+  };
+
+
+  const jsonInputTypes = {
+    keyType: agentLib.InputType.JsonKey, valueType: agentLib.InputType.JsonValue
+  };
+  const parameterInputTypes = {
+    keyType: agentLib.InputType.ParameterKey, valueType: agentLib.InputType.ParameterValue
+  };
+
+  /**
+   * handleQueryParams()
+   *
+   * If all values are strings there there is no need to re-evaluate them; that was
+   * done on requestConnect. But some frameworks use packages like 'qs' to parse the
+   * search params, which is non-standard and has many options including changing the
+   * delimiters and the ability to create the equivalent of JSON from the search params
+   * string. If any of the values are not strings then they need to be evaluated here;
+   * these results replace the results generated at requestConnect.
+   *
+   * If it is known that 'qs' is being used then it is better not to have passed the
+   * querystring to scoreRequestConnect().
+   *
+   * @param {Object} sourceContext
+   * @param {Object} queryParams pojo {key: value, ...} for all query params/search params
+   */
+  inputAnalysis.handleQueryParams = function handleQueryParams(sourceContext, queryParams) {
+    if (typeof queryParams !== 'object') {
+      logger.debug({ queryParams }, 'handleQueryParams() called with non-object');
+      return;
+    }
+    commonObjectAnalyzer(sourceContext, queryParams, parameterInputTypes);
+  };
+
+  /**
+   * handleUrlParams()
+   *
+   * Invoked when a framework emits URL params. It is similar to handling queryParams
+   * except no finding for URL params can be present.
+   *
+   * @param {Object} sourceContext
+   * @param {Object} urlParams pojo
+   */
+  inputAnalysis.handleUrlParams = function(sourceContext, urlParams) {
+    if (typeof urlParams !== 'object') {
+      logger.debug({ urlParams }, 'handleUrlParams() called with non-object');
+      return;
+    }
+
+    const { rules, rules: { agentLibRulesMask: mask } } = sourceContext;
+    const resultsList = [];
+    const { UrlParameter } = agentLib.InputType;
+
+    simpleTraverse(urlParams, function(path, type, value) {
+      // url param names are not checked.
+      if (type !== 'Value') {
+        return;
+      }
+      const items = agentLib.scoreAtom(mask, value, UrlParameter, preferWW);
+      if (!items) {
+        return;
+      }
+      for (const item of items) {
+        resultsList.push({
+          ruleId: item.ruleId,
+          inputType: 'UrlParameter',
+          path: path.slice(),
+          key: path.pop(), // there should always be at least the param name
+          value,
+          score: item.score,
+          idsList: [],
+        });
+      }
+    });
+
+    // if nothing was found then nothing needs to be done.
+    if (resultsList.length === 0) {
+      return;
+    }
+
+    // something was found, so create "complete" findings.
+    const urlParamsFindings = {
+      trackRequest: true,
+      securityException: undefined,
+      resultsList,
+    };
+    const block = mergeFindings(rules.agentLibRules, sourceContext.findings, urlParamsFindings);
+
+    if (block) {
+      sourceContext.block(...block);
+    }
+  };
+
+  /**
+   * handleCookies()
+   *
+   * Invoked when a framework emits cookies. It is similar to handling queryParams except
+   * no findings for cookies can be present.
+   * @param {Object} sourceContext
+   * @param {Object} cookies pojo
+   */
+  inputAnalysis.handleCookies = function(sourceContext, cookies) {
+    const cookiesArr = Object.entries(cookies).reduce((acc, [key, value]) => {
+      acc.push(key, value);
+      return acc;
+    }, []);
+    const { rules, rules: { agentLibRulesMask: mask } } = sourceContext;
+    const cookieFindings = agentLib.scoreRequestConnect(mask, { cookies: cookiesArr }, preferWW);
+
+    const block = mergeFindings(rules.agentLibRules, sourceContext.findings, cookieFindings);
+
+    if (block) {
+      sourceContext.block(...block);
+    }
+  };
+
+  /**
+   * handleParsedBody() is called with the body after a framework has parsed
+   * the body. If the body was JSON then it may have already been scored by
+   * handleRawBody(); if it was, bodyType was set to 'json' and this code only
+   * converts the previous findings, using the parsed body.
+   *
+   * @param {Object} sourceContext
+   * @param {Object} parsedBody
+   */
+  inputAnalysis.handleParsedBody = function(sourceContext, parsedBody) {
+    if (typeof parsedBody !== 'object') {
+      logger.debug({ parsedBody }, 'handleParsedBody() called with non-object');
+      return;
+    }
+
+    let bodyType;
+    let inputTypes;
+    if (sourceContext.reqData.contentType.includes('/json')) {
+      bodyType = 'json';
+      inputTypes = jsonInputTypes;
+    } else {
+      bodyType = 'urlencoded';
+      inputTypes = parameterInputTypes;
+    }
+    commonObjectAnalyzer(sourceContext, parsedBody, inputTypes);
+    sourceContext.findings.bodyType = bodyType;
+  };
+
+  // was MULTIPART_NAME but maybe we should just call it what it is. it's kind
+  // of a dumb rule anyway. but maybe some code actually uses the name provided.
+  inputAnalysis.handleFileUploadName = function(sourceContext, name) {
+    throw new Error('nyi', sourceContext, name);
+  };
+
+
+  /**
+   * commonObjectAnalyzer() walks an object supplied by the end-user and checks
+   * it for vulnerabilities.
+   *
+   * This can cause the request to be blocked, depending on the mode and findings.
+   *
+   * @param {Object} sourceContext the sourceContext for the request
+   * @param {Object} object the object to analyze. It could be from any input
+   * source that can resolve to an object: x-www-form-urlencoded, JSON,
+   * query params.
+   * @param {Object} inputTypes is either jsonInputTypes or parameterInputTypes,
+   * both are defined above. They specify the input types to be used when evaluating
+   * the object.
+   * @returns undefined
+   */
+  function commonObjectAnalyzer(sourceContext, object, inputTypes) {
+    const { rules, rules: { agentLibRulesMask: mask } } = sourceContext;
+    // use inputTypes to set params...
+    const { keyType, valueType } = inputTypes;
+    const inputTypeStr = inputTypes === jsonInputTypes ? 'Json' : 'Parameter';
+    const { Where } = agentLib.MongoQueryType;
+    const resultsList = [];
+
+    // it's possible to optimize this if qs (or a similar package) is not loaded
+    // or if none of the values of queryParams are objects. a quick '.includes()'
+    // could be used to determine that. if none are objects then simpleTraverse()
+    // wouldn't be used, just a simple "for (const key in queryParams) {...}" to
+    // check each key and value associated with the key.
+    //
+    // otoh, it's a fair amount of additional logic and the gain is likely to be
+    // small, so it probably only makes sense to check if qs (or similar) is actually
+    // in use. a benchmark of "for (const key in queryParams) {...}" vs simpleTraverse
+    // should be created to see if, and in what cases, it makes sense.
+    //
+    // another day.
+
+    /* eslint-disable-next-line complexity */
+    simpleTraverse(object, function(path, type, value) {
+      let itemType;
+      let mongoQueryType;
+      // this is a bit awkward now because nosql-injection-mongo is not integrated
+      // into the scoreAtom() function (or the check_input() function it uses). as
+      // a result, the two rules need to be checked independently and the results
+      // merged, which is kind of a pia.
+      // TODO AGENT-205
+      if (type === 'Key') {
+        itemType = keyType;
+        if (mask & agentLib.RuleType['nosql-injection-mongo']) {
+          mongoQueryType = agentLib.getMongoQueryType(value);
+        }
+      } else {
+        itemType = valueType;
+      }
+      let items = agentLib.scoreAtom(mask, value, itemType, preferWW);
+      if (!items && !mongoQueryType) {
+        return;
+      }
+      if (!items) {
+        items = [];
+      }
+      let mongoPath;
+      // if the key was a mongo query key, then add it to the items. it requires
+      // that additional information is kept as well.
+      if (mongoQueryType) {
+        const inputToCheck = getValueAtKey(object, path, value);
+        // because scoreRequestConnect() returns the query type in the value, we
+        // mimic it here (where scoreAtom() was used). the actual object/string
+        // to match is stored as `inputToCheck`.
+        const inputType = typeof inputToCheck;
+        if ((mongoQueryType <= Where && inputType === 'object') || (mongoQueryType >= Where && inputType === 'string')) {
+          // the query-type/input-type combination is valid. add a synthesized item.
+          const item = { ruleId: 'nosql-injection-mongo', score: 10, mongoContext: { inputToCheck } };
+          items.push(item);
+        }
+      }
+      // make each item a complete Finding
+      for (const item of items) {
+        const result = {
+          ruleId: item.ruleId,
+          inputType: `${inputTypeStr}${type}`,
+          path: mongoPath || path.slice(),
+          key: type === 'Key' ? value : path[path.length - 1],
+          // mimic scoreRequestConnect() returning the query type as the value
+          value: mongoQueryType || value,
+          score: item.score,
+          idsList: [],
+        };
+        if (item.mongoContext) {
+          result.mongoContext = item.mongoContext;
+        }
+        resultsList.push(result);
+      }
+    });
+
+    // if nothing was found then nothing needs to be done.
+    if (resultsList.length === 0) {
+      return;
+    }
+
+    // something was found, so create "complete" findings.
+    const findings = {
+      trackRequest: true,
+      securityException: undefined,
+      resultsList,
+    };
+
+    const block = mergeFindings(rules.agentLibRules, sourceContext.findings, findings);
+    if (block) {
+      sourceContext.block(...block);
+    }
+  }
+};
+
+/**
+ * merge new findings into the existing findings
+ *
+ * @param {Object} sourceContext sourceContext.findings is the existing findings
+ * @param {Object} newFindings the findings, in {trackRequest, resultsList} format.
+ * @returns {undefined|[String]} undefined to permit else [mode, rule] to block.
+ */
+function mergeFindings(rules, findings, newFindings) {
+  if (!newFindings.trackRequest) {
+    return findings.securityException;
+  }
+  normalizeFindings(rules, newFindings);
+
+  findings.trackRequest = findings.trackRequest || newFindings.trackRequest;
+  findings.securityException = findings.securityException || newFindings.securityException;
+
+  // merge them into a ruleId-indexed map (pojo)
+  for (const result of newFindings.resultsList) {
+    if (!findings.resultsMap[result.ruleId]) {
+      findings.resultsMap[result.ruleId] = [];
+    }
+    findings.resultsMap[result.ruleId].push(result);
+  }
+
+  return findings.securityException;
+}
+
+//
+// add common fields to findings.
+//
+function normalizeFindings(rules, findings) {
+  // now both augment the rules and check to see if any require blocking
+  // at perimeter.
+  for (const r of findings.resultsList) {
+    // augment
+    // what additional augmentations are needed?
+    // the name/id might need to be mapped but keep the original so it's not lost
+    r.mappedId = agentLibRuleTypeToName[r.ruleId] || r.ruleId;
+    // this finding resulted in blocking, i.e., it is not a probe.
+    r.blocked = false;
+
+    // sink analysis will add findings here
+    r.details = [];
+
+    // apply exclusions here.
+    //
+    // apply exclusions after scoring inputs as it will require less work
+    // most of the time.
+    //
+    // the following might need to be changed. BAP is legacy behavior; beyond that,
+    // the only way a score >= 90 can come back is if there is no "worth-watching"
+    // option and that implies that there is no sink, so this is the only place at
+    // which the block can occur. so at a minimum 'block' should also result in a
+    // block.
+    const { mode } = rules[r.ruleId];
+    if (r.score >= 90 && ['block', 'block_at_perimeter'].includes(mode)) {
+      r.blocked = true;
+      findings.securityException = [mode, r.ruleId];
+    }
+  }
+}
+
+/**
+ * getValueAtKey() is used to fetch the object (expected) associated
+ * with the path of keys in obj. i say expected because this is only used
+ * for fetching the objects associated with a nosql vulnerability and those
+ * should always be objects.
+ *
+ * @param {Object} obj an object with keys
+ * @param {Array} path list of keys to walk through the object
+ * @param {String} lastKey the last key (it's not in path)
+ *
+ * @returns the value at end of walking path in obj
+ */
+function getValueAtKey(obj, path, key) {
+  for (const p of path) {
+    if (!(p in obj)) {
+      return undefined;
+    }
+    obj = obj[p];
+  }
+  return key in obj ? obj[key] : undefined;
+}