@contrast/protect 1.0.1

package/lib/make-source-context.test.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+
+const mocks = require('../../test/mocks');
+
+// rules in config
+const rulesCfg = [
+  { id: 'bot-blocker', where: 'agent-lib-input' },
+  { id: 'cmd-injection', where: 'agent-lib-input' },
+  { id: 'cmd-injection-command-backdoors', where: 'agent' },
+  { id: 'cmd-injection-semantic-chained-commands', where: 'agent' },
+  { id: 'cmd-injection-semantic-dangerous-paths', where: 'agent' },
+  { id: 'ip-denylist', where: 'agent' },
+  { id: 'method-tampering', where: 'agent-lib-input' },
+  { id: 'nosql-injection-mongo', where: 'agent-lib-input' },
+  { id: 'path-traversal', where: 'agent-lib-input' },
+  { id: 'reflected-xss', where: 'agent-lib-input' },
+  { id: 'sql-injection', where: 'agent-lib-input' },
+  { id: 'ssjs-injection', where: 'agent-lib-input' },
+  { id: 'virtual-patch', where: 'agent' },
+  { id: 'untrusted-deserialization', where: 'agent' },
+  { id: 'unsafe-file-upload', where: 'agent-lib-input' },
+  { id: 'xxe', where: 'agent' },
+];
+
+const rules = rulesCfg.map((r) => r.id);
+const agentLibRules = rulesCfg.filter((r) => r.where === 'agent-lib-input').map((r) => r.id);
+const agentRules = rulesCfg.filter((r) => r.where !== 'agent-lib-input').map((r) => r.id);
+
+/* eslint-disable newline-per-chained-call */
+
+describe('protect make-source-context', function() {
+  let core;
+
+  beforeEach(function() {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.config = mocks.config();
+    core.scopes = mocks.scopes();
+    core.config.protect.rules = makeProtectRulesConfig(rules);
+    core.scopes = mocks.scopes();
+    require('../../protect')(core);
+  });
+
+  it('mock core.config.protect.rules are initialized correctly', function() {
+    // shorthand
+    const protectRules = core.config.protect.rules;
+    for (const ruleId of rules) {
+      expect(protectRules).property(ruleId).eql({ mode: 'monitor' });
+    }
+  });
+
+  it('core.protect.rules is initialized correctly from mock config', function() {
+    const { protect } = core;
+
+    expect(protect).property('agentLib').an('object');
+    expect(protect.agentLib).property('RuleType').eql({
+      'unsafe-file-upload': 1,
+      'path-traversal': 2,
+      'reflected-xss': 4,
+      'sql-injection': 8,
+      'cmd-injection': 16,
+      'nosql-injection-mongo': 32,
+      'bot-blocker': 64,
+      'ssjs-injection': 128,
+      'method-tampering': 256,
+    });
+    expect(protect.agentLib).property('MongoQueryType');
+    expect(protect.agentLib).property('DbType');
+
+    expect(protect).property('rules').an('object');
+    const { rules } = protect;
+
+    expect(rules).property('agentLibRules').keys(agentLibRules);
+    expect(rules).property('agentLibRulesMask').equal(511);
+    expect(rules).property('agentRules').keys(agentRules);
+  });
+
+  describe('makeSourceContext() for rules', function() {
+    const alRules = ['reflected-xss', 'path-traversal', 'method-tampering'];
+    const aRules = ['virtual-patch'];
+    const aSlice = aRules.at.length > 1 ? 1 : 0;
+    const tests = [
+    //                          config, agent-lib, agent
+      { desc: 'handles no rules', rules: [], alr: [], ar: [] },
+      { desc: 'handles all rules', rules, alr: agentLibRules, ar: agentRules },
+      { desc: 'handles some agent-lib rules', rules: alRules, alr: alRules, ar: [] },
+      { desc: 'handles some agent rules', rules: aRules, alr: [], ar: aRules },
+      { desc: 'handle some of both rules', rules: alRules.concat(aRules), alr: alRules, ar: aRules },
+      { desc: 'handles a single agent-lib rule', rules: alRules.slice(1), alr: alRules.slice(1), ar: [] },
+      { desc: 'handles a single agent rule', rules: aRules.slice(aSlice), alr: [], ar: aRules.slice(aSlice) },
+    ];
+
+    tests.forEach((t) => {
+      it(t.desc, function() {
+        const core = mocks.core();
+        core.patcher = mocks.patcher();
+        core.logger = mocks.logger();
+        core.scopes = mocks.scopes();
+        core.config = mocks.config();
+        // make the rules config based on the test's rules
+        core.config.protect.rules = makeProtectRulesConfig(t.rules);
+        core.scopes = mocks.scopes();
+
+        // create protect with the rules config
+        require('../../protect')(core);
+        const { makeSourceContext } = core.protect;
+        const [req, res] = makeReqRes({}, {});
+
+        // this is what is really being tested.
+        const sc = makeSourceContext(req, res);
+
+        // make expected source context
+        const expectedAlr = {};
+        let alrm = 0;
+        t.alr.forEach((alr) => {
+          expectedAlr[alr] = { mode: 'monitor' };
+          alrm |= core.protect.agentLib.RuleType[alr];
+        });
+        const expectedAr = {};
+        t.ar.forEach((ar) => expectedAr[ar] = { mode: 'monitor' });
+
+        // check everything
+        expect(sc.block).a('function');
+        expect(sc.rules).eql({
+          agentLibRules: expectedAlr,
+          agentLibRulesMask: alrm,
+          agentRules: expectedAr,
+        });
+        expect(sc.exclusions).eql([]);
+        expect(sc.virtualPatches).eql([]);
+        expect(sc.findings).eql({
+          trackRequest: false,
+          securityException: undefined,
+          bodyType: undefined,
+          resultsMap: Object.create(null),
+        });
+      });
+    });
+  });
+
+  describe('makeSourceContext() for req, res', function() {
+    const rules = ['reflected-xss'];
+    const expectedAlr = { 'reflected-xss': { mode: 'monitor' } };
+    const expectedAlrm = 4; // RuleType['reflected-xss']
+    const expectedAr = {};
+
+    const tests = [
+      { desc: 'works with unmodified req', req: {}, res: {} },
+      { desc: 'handles an uppercase header name', req: { rawHeaders: ['Accept', '*'] }, res: {} },
+      { desc: 'does not modify a header value', req: { rawHeaders: ['Accept', 'TEXT/HTmL'] }, res: {} },
+      { desc: 'handles an empty url', req: { url: '' }, res: {} },
+      { desc: 'handles search params', req: { url: '/mimsy?borogroves' }, res: {} },
+      { desc: 'handles only search params', req: { url: '?alice' }, res: {} },
+      { desc: 'detects multipart content-type', req: { rawHeaders: ['Content-type', 'multipart/x-www-form-urlencoded'] }, res: {} },
+      { desc: 'blocks when headers not sent', req: {}, res: { writeHead: sinon.stub(), end: sinon.stub() } },
+      { desc: 'blocks when headers sent', req: {}, res: { writeHead: sinon.stub(), end: sinon.stub(), headersSent: true } },
+    ];
+
+    tests.forEach((t) => {
+      it(t.desc, function() {
+        const core = mocks.core();
+        core.patcher = mocks.patcher();
+        core.logger = mocks.logger();
+        core.scopes = mocks.scopes();
+        core.config = mocks.config();
+        core.config.protect.rules = makeProtectRulesConfig(rules);
+        core.scopes = mocks.scopes();
+        // create protect with the rules config
+        require('../../protect')(core);
+        const { makeSourceContext } = core.protect;
+
+        const [req, res] = makeReqRes(t.req, t.res);
+
+        // this is what is really being tested.
+        const sc = makeSourceContext(req, res);
+
+        // default to setting headers but not including a content-type
+        let contentType = '';
+        if (!t.req.rawHeaders) {
+          // the test doesn't set the headers so they are the default
+          contentType = 'application/x-www-form-urlencoded';
+        } else if (t.req.rawHeaders[t.req.rawHeaders.length - 1].startsWith('multipart')) {
+          // the test does set the content-type header (inferred)
+          contentType = t.req.rawHeaders[t.req.rawHeaders.length - 1];
+        }
+        const headers = req.rawHeaders.map((h, ix) => ix & 1 ? h : h.toLowerCase());
+        const expectedReqData = {
+          method: 'get',
+          headers,
+          uriPath: '/',
+          queries: '',
+          contentType,
+          standardUrlParsing: false,
+        };
+        if (t.req.rawHeaders) {
+          expectedReqData.headers = t.req.rawHeaders.map((h, i) => {
+            if (i & 1 && h.startsWith('multipart')) {
+              expectedReqData.contentType = h;
+            }
+            return i & 1 ? h : h.toLowerCase();
+          });
+        }
+        if (t.req.url !== undefined) {
+          expectedReqData.uriPath = t.req.url;
+          expectedReqData.queries = '';
+          const ix = t.req.url.indexOf('?');
+          if (ix >= 0) {
+            expectedReqData.uriPath = t.req.url.slice(0, ix);
+            expectedReqData.queries = t.req.url.slice(ix + 1);
+          }
+        }
+
+        // check that req and res make the expected abstract request
+        expect(sc).property('reqData').eql(expectedReqData);
+
+        // if a block test, does it work as expected?
+        if (t.res.writeHead) {
+          sc.block('mode', 'reflected-xss');
+          if (!t.res.headersSent) {
+            expect(t.res.writeHead.callCount).equal(1);
+          } else {
+            expect(t.res.writeHead.callCount).equal(0);
+          }
+          expect(t.res.end.callCount).equal(1);
+        }
+
+        // check constant items
+        expect(sc.block).a('function');
+        expect(sc.rules).eql({
+          agentLibRules: expectedAlr,
+          agentLibRulesMask: expectedAlrm,
+          agentRules: expectedAr,
+        });
+        expect(sc.exclusions).eql([]);
+        expect(sc.virtualPatches).eql([]);
+        expect(sc.findings).eql({
+          trackRequest: false,
+          securityException: undefined,
+          bodyType: undefined,
+          resultsMap: Object.create(null)
+        });
+      });
+    });
+
+  });
+});
+
+//
+// make a req and res pair
+//
+function makeReqRes(req = {}, res = {}) {
+  const defaultReq = {
+    method: 'get',
+    url: '/',
+    rawHeaders: getRawHeaders(),
+  };
+
+  const defaultRes = {
+    headersSent: false,
+    writeHead() {},
+    end() {},
+  };
+
+  return [
+    Object.assign({}, defaultReq, req),
+    Object.assign({}, defaultRes, res),
+  ];
+}
+
+function getRawHeaders() {
+  return [
+    'accept', 'text/html',
+    'accept-encoding', 'gzip, deflate, br',
+    'user-agent', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.',
+    'content-type', 'application/x-www-form-urlencoded'
+  ];
+}
+
+//
+// create the config for protect's rules
+//
+function makeProtectRulesConfig(rules, mode) {
+  if (mode === undefined) {
+    mode = 'monitor';
+  }
+  if (['monitor', 'block', 'off'].indexOf(mode) < 0) {
+    throw new Error('valid modes are monitor, block, and off');
+  }
+  const rulesOptions = {};
+  for (const ruleId of rules) {
+    rulesOptions[ruleId] = { mode };
+  }
+
+  return rulesOptions;
+}

