@contrast/protect 1.3.0 → 1.5.0

package/lib/semantic-analysis/handlers.js

@@ -0,0 +1,161 @@
+/*
+ * 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 {
+  BLOCKING_MODES,
+  ProtectRuleMode: { OFF },
+  InputType,
+  isString,
+  simpleTraverse
+} = require('@contrast/common');
+
+const SINK_EXPLOIT_PATTERN_START = /(?:^|\\|\/)(?:sh|bash|zsh|ksh|tcsh|csh|fish|cmd)/;
+const stripWhiteSpace = (str) => str.replace(/\s/g, '');
+
+// The sink instrumentation for this rule is in `protect/lib/input-tracing/install/child-process.js
+module.exports = function(core) {
+  const { protect: { agentLib, semanticAnalysis, throwSecurityException } } = core;
+
+  function handleResult(sourceContext, sinkContext, ruleId, mode, finding) {
+    const sinkResults = sourceContext.findings.semanticResultsMap[ruleId];
+    const result = {
+      blocked: false,
+      findings: { command: sinkContext.value },
+      sinkContext,
+      ...finding
+    };
+
+    sourceContext.findings.semanticResultsMap[ruleId] = sinkResults ? [...sinkResults, result] : [result];
+
+    if (BLOCKING_MODES.includes(mode)) {
+      result.blocked = true;
+      const blockInfo = [mode, ruleId];
+      sourceContext.findings.securityException = blockInfo;
+      throwSecurityException(sourceContext);
+    }
+  }
+
+  semanticAnalysis.handleCmdInjectionSemanticDangerous = function(sourceContext, sinkContext) {
+    const ruleId = 'cmd-injection-semantic-dangerous-paths';
+    const mode = sourceContext.policy[ruleId];
+
+    if (mode == OFF) return;
+
+    const result = agentLib.containsDangerousPath(sinkContext.value);
+
+    if (result) {
+      handleResult(sourceContext, sinkContext, ruleId, mode);
+    }
+  };
+
+  semanticAnalysis.handleCmdInjectionSemanticChainedCommands = function(sourceContext, sinkContext) {
+    const ruleId = 'cmd-injection-semantic-chained-commands';
+    const mode = sourceContext.policy[ruleId];
+
+    if (mode == OFF) return;
+
+    const indexOfChaining = agentLib.indexOfChaining(sinkContext.value);
+
+    if (indexOfChaining != -1) {
+      handleResult(sourceContext, sinkContext, ruleId, mode);
+    }
+  };
+
+  semanticAnalysis.handleCommandInjectionCommandBackdoors = function(sourceContext, sinkContext) {
+    const ruleId = 'cmd-injection-command-backdoors';
+    const mode = sourceContext.policy[ruleId];
+
+    if (mode == OFF) return;
+
+    const finding = findBackdoorInjection(sourceContext, sinkContext.value);
+
+    if (finding) {
+      handleResult(sourceContext, sinkContext, ruleId, mode, finding);
+    }
+  };
+
+  return semanticAnalysis;
+};
+
+/**
+ * Backdoor detection logic:
+ *  - command is >= 2 chars
+ *  - iterates over every piece of request and checks
+ *    - the full value is the param to sink
+ *    - the value matches a regex and ends the param to the sink
+ */
+function findBackdoorInjection(sourceContext, command) {
+  if (command?.length < 2) {
+    return null;
+  }
+
+  const valuesOfInterest = {
+    [InputType.QUERYSTRING]: sourceContext.parsedQuery,
+    [InputType.PARAMETER_VALUE]: sourceContext.parsedParams,
+    [InputType.BODY]: sourceContext.parsedBody,
+    [InputType.COOKIE_VALUE]: sourceContext.parsedCookies,
+    [InputType.HEADER]: sourceContext.reqData.headers,
+  };
+
+  let found = false;
+  for (let inputType in valuesOfInterest) {
+    const values = valuesOfInterest[inputType];
+
+    if (values && Object.keys(values).length) {
+      simpleTraverse(values, (path, type, value, obj) => {
+        if (
+          !found &&
+            value &&
+            type === 'Value' &&
+            isString(value) &&
+            isBackdoorDetected(value, command)
+        ) {
+          let key;
+          key = inputType === InputType.HEADER ? obj.indexOf(command) - 1 : path[path.length - 1];
+          if (Number.isInteger(key) && obj[key]) {
+            key = obj[key];
+          }
+          path = path.length === 1 ? [] : Array.from(path).slice(0, path.length - 1);
+          inputType = path.length > 1 ? InputType.JSON_VALUE : inputType;
+
+          found = { key, inputType, path, value: command };
+        }
+      });
+    }
+  }
+
+  return found;
+}
+
+/**
+   * strips the whitespace of the request value and the command,
+   * checks if the command equals the request value
+   * or if the command looks like the start of a shell execution
+   * and ends with the request value passed to the sink
+   *
+   * @param {string} value from request key
+   */
+function isBackdoorDetected(requestValue, command) {
+  const normalizedValue = stripWhiteSpace(requestValue);
+  const normalizedCommand = stripWhiteSpace(command);
+
+  return (
+    normalizedValue === normalizedCommand ||
+      (normalizedCommand.endsWith(normalizedValue) &&
+        SINK_EXPLOIT_PATTERN_START.test(normalizedCommand))
+  );
+}

