@contrast/protect 1.4.0 → 1.6.0

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

@@ -0,0 +1,106 @@
+/*
+ * 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');
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    protect,
+    protect: { inputAnalysis },
+  } = core;
+
+  /**
+   * registers a depHook for hapi module instrumentation
+   */
+  function install() {
+    depHooks.resolve(
+      { name: 'hapi', version: '>=18 <21' },
+      registerServerHandler
+    );
+    depHooks.resolve(
+      { name: '@hapi/hapi', version: '>=18 <21' },
+      registerServerHandler
+    );
+  }
+
+  const registerServerHandler = (hapi) => {
+    patcher.patch(hapi, 'server', {
+      name: 'hapi.server',
+      patchType,
+      post(data) {
+        const server = data.result;
+        if (server) {
+          instrumentServer(server);
+        } else {
+          logger.error('Hapi Server is called but there is no server instance!');
+        }
+      }
+    });
+  };
+
+  const instrumentServer = (server) => {
+    server.ext('onPreStart', function onPreStart(core) {
+      logger.info('hapi version %s', core.version);
+    });
+
+    server.ext('onPreHandler', function onPreHandler(req, h) {
+      const sourceContext = protect.getSourceContext('hapi.onPreHandler');
+
+      if (sourceContext) {
+        try {
+          if (req.params && Object.keys(req.params).length) {
+            sourceContext.parsedParams = req.params;
+            inputAnalysis.handleUrlParams(sourceContext, req.params);
+          }
+
+          if (req.cookies && Object.keys(req.cookies).length) {
+            sourceContext.parsedCookies = req.cookies;
+            inputAnalysis.handleCookies(sourceContext, req.cookies);
+          }
+
+          if (req.payload && Object.keys(req.payload).length) {
+            sourceContext.parsedBody = req.payload;
+            inputAnalysis.handleParsedBody(sourceContext, req.payload);
+          }
+
+          if (req.query && Object.keys(req.query).length) {
+            sourceContext.parsedQuery = req.query;
+            inputAnalysis.handleQueryParams(sourceContext, req.query);
+          }
+        } catch (err) {
+          if (isSecurityException(err)) {
+            throw err;
+          } else {
+            logger.error({ err }, 'Unexpected error during input analysis');
+          }
+        }
+      }
+
+      return h.continue;
+    });
+  };
+
+  const hapiInstrumentation = inputAnalysis.hapiInstrumentation = {
+    install
+  };
+
+  return hapiInstrumentation;
+};

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