package/lib/security-exception.js

@@ -0,0 +1,12 @@
+'use strict';
+
+module.exports = class SecurityException extends Error {
+  static create() {
+    const err = new SecurityException('SecurityException');
+    return err;
+  }
+
+  static isSecurityException(err) {
+    return err instanceof SecurityException;
+  }
+};

package/lib/throw-security-exception.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const Domain = require('async-hook-domain');
+const securityException = require('./security-exception');
+
+module.exports = function(core) {
+  const { logger, protect } = core;
+
+  function throwSecurityException(sourceContext) {
+    if (!sourceContext) return;
+
+    const {
+      findings: {
+        securityException: [mode, ruleId]
+      }
+    } = sourceContext;
+
+    const err = securityException.create();
+
+    new Domain(() => {
+      sourceContext.block(mode, ruleId);
+    });
+
+    logger.info({ err, mode, ruleId }, 'throwing security exception');
+
+    throw err;
+  }
+
+  return protect.throwSecurityException = throwSecurityException;
+};

package/lib/throw-security-exception.test.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const proxyquire = require('proxyquire');
+const mocks = require('../../test/mocks');
+
+describe('protect throw-security-exception', function() {
+  let Domain;
+  let core;
+  let protect;
+  let sourceContext;
+
+  beforeEach(function() {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    protect = core.protect = mocks.protect();
+    sourceContext = {
+      block: sinon.stub(),
+      findings: {
+        securityException: ['block', 'cmd-injection']
+      }
+    };
+    Domain = sinon.stub().callsFake(function(cb) {
+      cb();
+    });
+    proxyquire('./throw-security-exception', {
+      'async-hook-domain': Domain
+    })(core);
+  });
+
+  it('domain listener will block in response to thrown exception', function() {
+    const { findings: { securityException } } = sourceContext;
+    expect(function() {
+      protect.throwSecurityException(sourceContext);
+    }).to.throw('SecurityException');
+    expect(sourceContext.block).calledWith(...securityException);
+    expect(core.logger.info).to.have.been.calledWith(sinon.match({
+      ruleId: 'cmd-injection',
+      mode: 'block',
+    }));
+  });
+
+  it('method is noop if source context is not provided', function() {
+    expect(function() {
+      protect.throwSecurityException();
+      expect(sourceContext.block).to.not.have.been.called;
+    }).not.to.throw('SecurityException');
+  });
+});

