@contrast/protect 1.0.1

package/LICENSE

@@ -0,0 +1,12 @@
+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.

package/README.md

@@ -0,0 +1,9 @@
+# `@contrast/protect`
+
+## Sub-Components
+
+### Request Correlation
+
+### Input Analysis
+
+### Input Tracing

package/lib/cli-rewriter.js

@@ -0,0 +1,20 @@
+#!/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/error-handlers/constants.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = {
+  patchType: 'protect-error-handling'
+};

package/lib/error-handlers/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+module.exports = function(core) {
+  const errorHandlers = core.protect.errorHandlers = {};
+
+  require('./install/fastify3')(core);
+
+  errorHandlers.install = function() {
+    errorHandlers.fastify3ErrorHandler.install();
+  };
+
+  return errorHandlers;
+};

package/lib/error-handlers/install/fastify3.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const { isSecurityException } = require('../../security-exception');
+const { patchType } = require('../constants');
+
+module.exports = function(core) {
+  const {
+    logger,
+    depHooks,
+    patcher,
+    scopes: { sources },
+    protect,
+  } = core;
+
+  const fastify3ErrorHandler = protect.errorHandlers.fastify3ErrorHandler = {
+    _userHandler: null
+  };
+
+  /**
+   * This is the default handler from fastify's source code. If it's not a
+   * Contrast error and the user didn't supply their own we should use this.
+   */
+  fastify3ErrorHandler.defaultErrorHandler = function (error, request, reply) {
+    if (reply.statusCode < 500) {
+      reply.log.info({ res: reply, err: error }, error && error.message);
+    } else {
+      reply.log.error(
+        { req: request, res: reply, err: error },
+        error && error.message
+      );
+    }
+    reply.send(error);
+  };
+
+  /**
+   * Check if the error being handled was thrown by Contrast. If not,
+   * use either the default fastify3 error handler or the user-defined handler
+   * if one was specified by calling fastify.setErrorHandler(fn).
+   * @param {error} err error being handled
+   * @param {object} request fastify request
+   * @param {object} reply fastify repoly
+   */
+  fastify3ErrorHandler.handler = function(err, request, reply) {
+    const normalHandler = fastify3ErrorHandler._userHandler || fastify3ErrorHandler.defaultErrorHandler;
+
+    if (isSecurityException(err)) {
+      const sourceContext = sources.getStore()?.protect;
+      if (!sourceContext) {
+        logger.info('source context not found; unable to handle response');
+        normalHandler.call(this, err, request, reply);
+      } else {
+        const blockInfo = sourceContext.findings.securityException;
+        sourceContext.block(...blockInfo);
+      }
+    } else {
+      normalHandler.call(this, err, request, reply);
+    }
+  };
+
+  /**
+   * Instruments fastify in order to add our custom error handler.
+   */
+  fastify3ErrorHandler.install = function() {
+    depHooks.resolve({ name: 'fastify', version: '<=4.0.0' }, (fastify) => patcher.patch(fastify, {
+      name: 'fastify',
+      patchType,
+      post(data) {
+        const { result: server } = data;
+        // Set our custom handler initially
+        server.setErrorHandler(fastify3ErrorHandler.handler);
+
+        // Patch, so that if someone sets their own, we override with ours. But,
+        // we do need to keep a reference to it so we can still call it for when
+        // non-Contrast errors need handling.
+        patcher.patch(server, 'setErrorHandler', {
+          name: 'fastify.setErrorHandler',
+          patchType,
+          pre({ args }) {
+            fastify3ErrorHandler._userHandler = args[0];
+            args[0] = fastify3ErrorHandler.handler;
+          }
+        });
+      }
+    }));
+  };
+
+  return fastify3ErrorHandler;
+};