@@ -27,13 +27,13 @@ module.exports = function(core) {
 };
 class HttpInstrumentation {
   constructor(core) {
-    const { logger } = core;
     this.messages = core.messages;
     this.scope = core.scopes.sources;
     this.config = core.config;
-    this.logger = logger.child({ name: 'contrast:protect:input-analysis' });
+    this.logger = core.logger.child('contrast:protect:input-analysis');
     this.depHooks = core.depHooks;
     this.protect = core.protect;
+    this.patcher = core.patcher;
     this.makeSourceContext = this.protect.makeSourceContext;
     this.maxBodySize = 16 * 1024 * 1024;
     this.installed = false;
@@ -51,6 +51,7 @@ class HttpInstrumentation {
     this.installed = true;
     this.hookHttp();
     this.hookHttps();
+    this.hookHttp2();
   }
 
   uninstall() {
@@ -62,7 +63,7 @@ class HttpInstrumentation {
    */
   hookHttp() {
     this.logger.debug('hooking library: http');
-    this.depHooks.resolve({ name: 'http' }, this.hookServer.bind(this));
+    this.depHooks.resolve({ name: 'http' }, (http) => this.hookServerEmit.call(this, http, 'httpServer'));
   }
 
   /**
@@ -70,36 +71,78 @@ class HttpInstrumentation {
    */
   hookHttps() {
     this.logger.debug('hooking library: https');
-    this.depHooks.resolve({ name: 'https' }, this.hookServer.bind(this));
+    this.depHooks.resolve({ name: 'https' }, (https) => this.hookServerEmit.call(this, https, 'httpsServer'));
   }
 
   /**
-   * Instruments the `Server` prototype from `http(s)`. This patches `emit` and
+   * Sets hooks to instrument `http2 Servers`.
+   */
+  hookHttp2() {
+    this.logger.debug('hooking library: http2');
+    // http2 library does not expose its Server class, so we need to hook the createServer function
+    this.depHooks.resolve({ name: 'http2' }, (http2) => this.hookCreateServer.call(this, http2, 'http2Server'));
+    this.depHooks.resolve({ name: 'http2' }, (http2) => this.hookCreateServer.call(this, http2, 'http2SecureServer', 'createSecureServer'));
+
+    this.logger.debug('hooking library: spdy');
+    this.depHooks.resolve({ name: 'spdy' }, (spdy) => this.hookServerEmit.call(this, spdy, 'spdyServer'));
+  }
+
+  /**
+   * Instruments the `Server` prototype from `http(s)` or spdy's http2 Server. This patches `emit` and
+   * invokes the protect service to do analysis when appropriate.
+   */
+  hookServerEmit(serverSource, sourceName) {
+    serverSource.Server.prototype = this.patcher.patch(serverSource.Server.prototype, 'emit', {
+      name: `${sourceName}.Server.prototype.emit`,
+      patchType: 'initiate-handling',
+      around: this.emitAroundHook.bind(this)
+    });
+  }
+
+  /**
+   * Instruments the `Http2Server` prototype which results from the http2.createServer/createSecureServer() call.
+   * This also patches `emit` and
    * invokes the protect service to do analysis when appropriate.
-   *
-   * @param {Object} xport The http(s) module export
    */
-  hookServer(xport) {
+  hookCreateServer(serverSource, sourceName, constructorName = 'createServer') {
     const self = this;
 
-    const {
-      Server: {
-        prototype: { emit }
-      }
-    } = xport;
+    return this.patcher.patch(serverSource, constructorName, {
+      name: sourceName,
+      patchType: 'initiate-handling',
+      post(data) {
+
+        const { result: server } = data;
+        const serverPrototype = server ? Object.getPrototypeOf(server) : null;
 
-    xport.Server.prototype.emit = function(...args) {
-      const [type] = args;
+        if (!serverPrototype) {
+          self.logger.error('Unable to patch server prototype, continue without instrumentation');
+          return;
+        }
 
-      if (type !== 'request') {
-        return emit.call(this, ...args);
+        self.patcher.patch(serverPrototype, 'emit', {
+          name: `${sourceName}.Server.prototype.emit`,
+          patchType: 'req-async-storage',
+          around: self.emitAroundHook.bind(self)
+        });
       }
+    });
+  }
 
-      const context = { instance: this, method: emit, args };
-      self.initiateRequestHandling(context);
+  /**
+   * The around hook for `emit` that
+   * invokes the protect service to do analysis when appropriate.
+   */
+  emitAroundHook(next, data) {
+    const [type] = data.args;
 
-      return !!this._events[type];
-    };
+    if (type !== 'request') {
+      return next();
+    }
+
+    const context = { instance: data.obj, method: next, args: data.args };
+    this.initiateRequestHandling(context);
+    return !!data.obj._events[type];
   }
 
   /**
@@ -117,15 +160,6 @@ class HttpInstrumentation {
       args: [, req, res]
     } = fnContext;
 
-    // URL exclusions should be applied here. there is no point in doing any additional
-    // work if the url is excluded for a particular rule, i.e., that rule should be removed
-    // from the list of rules for this request. and if all rules are excluded for this url
-    // then none of the following needs to be done.
-    if (this.protect.rules.agentLibRulesMask === 0) {
-      this.logger.debug('no agent-lib rules are enabled, not checking request');
-      return;
-    }
-
     let store;
     let block;
 
@@ -136,15 +170,20 @@ class HttpInstrumentation {
       // so that an async context is present.
       store = this.scope.getStore();
       // nothing can be done if async context is not available.
+
       if (!store) {
         this.logger.debug('cannot acquire store for initiateRequestHandling()');
+        setImmediate(() => method.call(instance, ...args));
         return;
       }
 
       store.protect = this.makeSourceContext(req, res);
       const { reqData } = store.protect;
 
-      res.on('finish', () => messages.emit(Event.PROTECT, store));
+      res.on('finish', () => {
+        this.protect.inputAnalysis.handleRequestEnd(store.protect);
+        messages.emit(Event.PROTECT, store);
+      });
 
       // don't put inputs in the store; they are a param to each handler. findings
       // associated with inputs do go into the store. why not put the inputs
@@ -169,17 +208,21 @@ class HttpInstrumentation {
         // TODO AGENT-203 - need to handle method-tampering rule.
         method: reqData.method,
       };
+
       // only add queries if it's known that 'qs' or equivalent won't be used.
       /* c8 ignore next 3 */
       if (reqData.standardUrlParsing) {
         connectInputs.queries = reqData.queries;
       }
+
       if (inputAnalysis.virtualPatchesEvaluators?.length) {
         store.protect.virtualPatchesEvaluators.push(...inputAnalysis.virtualPatchesEvaluators.map((e) => new Map(e)));
       }
+
       if (inputAnalysis.ipDenylist?.length) {
         block = inputAnalysis.handleIpDenylist(store.protect, inputAnalysis.ipDenylist);
       }
+
       if (inputAnalysis.ipAllowlist?.length) {
         const allowed = inputAnalysis.handleIpAllowlist(store.protect, inputAnalysis.ipAllowlist);
         if (!block) Object.assign(store.protect, { allowed });

package/lib/input-tracing/handlers/index.js

@@ -16,7 +16,12 @@
 'use strict';
 
 const util = require('util');
-const { BLOCKING_MODES, isString, simpleTraverse } = require('@contrast/common');
+const {
+  ProtectRuleMode: { OFF },
+  BLOCKING_MODES,
+  isString,
+  simpleTraverse
+} = require('@contrast/common');
 
 module.exports = function(core) {
   const { protect: { agentLib, inputTracing, throwSecurityException } } = core;
@@ -24,7 +29,7 @@ module.exports = function(core) {
   function handleFindings(sourceContext, sinkContext, ruleId, result, findings) {
     result.details.push({ sinkContext, findings });
 
-    const { mode } = sourceContext.rules.agentLibRules[ruleId];
+    const mode = sourceContext.policy[ruleId];
 
     if (BLOCKING_MODES.includes(mode)) {
       result.blocked = true;
@@ -215,7 +220,7 @@ module.exports = function(core) {
  * @returns {AnalysisResult[]}
  */
 function getResultsByRuleId(ruleId, context) {
-  if (context.rules.agentLibRules[ruleId].mode === 'off') {
+  if (context.policy[ruleId] === OFF) {
     return;
   }
   return context.findings.resultsMap[ruleId];

package/lib/input-tracing/index.js

@@ -15,21 +15,15 @@
 
 'use strict';
 
-/**
- * INPUT TRACING is a STAGE of Protect.
- * The specification can be found here https://protect-spec.prod.dotnet.contsec.com/guide/input-tracing.html.
- *
- * 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}
- */
+const { installChildComponentsSync } = require('@contrast/common');
+
 module.exports = function(core) {
   const inputTracing = core.protect.inputTracing = {};
 
-  // load the interfaces that will be used by input tracing instrumentation
+  // api
   require('./handlers')(core);
 
-  // load the instrumentation installers
+  // instrumentation
   require('./install/child-process')(core);
   require('./install/fs')(core);
   require('./install/mongodb')(core);
@@ -38,17 +32,13 @@ module.exports = function(core) {
   require('./install/sequelize')(core);
   require('./install/sqlite3')(core);
   require('./install/http')(core);
+  require('./install/vm')(core);
+  require('./install/eval')(core);
+  require('./install/function')(core);
+  // TODO: NODE-2360 (oracledb)
 
   inputTracing.install = function() {
-    inputTracing.cpInstrumentation.install();
-    inputTracing.fsInstrumentation.install();
-    inputTracing.mongodbInstrumentation.install();
-    inputTracing.mysqlInstrumentation.install();
-    inputTracing.postgresInstrumentation.install();
-    inputTracing.sequelizeInstrumentation.install();
-    inputTracing.sqlite3Instrumentation.install();
-    inputTracing.httpInstrumentation.install();
-    // TODO: NODE-2360 (2260?)
+    installChildComponentsSync(inputTracing);
   };
 
   return inputTracing;

package/lib/input-tracing/install/child-process.js

@@ -54,6 +54,7 @@ module.exports = function(core) {
             core.protect.semanticAnalysis.handleCommandInjectionCommandBackdoors(sourceContext, sinkContext);
             core.protect.semanticAnalysis.handleCmdInjectionSemanticChainedCommands(sourceContext, sinkContext);
             core.protect.semanticAnalysis.handleCmdInjectionSemanticDangerous(sourceContext, sinkContext);
+            core.protect.semanticAnalysis.handlePathTraversalFileSecurityBypass(sourceContext, sinkContext);
           }
         });
       });

package/lib/input-tracing/install/eval.js

@@ -29,13 +29,13 @@ module.exports = function(core) {
   } = core;
 
   function install() {
-    if (!global.ContrastMethods.__contrastEval) {
+    if (!global.ContrastMethods.eval) {
       logger.error('Cannot install `eval` instrumentation - Contrast method DNE');
       return;
     }
 
-    patcher.patch(global.ContrastMethods, '__contrastEval', {
-      name: 'global.ContrastMethods.__contrastEval',
+    patcher.patch(global.ContrastMethods, 'eval', {
+      name: 'global.ContrastMethods.eval',
       patchType,
       pre: ({ args, hooked, orig }) => {
         if (instrumentation.isLocked()) return;

package/lib/input-tracing/install/fs.js

@@ -106,6 +106,7 @@ module.exports = function(core) {
                 { constructorOpt: hooked, prependFrames: [orig] }
               );
               inputTracing.handlePathTraversal(sourceContext, sinkContext);
+              core.protect.semanticAnalysis.handlePathTraversalFileSecurityBypass(sourceContext, sinkContext);
             }
           }
         });

package/lib/input-tracing/install/function.js

@@ -0,0 +1,62 @@
+/*
+ * 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 { isString } = require('@contrast/common');
+const { patchType } = require('../constants');
+
+module.exports = function(core) {
+  const {
+    logger,
+    scopes: { instrumentation },
+    patcher,
+    captureStacktrace,
+    protect,
+    protect: { inputTracing }
+  } = core;
+
+  function install() {
+    if (!global.ContrastMethods.Function) {
+      logger.error('Cannot install `Function` instrumentation - Contrast method DNE');
+      return;
+    }
+
+    Object.assign(global.ContrastMethods, {
+      Function: patcher.patch(global.ContrastMethods.Function, {
+        name: 'global.ContrastMethods.Function',
+        patchType,
+        pre: ({ args, hooked, orig }) => {
+          if (instrumentation.isLocked()) return;
+
+          const sourceContext = protect.getSourceContext('Function');
+          const fnBody = args[args.length - 1];
+
+          if (!sourceContext || !fnBody || !isString(fnBody)) return;
+
+          const sinkContext = captureStacktrace(
+            { name: 'Function', value: fnBody },
+            { constructorOpt: hooked, prependFrames: [orig] }
+          );
+          inputTracing.ssjsInjection(sourceContext, sinkContext);
+        }
+      })
+    });
+  }
+
+  const functionInstrumentation = inputTracing.functionInstrumentation = { install };
+
+  return functionInstrumentation;
+};

package/lib/make-source-context.js

@@ -16,6 +16,7 @@
 'use strict';
 
 module.exports = function(core) {
+  const { protect } = core;
 
   function makeSourceContext(req, res) {
     // make the abstract request. it is an abstraction of a request that
@@ -79,9 +80,8 @@ module.exports = function(core) {
       // block closure captures res so it isn't exposed to beyond here
       block: core.protect.makeResponseBlocker(res),
 
-      // this should be changed to capture only the rules applicable to this
-      // particular request (if any route exclusions, etc.)
-      rules: core.protect.rules,
+      policy: protect.getPolicy(),
+
       exclusions: [],
       virtualPatchesEvaluators: [],
 
@@ -98,54 +98,10 @@ module.exports = function(core) {
         semanticResultsMap: Object.create(null),
         serverFeaturesResultsMap: Object.create(null)
       },
-
-      /*
-      findings: {
-        trackRequest: true,
-        resultsList: [
-          // Example 2
-          {
-            // return value from agent-lib
-            value: 'kill -9 1',
-            type: 'PARAMETER_VALUE',
-            ruleId: 'cmd-injection',
-            path: ['path', 'to', 'val'],
-            // other data added during lifecycle
-            // could we add these by mutating agent-lib return values?
-            // What if there are multiple injections for the same value? The `details` value
-            // could be an array in that case, or is this too complicated.
-            blocked: false,
-            details: [
-              {
-                context: {
-                  id: 'child_process.exec',
-                  get stack() {}, // lazy
-                  command: 'sudo kill -9 1',
-                  index: 5,
-                }
-              },
-              {
-                sinkId: 'child_process.exec',
-                get stack() {}, // lazy
-                command: 'sudo kill -9 1',
-                index: 5,
-              }]
-          },
-        ]
-      }
-      // (scoreAtom() returns only the ruleId and score because the caller supplied
-      // the input and type; no key or path is known to scoreAtom(). code calling
-      // scoreAtom() will need to augment the finding to match the above.)
-      //
-      // each finding is augmented with additional properties
-      // - blocked: false     // set to true if the finding causes the request to be blocked
-      // - mappedId: ruleId   // normalized ruleId, e.g., nosql-injection-mongo => nosql-injection
-      // -
-      // */
     };
 
     return protectStore;
   }
 
-  core.protect.makeSourceContext = makeSourceContext;
+  return core.protect.makeSourceContext = makeSourceContext;
 };

package/lib/policy.js

@@ -0,0 +1,134 @@
+/*
+ * 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 {
+  Rule,
+  ProtectRuleMode: {
+    BLOCK_AT_PERIMETER,
+    BLOCK,
+    MONITOR,
+    OFF,
+  },
+  Rule: { BOT_BLOCKER },
+  Event: { SERVER_SETTINGS_UPDATE },
+} = require('@contrast/common');
+
+
+module.exports = function(core) {
+  const { config, logger, messages, protect } = core;
+  const policy = protect.policy = {};
+
+  function getModeFromConfig(ruleId) {
+    if (config.protect.disabled_rules.includes(ruleId)) {
+      return 'off';
+    }
+    return config.protect.rules?.[ruleId]?.mode;
+  }
+
+  /**
+   * Coerces ContrastUI mode names to match from common-agent-configuration
+   * @param {} remoteSetting
+   * @returns {string}
+   */
+  function readModeFromSetting(remoteSetting) {
+    switch (remoteSetting.mode) {
+      case 'OFF': return OFF;
+      case 'MONITORING': return MONITOR;
+      case 'BLOCKING': return remoteSetting.blockAtEntry ? BLOCK_AT_PERIMETER : BLOCK;
+    }
+  }
+
+  /**
+   * Build out initial policy from configuration data
+   */
+  function initPolicy() {
+    for (const ruleId of Object.values(Rule)) {
+      policy[ruleId] = getModeFromConfig(ruleId) || OFF;
+    }
+    updateRulesMask();
+  }
+
+  /**
+   * When updates are given at runtime, we update our local rule policy while
+   * respecting rules of precedence.
+   * @param {[]} protectionRules
+   */
+  function updateFromProtectionRules(protectionRules) {
+    for (const remoteSetting of Object.values(protectionRules)) {
+      const { id: ruleId } = remoteSetting;
+
+      if (getModeFromConfig(ruleId)) {
+        continue;
+      }
+
+      policy[ruleId] = readModeFromSetting(remoteSetting);
+    }
+  }
+
+  /**
+   * Rebuild rules mask based on which agent-lib rules are enabled
+   */
+  function updateRulesMask() {
+    let rulesMask = 0;
+    for (const [ruleId, mode] of Object.entries(policy)) {
+      if (protect.agentLib.RuleType[ruleId] && mode !== OFF) {
+        rulesMask = rulesMask | protect.agentLib.RuleType[ruleId];
+      }
+    }
+    policy.rulesMask = rulesMask;
+  }
+
+  /**
+   * 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 };
+  }
+
+  initPolicy();
+
+  messages.on(SERVER_SETTINGS_UPDATE, (remoteSettings) => {
+    let update;
+
+    const protectionRules = remoteSettings?.settings?.defend?.protectionRules;
+    if (protectionRules) {
+      updateFromProtectionRules(protectionRules);
+      update = 'application-settings';
+    }
+
+    if (remoteSettings?.features?.defend) {
+      const bbEnabled = remoteSettings.features.defend[BOT_BLOCKER];
+
+      if (
+        bbEnabled != null &&
+        !config.protect.disabled_rules.includes(BOT_BLOCKER) &&
+        !config.protect.rules?.[BOT_BLOCKER]?.mode
+      ) {
+        policy[BOT_BLOCKER] = bbEnabled ? BLOCK_AT_PERIMETER : OFF;
+        update = 'server-features';
+      }
+    }
+
+    if (update) {
+      updateRulesMask();
+      logger.info({ policy: protect.policy }, `protect policy updated from ${update}`);
+    }
+  });
+
+  return protect.getPolicy = getPolicy;
+};