package/lib/utils.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Get a symbol parameter value on the given object. The function should be
+ * used with a `target` for which we are sure that the Symbol property we need is set before
+ * any eventual duplicating Symbol properties. In case of duplicating Symbol properties
+ * we will always get the one that's set first.
+ * @param   {Object} target built outgoing response
+ * @param   {String} symbolName full symbol stringified
+ * @returns {Object}        value of the requested symbol property
+ */
+function getSymbolProperty(target, symbolName) {
+  if (!target) return;
+  for (const sym of Object.getOwnPropertySymbols(target)) {
+    if (sym.toString() === `Symbol(${symbolName})`) {
+      return target[sym];
+    }
+  }
+}
+
+/**
+ * simpleTraverse() walks an object and calls a user function for each key
+ * and string value. It is a "simple traverse" in that it
+ * 1) doesn't make value callbacks unless the value is a non-empty string
+ * 2) it only recognizes items that can be expressed in JSON, i.e., POJO
+ * and arrays.
+ * 3) it doesn't make callbacks for array indexes (though they appear in
+ * the path). array indexes are always numeric and are not a threat.
+ *
+ * N.B. the path array that is passed to the callback is a dynamic path; new
+ * keys are pushed and popped onto the path as simpleTraverse() walks the
+ * object. in order to capture the path at the time of the callback, the
+ * callback must copy the array, e.g., `path.slice()`, in order to "freeze"
+ * it at the time of the callback. the reason for this is that most keys/values
+ * are not going to be of interest, and there is no reason to create a new array
+ * unless the key/value is of interest.
+ *
+ * @param {Object} obj the object to traverse
+ * @param {Function} cb(path, type, value) is called for each non-array-index key
+ * and string value. It is not called for non-string or empty-string Values.
+ *   path {[String]} the path prior to the 'Key' or 'Value'; includes array indexes.
+ *   type {String} 'Key' or 'Value'
+ *   value {String} the Key or Leaf string
+ *
+ */
+function simpleTraverse(obj, cb) {
+  if (typeof obj !== 'object' || obj === null) {
+    return;
+  }
+  const path = [];
+  /* eslint-disable complexity */
+  function traverse(obj) {
+    const isArray = Array.isArray(obj);
+    for (const k in obj) {
+      if (isArray) {
+        // if it is an array, store each index in path but don't call the
+        // callback on the index itself as they are just numeric strings.
+        path.push(k);
+        if (typeof obj[k] === 'object' && obj[k] !== null) {
+          traverse(obj[k]);
+        } else if (typeof obj[k] === 'string' && obj[k]) {
+          cb(path, 'Value', obj[k]);
+        }
+        path.pop();
+      } else if (typeof obj[k] === 'object' && obj[k] !== null) {
+        cb(path, 'Key', k);
+        path.push(k);
+        traverse(obj[k]);
+        path.pop();
+      } else {
+        cb(path, 'Key', k);
+        // only callback if the value is a non-empty string
+        if (typeof obj[k] === 'string' && obj[k]) {
+          path.push(k);
+          cb(path, 'Value', obj[k]);
+          path.pop();
+        }
+      }
+    }
+  }
+
+  traverse(obj);
+}
+
+module.exports = {
+  getSymbolProperty,
+  simpleTraverse,
+};