package/lib/semantic-analysis/index.js

@@ -0,0 +1,38 @@
+/*
+ * 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';
+
+/**
+ * SEMANTIC ANALYSIS is a STAGE of Protect.
+ * The information about it can be found under some of the separate rules we support for this stage:
+ * https://protect-spec.prod.dotnet.contsec.com/rules/cmd-injection-semantic-dangerous-paths.html#semantic-analysis
+ * https://protect-spec.prod.dotnet.contsec.com/rules/cmd-injection-semantic-chained-commands.html#semantic-analysis
+ *
+ * To view other STAGES see https://protect-spec.prod.dotnet.contsec.com/guide/protect-types.html#protection-types
+ * @param {object} core composed dependencies
+ * @returns {object}
+ */
+module.exports = function(core) {
+  const semanticAnalysis = core.protect.semanticAnalysis = {};
+
+  // load the interfaces that will be used by input tracing instrumentation
+  require('./handlers')(core);
+
+  // There is no `.install()` method as this STAGE does not introduce side effects on its own,
+  // it uses the instrumentation that's already in place for INPUT TRACING.
+
+  return semanticAnalysis;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Contrast service providing framework-agnostic Protect support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -9,9 +9,6 @@
   ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
-  "bin": {
-    "contrast-transpile": "lib/cli-rewriter.js"
-  },
   "engines": {
     "npm": ">= 8.4.0",
     "node": ">= 14.15.0"
@@ -22,12 +19,13 @@
   "dependencies": {
     "@babel/template": "^7.16.7",
     "@babel/types": "^7.16.8",
-    "@contrast/agent-lib": "^4.2.0",
-    "@contrast/common": "1.0.3",
-    "@contrast/core": "1.2.0",
-    "@contrast/scopes": "1.1.0",
-    "@contrast/esm-hooks": "1.1.3",
+    "@contrast/agent-lib": "^5.1.0",
+    "@contrast/common": "1.1.1",
+    "@contrast/core": "1.4.0",
+    "@contrast/esm-hooks": "1.1.5",
+    "@contrast/scopes": "1.1.1",
     "builtin-modules": "^3.2.0",
+    "ipaddr.js": "^2.0.1",
     "semver": "^7.3.7"
   }
 }

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

@@ -1,107 +0,0 @@
-/*
- * 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 { patchType } = require('../constants');
-const { isSecurityException } = require('../../security-exception');
-
-/**
- * Function that exports an install method to patch Fastify framework with our instrumentation
- * @param {Object} core - the core Contrast object in v5
- * @return {Object}     object with install method and the other relative functions exported for testing purposes
- */
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  /**
-   * registers a depHook for fastify module instrumentation
-   */
-  function install() {
-    depHooks.resolve({ name: 'fastify', version: '>=3.0.0' }, (fastify) => patchFastify(fastify));
-  }
-
-  /**
-   * The patch function for the depHooks callback
-   * @param {Object} fastify the fastify object returned from requiring the module
-   * @returns                a patched fastify object
-   */
-  function patchFastify(fastify) {
-    return patcher.patch(fastify, {
-      name: 'fastify.build',
-      patchType,
-      post({ result: server }) {
-        server.addHook('preValidation', preValidationHook);
-      },
-    });
-  }
-
-  /**
-   * Fastify lifecycle hook as defined in official docs.
-   * @external https://www.fastify.io/docs/latest/Reference/Hooks/#prevalidation
-   * @param {Fastify.Request} request incoming request
-   * @param {Fastify.Reply}   reply   unbuilt outgoing response
-   * @param {Function}        done    callback to signal the hook is finished.
-   */
-  function preValidationHook(request, reply, done) {
-    const sourceContext = sources.getStore()?.protect;
-    let securityException;
-
-    if (!sourceContext) {
-      logger.debug('source context not available in fastify prevalidation hook');
-    } else {
-      try {
-        if (request.params) {
-          sourceContext.parsedParams = request.params;
-          inputAnalysis.handleUrlParams(sourceContext, request.params);
-        }
-        if (request.cookies) {
-          sourceContext.parsedCookies = request.cookies;
-          inputAnalysis.handleCookies(sourceContext, request.cookies);
-        }
-        if (request.body) {
-          sourceContext.parsedBody = request.body;
-          inputAnalysis.handleParsedBody(sourceContext, request.body);
-        }
-
-        if (request.query) {
-          sourceContext.parsedQuery = request.query;
-          inputAnalysis.handleQueryParams(sourceContext, request.query);
-        }
-      } catch (err) {
-        if (isSecurityException(err)) {
-          securityException = err;
-        } else {
-          logger.error({ err }, 'Unexpected error during input analysis');
-        }
-      }
-    }
-
-    done(securityException);
-  }
-
-  const fastify3Instrumentation = inputAnalysis.fastify3Instrumentation = {
-    preValidationHook,
-    install,
-  };
-
-  return fastify3Instrumentation;
-};