package/lib/error-handlers/install/fastify3.test.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const sinon = require('sinon');
+const { expect } = require('chai');
+const securityException = require('../../security-exception');
+const mocks = require('../../../../test/mocks');
+
+describe('protect error-handlers: fastify3', function() {
+  let core;
+  let errorHandler;
+  let fastify;
+  let server;
+  let reply;
+
+  beforeEach(function() {
+    core = mocks.core();
+    core.config = mocks.config();
+    core.logger = mocks.logger();
+    core.scopes = mocks.scopes();
+    core.protect = mocks.protect();
+    core.depHooks = mocks.depHooks();
+    core.patcher = require('@contrast/patcher')(core);
+
+    server = {
+      setErrorHandler: sinon.stub(),
+      errorHandler: sinon.stub()
+    };
+    fastify = function() {
+      return server;
+    };
+    core.depHooks.resolve.callsFake((desc, cb) => {
+      fastify = cb(fastify);
+    });
+    reply = {
+      log: {
+        info: sinon.stub(),
+        error: sinon.stub()
+      },
+      send: sinon.stub(),
+      statusCode: 500,
+    };
+
+    errorHandler = require('./fastify3')(core);
+    sinon.spy(errorHandler, 'defaultErrorHandler');
+    errorHandler.install();
+
+    fastify();
+  });
+
+  describe('instrumentation adds custom handler', function() {
+    it('patches fastify', function() {
+      expect(server.setErrorHandler).to.have.been.calledWith(errorHandler.handler);
+    });
+  });
+
+  describe('defaultErrorHandler()', function() {
+    let request;
+    let err;
+
+    beforeEach(function() {
+      request = {};
+      err = {};
+    });
+
+    it('logs at error level when 500 status code', function() {
+      errorHandler.handler(err, request, reply);
+      expect(reply.log.error).calledWith({ req: request, res: reply, err });
+    });
+
+    it('logs at info level when <500 status code', function() {
+      reply.statusCode = 404;
+      errorHandler.handler(err, request, reply);
+      expect(reply.log.info).calledWith({ res: reply, err });
+    });
+  });
+
+  describe('handler()', function() {
+    let request;
+    let err;
+    let store;
+    let userHandler;
+
+    beforeEach(function() {
+      request = {};
+      err = securityException.create();
+      store = {
+        protect: {
+          block: sinon.stub(),
+          findings: {
+            securityException: ['block', 'cmd-injection']
+          }
+        }
+      };
+      userHandler = sinon.stub();
+    });
+
+    it('calls default handler when the source context is not available', function() {
+      errorHandler.handler(err, request, reply);
+      expect(core.logger.info).calledWith('source context not found; unable to handle response');
+    });
+
+    it('when set, calls user handler when the source context is not available', function() {
+      server.setErrorHandler(userHandler);
+      errorHandler.handler(err, request, reply);
+      expect(core.logger.info).calledWith('source context not found; unable to handle response');
+      expect(userHandler).calledWith(err, request, reply);
+    });
+
+    it('calls source context\'s .block() with mode and id of rule which raised error', function() {
+      const {
+        protect: {
+          block,
+          findings: { securityException }
+        }
+      } = store;
+      core.scopes.sources.run(store, () => {
+        errorHandler.handler(err, request, reply);
+        expect(core.logger.info).not.called;
+        expect(block).calledWith(...securityException);
+      });
+    });
+
+    it('calls default error handler when error is not security exception', function() {
+      err = {};
+      core.scopes.sources.run(store, () => {
+        errorHandler.handler(err, request, reply);
+        expect(core.logger.info).not.called;
+        expect(errorHandler.defaultErrorHandler).calledWith(err, request, reply);
+      });
+    });
+
+    it('when set, calls user handler when error is ont seecurity exception', function() {
+      err = {};
+      server.setErrorHandler(userHandler);
+      core.scopes.sources.run(store, () => {
+        errorHandler.handler(err, request, reply);
+        expect(core.logger.info).not.called;
+        expect(userHandler).calledWith(err, request, reply);
+      });
+    });
+  });
+});

package/lib/esm-loader.mjs

@@ -0,0 +1,2 @@
+import esmHooks from '@contrast/esm-hooks';
+export const { getSource, transformSource, load } = esmHooks();

package/lib/esm-loader.test.mjs