package/lib/utils.test.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const { expect } = require('chai');
+
+describe('protect utils', function () {
+  let getSymbolProperty, target;
+
+  beforeEach(function() {
+    ({ getSymbolProperty } = require('./utils'));
+  });
+
+  it('returns `undefined` if the target is falsey', function() {
+    [null, '', undefined].forEach((target) => {
+      expect(getSymbolProperty(target, 'test')).to.equal(undefined);
+    });
+  });
+
+  it('returns `undefined` if the target does not have the required symbol', function() {
+    target = {
+      foo: 'test',
+      [Symbol('not foo')]: 'test'
+    };
+
+    const result = getSymbolProperty(target, 'foo');
+
+    expect(result).to.equal(undefined);
+  });
+
+  it('returns value of the required Symbol property', function() {
+    target = {
+      foo: 'normal property',
+      [Symbol('not foo')]: 'another symbol',
+      [Symbol('foo')]: 'searched value'
+    };
+
+    const result = getSymbolProperty(target, 'foo');
+
+    expect(result).to.equal('searched value');
+  });
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@contrast/protect",
+  "version": "1.0.1",
+  "description": "Contrast service providing framework-agnostic Protect support",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
+  "files": [
+    "lib/"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "contrast-transpile": "lib/cli-rewriter.js"
+  },
+  "engines": {
+    "npm": ">= 8.4.0",
+    "node": ">= 14.15.0"
+  },
+  "scripts": {
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {
+    "@babel/template": "^7.16.7",
+    "@babel/types": "^7.16.8",
+    "@contrast/agent-lib": "^4.2.0",
+    "@contrast/common": "1.0.0",
+    "@contrast/core": "1.0.0",
+    "@contrast/esm-hooks": "1.0.0",
+    "async-hook-domain": "^2.0.4",
+    "builtin-modules": "^3.2.0"
+  }
+}