package/lib/utils.js

@@ -1,84 +0,0 @@
-/*
- * 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';
-
-/**
- * simpleTraverse() walks an object and calls a user function for each key
- * and string value. It is a "simple traverse" in that it
- * 1) doesn't make value callbacks unless the value is a non-empty string
- * 2) it only recognizes items that can be expressed in JSON, i.e., POJO
- * and arrays.
- * 3) it doesn't make callbacks for array indexes (though they appear in
- * the path). array indexes are always numeric and are not a threat.
- *
- * N.B. the path array that is passed to the callback is a dynamic path; new
- * keys are pushed and popped onto the path as simpleTraverse() walks the
- * object. in order to capture the path at the time of the callback, the
- * callback must copy the array, e.g., `path.slice()`, in order to "freeze"
- * it at the time of the callback. the reason for this is that most keys/values
- * are not going to be of interest, and there is no reason to create a new array
- * unless the key/value is of interest.
- *
- * @param {Object} obj the object to traverse
- * @param {Function} cb(path, type, value) is called for each non-array-index key
- * and string value. It is not called for non-string or empty-string Values.
- *   path {[String]} the path prior to the 'Key' or 'Value'; includes array indexes.
- *   type {String} 'Key' or 'Value'
- *   value {String} the Key or Leaf string
- *
- */
-function simpleTraverse(obj, cb) {
-  if (typeof obj !== 'object' || obj === null) {
-    return;
-  }
-  const path = [];
-  /* eslint-disable complexity */
-  function traverse(obj) {
-    const isArray = Array.isArray(obj);
-    for (const k in obj) {
-      if (isArray) {
-        // if it is an array, store each index in path but don't call the
-        // callback on the index itself as they are just numeric strings.
-        path.push(k);
-        if (typeof obj[k] === 'object' && obj[k] !== null) {
-          traverse(obj[k]);
-        } else if (typeof obj[k] === 'string' && obj[k]) {
-          cb(path, 'Value', obj[k]);
-        }
-        path.pop();
-      } else if (typeof obj[k] === 'object' && obj[k] !== null) {
-        cb(path, 'Key', k);
-        path.push(k);
-        traverse(obj[k]);
-        path.pop();
-      } else {
-        cb(path, 'Key', k);
-        // only callback if the value is a non-empty string
-        if (typeof obj[k] === 'string' && obj[k]) {
-          path.push(k);
-          cb(path, 'Value', obj[k]);
-          path.pop();
-        }
-      }
-    }
-  }
-
-  traverse(obj);
-}
-
-module.exports = {
-  simpleTraverse,
-};