@@ -0,0 +1,11 @@
+import chai from 'chai';
+const { expect } = chai;
+
+describe('protect esm-loader', function() {
+  it('exports the ESM hooks', async function() {
+    const hooks = await import('./esm-loader.mjs');
+    expect(hooks).itself.to.respondTo('getSource');
+    expect(hooks).itself.to.respondTo('transformSource');
+    expect(hooks).itself.to.respondTo('load');
+  });
+});

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+import { Core } from '@contrast/core';
+
+// TODO
+export interface Protect {
+  makeResponseBlocker: () => void,
+  makeSourceContext: () => void,
+  inputAnalysis: {
+    handleConnect: () => void,
+    handleRequestEnd: () => void,
+    handleRawBody: () => void,
+    handleQueryParams: () => void,
+    handleUrlParams: () => void,
+    handleCookies: () => void,
+    handleParsedBody: () => void,
+    handleFileuploadName: () => void,
+    install: () => void,
+  },
+  inputTracing: {
+    getResultsByRuleId: () => void,
+    handlerFactory: () => void,
+    handlePathTraversal: () => void,
+    handleCommandInjection: () => void,
+    handleSqlInjection: () => void,
+    install: () => void
+  }
+  errorHandlers: {
+    install: () => void,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  agentLib: any;
+  version: string,
+}
+
+declare function init(core: Core): Protect;
+
+export default init;

package/lib/index.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const agentLib = require('@contrast/agent-lib');
+
+module.exports = function(core) {
+  const protect = core.protect = {
+    agentLib: module.exports.instantiateAgentLib(agentLib),
+  };
+
+  const rules = instantiateRulesFromConfig(
+    core.config.protect.rules,
+    core.config.protect.disabled_rules,
+    protect.agentLib,
+  );
+
+  protect.rules = rules;
+
+  require('./throw-security-exception')(core);
+  require('./make-response-blocker')(core);
+  require('./make-source-context')(core);
+  require('./input-analysis')(core);
+  require('./input-tracing')(core);
+  require('./error-handlers')(core);
+
+  const pkj = require('../package.json');
+  protect.version = pkj.version;
+
+  protect.install = function() {
+    protect.inputAnalysis.install();
+    protect.inputTracing.install();
+    protect.errorHandlers.install();
+  };
+
+  return protect;
+};
+
+module.exports.instantiateAgentLib = instantiateAgentLib;
+
+/**
+ * Create an instance of agent-lib and attach the constants directly to it.
+ *
+ * @param {Object} lib the value returned by require('@contrast/agent-lib')
+ * @returns {Object} an agent-lib instance with the constants attached to it.
+ */
+function instantiateAgentLib(lib) {
+  const agentLib = new lib.Agent();
+  for (const c in lib.constants) {
+    agentLib[c] = lib.constants[c];
+  }
+  if ('version' in lib) {
+    agentLib.version = lib.version;
+  }
+  return agentLib;
+}
+
+/**
+ * This function instatiates the rules as defined in the configuration into
+ * some structure. I'm in no way convinced or asserting that this is the right
+ * structure but it does get a usable definition of rules in place. The final
+ * structure will change based on what exactly TS sends as well as what the needs
+ * of the code accessing the rules, exclusions, virtual-patches, etc.
+ *
+ * @param {Object} rules the rules object in the config.protect object.
+ * @param {string[]} disabled array of disabled rules from config.protect
+ * @param {Object} agentLib the agent-lib instance
+ * @returns {Object} { agentLibRules, agentLibRulesMask, agentRules }
+ */
+function instantiateRulesFromConfig(rules, disabled, agentLib) {
+  const agentLibRules = {};
+  let agentLibRulesMask = 0;
+  const agentRules = {};
+
+  for (const ruleId in rules) {
+    if (disabled.indexOf(ruleId) >= 0 || rules[ruleId].mode === 'off') {
+      continue;
+    }
+    // [matt] this is awkward. we should probably make each nosql-injection-x
+    // rule separate in the config and only convert them to 'nosql-injection'
+    // for reporting.
+    if (agentLib.RuleType[ruleId]) {
+      agentLibRules[ruleId] = rules[ruleId];
+      agentLibRulesMask = agentLibRulesMask | agentLib.RuleType[ruleId];
+    } else {
+      agentRules[ruleId] = rules[ruleId];
+    }
+  }
+
+  return { agentLibRules, agentLibRulesMask, agentRules };
+}

package/lib/index.test.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { expect } = require('chai');
+const proxyquire = require('proxyquire');
+
+const moduleMock = (moduleName, mock) => (deps) => {
+  deps.protect[moduleName] = mock[moduleName];
+};
+
+describe('protect', function () {
+  let mocks, coreMock, protectMock, protectModule, modulesWithInstall;
+  beforeEach(function () {
+    mocks = require('../../test/mocks');
+    protectMock = mocks.protect();
+    coreMock = { protect: {}, config: mocks.config() };
+    protectModule = proxyquire('.', {
+      './make-response-blocker': moduleMock('makeResponseBlocker', protectMock),
+      './make-source-context': moduleMock('makeSourceContext', protectMock),
+      './input-analysis': moduleMock('inputAnalysis', protectMock),
+      './input-tracing': moduleMock('inputTracing', protectMock),
+      './error-handlers': moduleMock('errorHandlers', protectMock),
+    });
+    modulesWithInstall = ['inputAnalysis', 'inputTracing', 'errorHandlers'];
+  });
+
+  it('calls the install() the specified modules', function () {
+    protectModule(coreMock).install();
+    modulesWithInstall.forEach((module) => {
+      expect(protectMock[module].install).to.have.been.calledOnce;
+    });
+  });
+});