@contrast/protect 1.4.0 → 1.5.0

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

@@ -34,6 +34,7 @@ class HttpInstrumentation {
     this.logger = logger.child({ name: '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 +52,7 @@ class HttpInstrumentation {
     this.installed = true;
     this.hookHttp();
     this.hookHttps();
+    this.hookHttp2();
   }
 
   uninstall() {
@@ -62,7 +64,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 +72,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 +161,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,8 +171,10 @@ 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;
       }
 
@@ -169,17 +206,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/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/function.js

@@ -0,0 +1,60 @@
+/*
+ * 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;
+    }
+
+    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;
+};

package/lib/semantic-analysis/handlers.js

@@ -17,6 +17,7 @@
 
 const {
   BLOCKING_MODES,
+  ProtectRuleMode: { OFF },
   InputType,
   isString,
   simpleTraverse
@@ -50,9 +51,9 @@ module.exports = function(core) {
 
   semanticAnalysis.handleCmdInjectionSemanticDangerous = function(sourceContext, sinkContext) {
     const ruleId = 'cmd-injection-semantic-dangerous-paths';
-    const { mode } = sourceContext.rules.agentRules[ruleId];
+    const mode = sourceContext.policy[ruleId];
 
-    if (mode == 'off') return;
+    if (mode == OFF) return;
 
     const result = agentLib.containsDangerousPath(sinkContext.value);
 
@@ -63,9 +64,9 @@ module.exports = function(core) {
 
   semanticAnalysis.handleCmdInjectionSemanticChainedCommands = function(sourceContext, sinkContext) {
     const ruleId = 'cmd-injection-semantic-chained-commands';
-    const { mode } = sourceContext.rules.agentRules[ruleId];
+    const mode = sourceContext.policy[ruleId];
 
-    if (mode == 'off') return;
+    if (mode == OFF) return;
 
     const indexOfChaining = agentLib.indexOfChaining(sinkContext.value);
 
@@ -76,9 +77,9 @@ module.exports = function(core) {
 
   semanticAnalysis.handleCommandInjectionCommandBackdoors = function(sourceContext, sinkContext) {
     const ruleId = 'cmd-injection-command-backdoors';
-    const { mode } = sourceContext.rules.agentRules[ruleId];
+    const mode = sourceContext.policy[ruleId];
 
-    if (mode == 'off') return;
+    if (mode == OFF) return;
 
     const finding = findBackdoorInjection(sourceContext, sinkContext.value);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.4.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)",
@@ -19,10 +19,10 @@
   "dependencies": {
     "@babel/template": "^7.16.7",
     "@babel/types": "^7.16.8",
-    "@contrast/agent-lib": "^5.0.0",
-    "@contrast/common": "1.1.0",
-    "@contrast/core": "1.3.0",
-    "@contrast/esm-hooks": "1.1.4",
+    "@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",