@contrast/protect 1.0.1

package/lib/input-analysis/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+module.exports = function(core) {
+  const inputAnalysis = core.protect.inputAnalysis = {};
+
+  require('./handlers')(core);
+  require('./install/http')(core);
+  require('./install/fastify3')(core);
+
+  inputAnalysis.install = function() {
+    inputAnalysis.httpInstrumentation.install();
+    inputAnalysis.fastifyInstrumentation.install();
+  };
+
+  return inputAnalysis;
+};

package/lib/input-analysis/index.test.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const proxyquire = require('proxyquire');
+
+describe('protect input-analysis', function () {
+  let modulesMock, exportsStub, coreMock;
+  beforeEach(function () {
+    exportsStub = sinon.stub();
+    modulesMock = () => exportsStub();
+    coreMock = { protect: {} };
+  });
+
+  it('calls the required hooks', function () {
+    const inputAnalysis = proxyquire('.', {
+      './handlers': modulesMock,
+      './install/http': modulesMock,
+      './install/fastify3': modulesMock
+    });
+
+    expect(exportsStub).to.not.have.been.called;
+    expect(coreMock.protect).to.not.haveOwnProperty('inputAnalysis');
+    inputAnalysis(coreMock);
+    expect(coreMock.protect).to.haveOwnProperty('inputAnalysis');
+    expect(exportsStub).to.have.been.callCount(3);
+  });
+});

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

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * 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: 'framework-patch',
+      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;
+
+    if (!sourceContext) {
+      logger.debug('source context not available in fastify prevalidation hook');
+    } else {
+      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);
+      }
+    }
+    done();
+  }
+
+  const fastifyInstrumentation = inputAnalysis.fastifyInstrumentation = {
+    preValidationHook,
+    install,
+  };
+
+  return fastifyInstrumentation;
+};

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

@@ -0,0 +1,71 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const mocks = require('../../../../test/mocks');
+
+describe('protect input-analysis fastify intrumentation', function () {
+  let core;
+  let inputAnalysis;
+  let fastify;
+  let serverMock;
+  let reqMock;
+  let resMock;
+  let doneMock;
+
+  beforeEach(function () {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.scopes = mocks.scopes();
+    core.protect = mocks.protect();
+    core.depHooks = mocks.depHooks();
+    core.patcher = require('@contrast/patcher')(core);
+
+    reqMock = {
+      cookies: { foo: 'bar' },
+      params: { foo: 'bar' },
+      body: { foo: 'bar' },
+    };
+    resMock = {};
+    doneMock = sinon.stub();
+    serverMock = {
+      addHook: sinon.stub().yields(reqMock, resMock, doneMock),
+    };
+
+    const fastifyOrig = () => serverMock;
+    core.depHooks.resolve.callsFake(function(desc, cb) {
+      fastify = cb(fastifyOrig);
+    });
+
+    const fastifyInstr = require('./fastify3')(core);
+    inputAnalysis = core.protect.inputAnalysis;
+    fastifyInstr.install();
+  });
+
+  describe('preValidationHook', function () {
+    it('hook is added and calls appropriate analysis handlers', function () {
+      core.scopes.sources.run({ protect: {} }, () => {
+        fastify();
+      });
+
+      expect(serverMock.addHook).to.have.been.called;
+      expect(doneMock).to.have.been.called;
+      expect(core.logger.debug).not.to.have.been.called;
+
+      expect(inputAnalysis.handleUrlParams).to.have.been.called;
+      expect(inputAnalysis.handleCookies).to.have.been.called;
+      expect(inputAnalysis.handleParsedBody).to.have.been.called;
+    });
+    it('input analysis does not occur if there is no protect source context', function () {
+      fastify();
+      expect(doneMock).to.have.been.called;
+      expect(core.logger.debug).to.have.been.calledWith(
+        'source context not available in fastify prevalidation hook'
+      );
+
+      expect(inputAnalysis.handleUrlParams).to.not.have.been.called;
+      expect(inputAnalysis.handleCookies).to.not.have.been.called;
+      expect(inputAnalysis.handleParsedBody).to.not.have.been.called;
+    });
+  });
+});

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

