@contrast/protect 1.2.1 → 1.4.0

package/lib/semantic-analysis/handlers.js

@@ -0,0 +1,160 @@
+/*
+ * 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,
+  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.rules.agentRules[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.rules.agentRules[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.rules.agentRules[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/lib/throw-security-exception.js

@@ -1,6 +1,20 @@
+/*
+ * 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 Domain = require('async-hook-domain');
 const securityException = require('./security-exception');
 
 module.exports = function(core) {
@@ -17,12 +31,9 @@ module.exports = function(core) {
 
     const err = securityException.create();
 
-    new Domain(() => {
-      sourceContext.block(mode, ruleId);
-    });
-
-    logger.info({ err, mode, ruleId }, 'throwing security exception');
+    logger.debug({ err, mode, ruleId }, 'throwing security exception');
 
+    // TO-DO: NODE-2556 Research fail-safe handler for all security exceptions
     throw err;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.2.1",
+  "version": "1.4.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,11 +9,8 @@
   ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
-  "bin": {
-    "contrast-transpile": "lib/cli-rewriter.js"
-  },
   "engines": {
-    "npm": ">=6.13.7 <7 || >= 8.4.0",
+    "npm": ">= 8.4.0",
     "node": ">= 14.15.0"
   },
   "scripts": {
@@ -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.1",
-    "@contrast/core": "1.1.1",
-    "@contrast/scopes": "1.0.1",
-    "@contrast/esm-hooks": "1.1.1",
-    "async-hook-domain": "^2.0.4",
-    "builtin-modules": "^3.2.0"
+    "@contrast/agent-lib": "^5.0.0",
+    "@contrast/common": "1.1.0",
+    "@contrast/core": "1.3.0",
+    "@contrast/esm-hooks": "1.1.4",
+    "@contrast/scopes": "1.1.1",
+    "builtin-modules": "^3.2.0",
+    "ipaddr.js": "^2.0.1",
+    "semver": "^7.3.7"
   }
 }

package/lib/cli-rewriter.js

@@ -1,20 +0,0 @@
-#!/usr/bin/env node
-
-'use strict';
-
-const { cliRewriter } = require('@contrast/core')();
-
-cliRewriter((deps) => {
-  if (deps.config.protect.enable) {
-    try {
-      const protect = require('./index')(deps);
-      protect.rewriting.install();
-    } catch (err) {
-      // TODO: something else
-      throw err;
-    }
-  } else {
-    deps.logger.error('Configuration Error: mode \'Protect\' is not enabled');
-    process.exit(1);
-  }
-});

package/lib/input-analysis/install/co-body.js

@@ -1,51 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  async function postHook(data) {
-    const { args: [, opts], result } = data;
-    if (result) {
-      const sourceContext = sources.getStore()?.protect;
-      if (!sourceContext) {
-        logger.debug('source context not available in `co-body` hook');
-      } else {
-        result.then((resolved) => {
-          const parsedBody = opts?.returnRawBody ? resolved.parsed : resolved;
-          sourceContext.parsedBody = parsedBody;
-          inputAnalysis.handleParsedBody(sourceContext, parsedBody);
-        });
-      }
-    }
-  }
-
-  return {
-    // Patch lower level parser - `co-body` used by `koa-body` and `koa-bodyparser`
-    install() {
-      depHooks.resolve({ name: 'co-body' }, (coBody) => {
-        coBody = patcher.patch(coBody, {
-          name: 'co-body',
-          patchType: 'framework-patch',
-          post: postHook
-        });
-
-        ['json', 'form', 'text'].forEach((property) => {
-          patcher.patch(coBody, property, {
-            name: `co-body.${property}`,
-            patchType: 'framework-patch',
-            post: postHook
-          });
-        });
-
-        return coBody;
-      }
-      );
-    }
-  };
-};

package/lib/input-analysis/install/cookie-parser.js

@@ -1,48 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  return {
-  // Patch `cookie-parser` package
-    install() {
-      depHooks.resolve({ name: 'cookie-parser' }, (cookieParser) => patcher.patch(cookieParser, {
-        name: 'cookie-parser',
-        patchType: 'framework-patch',
-        post(data) {
-          data.result = patcher.patch(data.result, {
-            name: 'cookie-parser',
-            patchType: 'framework-patch',
-            pre(data) {
-              const [req, , origNext] = data.args;
-
-              async function contrastNext() {
-                const sourceContext = sources.getStore()?.protect;
-
-                if (!sourceContext) {
-                  logger.debug('source context not available in `cookie-parser` hook');
-                } else {
-                  if (req.cookies) {
-                    sourceContext.parsedCookies = req.cookies;
-                    inputAnalysis.handleCookies(sourceContext, req.cookies);
-                  }
-                }
-
-                await origNext();
-              }
-
-              data.args[2] = contrastNext;
-            }
-          });
-        }
-      })
-      );
-    }
-  };
-};

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

@@ -1,53 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  return {
-    // Patch `formidable`
-    install() {
-      depHooks.resolve({ name: 'formidable' }, (formidable) => {
-        formidable.IncomingForm.prototype.parse = patcher.patch(formidable.IncomingForm.prototype.parse, {
-          name: 'Formidable.IncomingForm.prototype.parse',
-          patchType: 'framework-patch',
-          pre(data) {
-            const origCb = data.args[1];
-
-            function hookedCb(...cbArgs) {
-              const sourceContext = sources.getStore()?.protect;
-              const [, fields, files] = cbArgs;
-
-              if (!sourceContext) {
-                logger.debug('source context not available in `formidable` hook');
-              } else {
-                if (fields) {
-                  sourceContext.parsedBody = fields;
-                  inputAnalysis.handleParsedBody(sourceContext, fields);
-                }
-                if (files) {
-                  logger.debug('Check for vulnerable filename upload nyi');
-                  // CHECK FILENAME - NYI
-                }
-              }
-
-              if (origCb && typeof origCb === 'function') {
-                // Should we explicitly run in the current source context?
-                origCb.apply(this, cbArgs);
-              }
-            }
-
-            data.args[1] = hookedCb;
-          }
-        });
-
-        return formidable;
-      });
-    }
-  };
-};

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

@@ -1,52 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  return {
-    // Patch `multer`
-    install() {
-      depHooks.resolve({ name: 'multer', file: 'lib/make-middleware.js' }, (multerMakeMiddleware) => patcher.patch(multerMakeMiddleware, {
-        name: 'multer.make-middleware',
-        patchType: 'framework-patch',
-        post(data) {
-          data.result = patcher.patch(data.result, {
-            name: 'multerMiddleware',
-            patchType: 'framework-patch',
-            pre(data) {
-              const [req, , origNext] = data.args;
-
-              async function contrastNext() {
-
-                const sourceContext = sources.getStore()?.protect;
-
-                if (!sourceContext) {
-                  logger.debug('source context not available in `multer` hook');
-                } else {
-                  if (req.body) {
-                    sourceContext.parsedBody = req.body;
-                    inputAnalysis.handleParsedBody(sourceContext, req.body);
-                  }
-                  if (req.file || req.files) {
-                    logger.debug('Check for vulnerable filename upload nyi');
-                    // CHECK FILENAME - NYI
-                  }
-                }
-
-                await origNext();
-              }
-
-              data.args[2] = contrastNext;
-            }
-          });
-        }
-      }));
-    }
-  };
-};

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

@@ -1,40 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  return {
-    // Patch `qs`
-    install() {
-      depHooks.resolve({ name: 'qs' },
-        (qs) => patcher.patch(qs, 'parse', {
-          name: 'qs',
-          patchType: 'framework-patch',
-          post({ args, result }) {
-            if (result && Object.keys(result).length) {
-              const sourceContext = sources.getStore()?.protect;
-
-              if (!sourceContext) {
-                logger.debug('source context not available in `qs` hook');
-
-              // We need to run analysis for the `qs` result only when it's used as a query parser.
-              // `qs` is used also for parsing bodies, but these cases we handle individually with
-              // the respective library that's using it (e.g. `formidable`, `co-body`) because in
-              // some cases its use is optional and we cannot rely on it.
-              } else if (sourceContext.reqData?.queries === args[0]) {
-                sourceContext.parsedQuery = result;
-                inputAnalysis.handleQueryParams(sourceContext, result);
-              }
-            }
-          }
-        })
-      );
-    }
-  };
-};

package/lib/input-analysis/install/universal-cookie.js

@@ -1,34 +0,0 @@
-'use strict';
-
-module.exports = (core) => {
-  const {
-    depHooks,
-    patcher,
-    logger,
-    scopes: { sources },
-    protect: { inputAnalysis },
-  } = core;
-
-  return {
-  // Patch `universal-cookie` package
-    install() {
-      depHooks.resolve({ name: 'universal-cookie', file: 'cjs/utils.js' }, (uCookieUtils) => patcher.patch(uCookieUtils, 'parseCookies', {
-        name: 'universal-cookie.utils',
-        patchType: 'framework-patch',
-        post({ result }) {
-          if (result && Object.keys(result).length) {
-            const sourceContext = sources.getStore()?.protect;
-
-            if (!sourceContext) {
-              logger.debug('source context not available in `universal-cookie` hook');
-            } else {
-              sourceContext.parsedCookies = result;
-              inputAnalysis.handleCookies(sourceContext, result);
-            }
-          }
-        }
-      })
-      );
-    }
-  };
-};

package/lib/input-tracing/handlers/nosql-injection-mongo.js

@@ -1,48 +0,0 @@
-'use strict';
-
-/* c8 ignore start */
-// this is just the general structure of how to handle mongo sinks
-const util = require('util');
-
-const { simpleTraverse } = require('../../utils');
-
-function mongoSink(results, sinkContext) {
-  if (typeof sinkContext.value === 'object') {
-    return handleObjectValue(results, sinkContext.value);
-  } else if (typeof sinkContext.value === 'string') {
-    return handleStringValue(results, sinkContext.value);
-  }
-
-  return null;
-}
-
-function handleObjectValue(results, object) {
-  for (const result of results) {
-    simpleTraverse(object, function(path, type, value) {
-      if (type !== 'Key') {
-        return;
-      }
-      // the result value is the key that was found
-      if (result.value === value) {
-        // does the object at this path equal the user input?
-        let obj = object;
-        for (const p of path) {
-          obj = obj[p];
-        }
-        obj = obj[value];
-        // does the found object in the query equal the saved object?
-        if (util.isDeepStrictEqual(obj, object)) {
-          //
-        }
-      }
-    });
-  }
-}
-
-function handleStringValue(results, string) {
-  // nyi
-}
-
-module.exports = mongoSink;
-
-/* c8 ignore stop */