@@ -0,0 +1,185 @@
+'use strict';
+
+const { Event } = require('@contrast/common');
+
+// Instruments http `Server` and `IncomingMessage` instances to support input
+// analysis in framework-agnostic manner.
+
+module.exports = function(core) {
+  const { protect: { inputAnalysis } } = core;
+  inputAnalysis.httpInstrumentation = new HttpInstrumentation(core);
+  return inputAnalysis.httpInstrumentation;
+};
+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.depHooks = core.depHooks;
+    this.messages = core.messages;
+    this.protect = core.protect;
+    this.makeSourceContext = this.protect.makeSourceContext;
+    this.maxBodySize = 16 * 1024 * 1024;
+    this.installed = false;
+  }
+
+  /**
+   * After checking whether the sensor is enabled, will set up `require` hooks
+   * for instrumenting both `http` and `https` modules when they load.
+   */
+  install() {
+    if (this.installed) {
+      return;
+    }
+
+    this.installed = true;
+    this.hookHttp();
+    this.hookHttps();
+  }
+
+  uninstall() {}
+
+  /**
+   * Sets hooks to instrument `http.Server.prototype`.
+   */
+  hookHttp() {
+    this.logger.debug('hooking library: http');
+    this.depHooks.resolve({ name: 'http' }, this.hookServer.bind(this));
+  }
+
+  /**
+   * Sets hooks to instrument `https.Server.prototype`.
+   */
+  hookHttps() {
+    this.logger.debug('hooking library: https');
+    this.depHooks.resolve({ name: 'https' }, this.hookServer.bind(this));
+  }
+
+  /**
+   * Instruments the `Server` prototype from `http(s)`. This patches `emit` and
+   * invokes the protect service to do analysis when appropriate.
+   *
+   * @param {Object} xport The http(s) module export
+   */
+  hookServer(xport) {
+    const self = this;
+
+    const {
+      Server: {
+        prototype: { emit }
+      }
+    } = xport;
+
+    xport.Server.prototype.emit = function(...args) {
+      const [type] = args;
+
+      if (type !== 'request') {
+        return emit.call(this, ...args);
+      }
+
+      const context = { instance: this, method: emit, args };
+      self.initiateRequestHandling(context);
+
+      return !!this._events[type];
+    };
+  }
+
+  /**
+   * Creates the sourceContext for the request and invokes the handler for
+   * inputs that are present in the 'incomingMessage' object at the time of
+   * the 'connect' event.
+   *
+   * @param {Object} context Function invocation context
+   */
+  initiateRequestHandling(fnContext) {
+    const {
+      instance,
+      method,
+      args,
+      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;
+
+    try {
+      const { messages, protect: { inputAnalysis } } = this; // the functions that do input analysis
+
+      // this must be invoked by the patching code using scope.sources.run({}, ...)
+      // 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()');
+        return;
+      }
+
+      store.protect = this.makeSourceContext(req, res);
+      const { reqData } = store.protect;
+
+      res.on('finish', () => 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
+      // into the store? after all, the inputs come from the store. mostly because
+      // they can really add up to a lot of data that isn't going to be used.
+      //
+      // how to replace result in resultsList, e.g., queries find something
+      // but then framework emits parsed queries? does this only matter for
+      // no-sql? index-lookup or hash?
+      //
+      // create inputs for this handler. we defer cookies until the framework
+      // parses them because there is no way to be certain of their formatting
+      // and encoding.
+      //
+      // the primary reason for this is to avoid passing the incomingMessage,
+      // req, to all the handlers allowing direct access to it and tightly
+      // coupling all handlers to an extensive collection of data.
+      const connectInputs = {
+        headers: HttpInstrumentation.removeCookies(reqData.headers),
+        uriPath: reqData.uriPath,
+        // 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;
+      }
+
+      block = inputAnalysis.handleConnect(store.protect, connectInputs);
+
+    } catch (err) {
+      this.logger.error({ err }, 'Error during input analysis');
+    }
+
+    if (!block) {
+      setImmediate(() => method.call(instance, ...args));
+    } else {
+      store.protect.block(...block);
+      this.logger.debug({ block }, 'request blocked by not emitting request event');
+    }
+  }
+
+  static removeCookies(headers) {
+    for (let i = 0; i < headers.length; i += 2) {
+      if (headers[i] === 'cookies') {
+        headers = headers.slice();
+        headers.splice(i, 2);
+        return headers;
+      }
+    }
+    return headers;
+  }
+}

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

@@ -0,0 +1,315 @@
+'use strict';
+
+const EventEmitter = require('events');
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+
+const aLib = require('@contrast/agent-lib');
+const Protect = require('../../..');
+const mocks = require('../../../../test/mocks');
+
+describe('protect input-analysis/http', function() {
+
+  describe('initialization', function() {
+    let core;
+    let httpInstr;
+
+    beforeEach(function() {
+      core = mocks.core();
+      core.depHooks = mocks.depHooks();
+      core.config = mocks.config();
+      core.logger = mocks.logger();
+      core.scopes = mocks.scopes();
+      core.patcher = mocks.patcher();
+      core.protect = Protect(core);
+      httpInstr = require('./http')(core);
+    });
+
+    it('should not be initialized after being required', function() {
+      expect(httpInstr.install).a('function');
+      expect(core.depHooks.install).not.called;
+      expect(core.depHooks.resolve).not.called;
+    });
+
+    it('should be initialized after being installed', function() {
+      httpInstr.install();
+      // once for http, once for https
+      expect(core.depHooks.resolve).callCount(2);
+      // no way to check the sensor state. probably should attach it to ?
+    });
+  });
+
+  describe('initiateRequestHandling()', function() {
+    let core;
+    let expectedRules;
+    let httpInstr;
+    let server;
+    let serverEmit;
+    let req, res;
+    let reqEmitter;
+    let context;
+    let expectedReqData;
+    let connectInputs;
+
+    beforeEach(function() {
+      //console.log(this.currentTest.title);
+      core = mocks.core();
+      core.depHooks = mocks.depHooks();
+      core.config = mocks.config();
+      Object.assign(core.config.protect.rules, {
+        'cmd-injection': { mode: 'monitor' }
+      });
+      core.logger = mocks.logger();
+      core.scopes = mocks.scopes();
+      core.patcher = mocks.patcher();
+      core.protect = Protect(core);
+
+      expectedRules = makeExpectedRules(core.config.protect.rules);
+
+      sinon.spy(core.protect.inputAnalysis, 'handleConnect');
+
+      httpInstr = require('./http')(core);
+      sinon.spy(httpInstr, 'makeSourceContext');
+      sinon.spy(httpInstr.scope, 'getStore');
+
+      // mock Server thing...
+      server = {};
+      serverEmit = sinon.stub();
+      server.prototype = { emit: serverEmit };
+
+      // mock req, res
+      reqEmitter = new EventEmitter();
+      req = {
+        url: '/',
+        method: 'GET',
+        rawHeaders: ['host', 'vogon.com', 'content-type', 'application/json'],
+        // this needs to look sort of like a real incoming message
+        emit: (...args) => reqEmitter.emit(...args),
+        _events: {},
+        socket: { _readableState: { autoDestroy: false } },
+        resume: sinon.stub(),
+      };
+      res = {
+        end: sinon.stub(),
+        writeHead: sinon.stub(),
+        headersSent: false,
+        on: sinon.stub(),
+      };
+
+      // setup the context required
+      context = {
+        instance: server,
+        method: serverEmit,
+        args: ['request', req, res]
+      };
+
+      // setup a few expected results. these can be modified as needed by
+      // different tests.
+      expectedReqData = {
+        method: req.method,
+        headers: req.rawHeaders.map((h, i) => i & 1 ? h : h.toLowerCase()),
+        uriPath: '/',
+        queries: '',
+        contentType: '',
+        standardUrlParsing: false,
+      };
+      connectInputs = {
+        method: expectedReqData.method,
+        headers: expectedReqData.headers,
+        uriPath: expectedReqData.uriPath,
+      };
+    });
+
+    //
+    // make sure basic things are as expected
+    //
+    function doBasicChecks(expectedReqData) {
+      // scope.run() call invokes scope.getStore(), so it will be called once to execute
+      // the test and once more unless no rules were in effect.
+      if (core.protect.rules.agentLibRulesMask !== 0) {
+        expect(httpInstr.scope.getStore).callCount(2);
+        expect(httpInstr.makeSourceContext).calledOnceWith(req, res);
+      } else {
+        // source context wasn't available, so
+        expect(httpInstr.scope.getStore).callCount(1);
+        return;
+      }
+
+      const sourceContext = httpInstr.makeSourceContext.returnValues[0];
+      const {
+        block, exclusions, findings, reqData, rules, virtualPatches
+      } = sourceContext;
+
+      /* eslint-disable newline-per-chained-call */
+      expect(block).a('function');
+      expect(exclusions).an('array').eql([]);
+      expect(findings).an('object').eql({
+        trackRequest: false, securityException: undefined, bodyType: undefined, resultsMap: {}
+      });
+      expect(reqData.method).equal(expectedReqData.method);
+      expect(reqData.uriPath).equal(expectedReqData.uriPath);
+      expect(reqData.headers).eql(expectedReqData.headers);
+      expect(rules).an('object').eql(expectedRules);
+      expect(virtualPatches).an('array').eql([]);
+
+      return sourceContext;
+    }
+
+    // i don't see how to unit test this; xport.Server.prototype.emit()
+    // i.e., the real patching function. i think verifying that function
+    // will require an integration test of some sort.
+    // it('should handle requests on http, https, and http2', ...)
+
+    // initiateRequestHandling() sets up everything but the inputs for all analysis
+    // of this request.
+    it('works as expected', function(done) {
+      // this is called here because other tests will modify the default data setup in
+      // beforeEach().
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      const sourceContext = doBasicChecks(expectedReqData);
+
+      // and finally, handleConnect() should have been called with context
+      // and input.
+      expect(core.protect.inputAnalysis.handleConnect).calledOnceWith(sourceContext, connectInputs);
+
+      // the real emitter is called via setImmediate() so give it a chance to run.
+      expect(serverEmit).callCount(0);
+      setImmediate(function() {
+        expect(serverEmit).callCount(1);
+        done();
+      });
+    });
+
+    it('debug logs if no async context', function() {
+      // this is called here because other tests will modify the default data setup in
+      // beforeEach().
+      httpInstr.scope.getStore.restore();
+      sinon.stub(httpInstr.scope, 'getStore').returns(undefined);
+      core.logger.debug = sinon.stub();
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      expect(core.logger.debug).calledOnceWith('cannot acquire store for initiateRequestHandling()');
+    });
+
+    it('error logs on exceptions', function() {
+      const err = new Error('sometimes things do not work out');
+      const { inputAnalysis } = core.protect;
+      inputAnalysis.handleConnect.restore();
+      sinon.stub(inputAnalysis, 'handleConnect').throws(err);
+      // simulate an incoming request to the server.
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      expect(core.logger.error).calledOnceWith({ err }, 'Error during input analysis');
+    });
+
+    it('connectInputs will contain not a cookies header', function(done) {
+      const withoutCookies = req.rawHeaders.slice();
+      req.rawHeaders.push('COOKIES', 'this;that;the other;thing');
+      expectedReqData.headers.push('cookies', 'this;that;the other;thing');
+
+      // simulate an incoming request to the server.
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      const sourceContext = doBasicChecks(expectedReqData);
+
+      // and finally, handleConnect() should have been called with sourceContext and connectInput.
+      // the cookies header should not be present because protect waits until the framework has
+      // decoded the cookies before scoring them.
+      connectInputs.headers = withoutCookies;
+      expect(core.protect.inputAnalysis.handleConnect).calledOnceWith(sourceContext, connectInputs);
+
+      // the real emitter is called via setImmediate() so give it a chance
+      // to run.
+      expect(serverEmit).callCount(0);
+      setImmediate(function() {
+        expect(serverEmit).callCount(1);
+        done();
+      });
+    });
+
+    it('does not analyze the request when no rules are in effect', function() {
+      // kind of hacky reset on the rules
+      core.protect.rules = {
+        agentLibRulesMask: 0,
+        agentLibRules: {},
+        agentRules: {},
+      };
+      expectedRules = core.protect.rules;
+      core.logger.debug = sinon.stub();
+
+      // simulate an incoming request to the server.
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      doBasicChecks(expectedReqData);
+
+      expect(core.logger.debug).calledOnceWith('no agent-lib rules are enabled, not checking request');
+    });
+
+    it('does not emit the original event when blocked', function(done) {
+      req.url = '/need/<script%20this&that';
+      const sourceContext = core.protect.makeSourceContext(req, res);
+      sourceContext.rules.agentLibRules['reflected-xss'] = { mode: 'block' };
+      sourceContext.rules.agentLibRulesMask |= aLib.constants.RuleType['reflected-xss'];
+      sourceContext.block = sinon.stub();
+      core.logger.debug = sinon.stub();
+
+
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      const block = ['block', 'reflected-xss'];
+
+      expect(core.protect.inputAnalysis.handleConnect).callCount(1).returned(block);
+      expect(core.logger.debug).calledWith({ block }, 'request blocked by not emitting request event');
+      setImmediate(function() {
+        expect(serverEmit).callCount(0);
+        done();
+      });
+    });
+
+    it('does not handle a request body when it is not JSON', function(done) {
+      req.rawHeaders = ['Content-Type', 'multipart/form-data'];
+      expectedReqData.headers = ['content-type', 'multipart/form-data'];
+      expectedReqData.contentType = 'multipart/form-data';
+
+      // simulate an incoming request to the server.
+      httpInstr.scope.run(httpInstr.scope, () => httpInstr.initiateRequestHandling(context));
+
+      const sourceContext = doBasicChecks(expectedReqData);
+
+      // and finally, handleConnect() should have been called with sourceContext and connectInput.
+      connectInputs.headers = expectedReqData.headers;
+      expect(core.protect.inputAnalysis.handleConnect).calledOnceWith(sourceContext, connectInputs);
+
+      expect(serverEmit).callCount(0);
+      setImmediate(function() {
+        expect(serverEmit).callCount(1);
+        done();
+      });
+    });
+  });
+});
+
+function makeExpectedRules(rules) {
+  const { RuleType } = aLib.constants;
+  const agentLibRules = {};
+  const agentRules = {};
+  let agentLibRulesMask = 0;
+
+  for (const rule in rules) {
+    if (!(rule in RuleType)) {
+      // it's a little random, but if the rule isn't an agent-lib rule, presume
+      // that it's an agent rule.
+      if (rule !== 'disabled_rules') {
+        agentRules[rule] = { mode: undefined };
+      }
+      continue;
+    }
+    agentLibRules[rule] = rules[rule];
+    agentLibRulesMask |= RuleType[rule];
+  }
+
+  return { agentLibRules, agentLibRulesMask, agentRules };
+
+}

package/lib/input-tracing/constants.js

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