@contrast/protect 1.0.1

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

@@ -0,0 +1,117 @@
+'use strict';
+
+module.exports = function(core) {
+  const { protect: { agentLib, inputTracing, throwSecurityException } } = core;
+
+  /**
+   * Util for pulling results from context for the particular rule id
+   * @param {string} ruleId rule id
+   * @param {object} context async storage data for protect
+   * @returns {AnalysisResult[]}
+   */
+  inputTracing.getResultsByRuleId = function(ruleId, context) {
+    return context.findings.resultsMap[ruleId];
+  };
+
+  /**
+   * Given a ruleId and an analysis function, wrap the analysis function
+   * with common setup and post-processing code.
+   */
+  inputTracing.handlerFactory = function(ruleId, analysisFn) {
+    /**
+     * This is the common API for INPUT TRACING instrumentation.
+     * @param {object} sourceContext
+     * @param {object} sinkContext
+     */
+    return function(sourceContext, sinkContext) {
+      if (sourceContext.rules.agentLibRules[ruleId].mode === 'off') {
+        return;
+      }
+
+      const results = inputTracing.getResultsByRuleId(ruleId, sourceContext);
+      if (!results) return;
+
+      for (const result of results) {
+        const findings = analysisFn(result, sinkContext);
+
+        if (findings) {
+          result.details.push({ sinkContext, findings });
+
+          if (sourceContext.rules.agentLibRules[ruleId].mode === 'block') {
+            result.blocked = true;
+            const blockInfo = ['block', ruleId];
+            sourceContext.findings.securityException = blockInfo;
+            throwSecurityException(sourceContext);
+          }
+        }
+      }
+    };
+  };
+
+  inputTracing.handlePathTraversal = inputTracing.handlerFactory(
+    'path-traversal',
+    function(result, sinkContext) {
+      const idx = sinkContext.value.indexOf(result.value);
+      return idx !== -1 ? { path: sinkContext.value } : null;
+    }
+  );
+
+  inputTracing.handleCommandInjection = inputTracing.handlerFactory(
+    'cmd-injection',
+    function(result, sinkContext) {
+      const inputIndex = sinkContext.value.indexOf(result.value);
+      if (inputIndex !== -1) {
+        return agentLib.checkCommandInjectionSink(
+          inputIndex,
+          result.value.length,
+          sinkContext.value,
+        );
+      }
+    }
+  );
+
+  inputTracing.handleSqlInjection = inputTracing.handlerFactory(
+    'sql-injection',
+    function(result, sinkContext) {
+      let analysis = null;
+
+      const inputIndex = sinkContext.value.indexOf(result.value);
+      // if the user input is not in the sink input, there is nothing to do.
+      if (inputIndex === -1) {
+        return analysis;
+      }
+
+      if (inputIndex === 0 && sinkContext.value === result.value) {
+        analysis = {
+          startIndex: 0,
+          endIndex: result.value.length - 1,
+          overrunIndex: 0,
+          boundaryIndex: 0,
+        };
+      } else {
+        analysis = agentLib.checkSqlInjectionSink(
+          inputIndex,
+          result.value.length,
+          2,
+          sinkContext.value,
+        );
+      }
+
+      return analysis;
+    }
+  );
+
+  inputTracing.nosqlInjectionMongo = inputTracing.handlerFactory(
+    'nosql-injection-mongo', require('./nosql-injection-mongo')
+  );
+
+  inputTracing.ssjsInjection = inputTracing.handlerFactory(
+    'ssjs-injection',
+    function(results, sinkContext) {
+      return null;
+    }
+  );
+
+  return inputTracing;
+};
+

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

@@ -0,0 +1,395 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+
+describe('protect input-tracing handlers', function() {
+  let handlers;
+
+  // each test should be asserting this at least
+  const TEST_DESCRIPTION = 'captures findings and sinkContext in result.details array';
+
+  // for additional assertions that might happen in tests, add to description
+  function makeTestDescription(blocks) {
+    const addl = blocks ? ' and blocks when in BLOCK mode' : '';
+    return `${TEST_DESCRIPTION}${addl}`;
+  }
+
+  function makeSourceContext(resultsList, rules) {
+    const e = new Error('SecurityException');
+    const resultsMap = Object.create(null);
+    if (resultsList) {
+      for (const result of resultsList) {
+        if (!resultsMap[result.ruleId]) {
+          resultsMap[result.ruleId] = [];
+        }
+        resultsMap[result.ruleId].push(result);
+      }
+    }
+
+    return {
+      rules: {
+        agentLibRules: {
+          ['cmd-injection']: { mode: 'monitor' },
+          ['path-traversal']: { mode: 'monitor' },
+          ['sql-injection']: { mode: 'monitor' },
+          ['ssjs-injection']: { mode: 'monitor' },
+          ...(rules || {})
+        }
+      },
+      findings: {
+        trackRequest: true,
+        resultsMap,
+      },
+      block: sinon.stub().throws(e)
+    };
+  }
+
+  before(function() {
+    const mocks = require('../../../../test/mocks');
+
+    const core = mocks.core();
+    core.logger = mocks.logger();
+    core.protect = mocks.protect();
+
+    handlers = require('.')(core);
+  });
+
+  describe('getResultsByRuleId()', function() {
+    [
+      { findings: { resultsMap: {} } },
+      { findings: { resultsMap: { 'not foo': [{ ruleId: 'not foo' }] } } },
+    ].forEach((sourceContext) => {
+      it(`returns null when context has missing keys or empty results. context = ${JSON.stringify(sourceContext)}`, function() {
+        expect(handlers.getResultsByRuleId('foo', sourceContext)).eql(undefined);
+      });
+    });
+
+    it('returns all items from context\'s resultsList which match provided ruldId', function() {
+      const context = {
+        findings: {
+          resultsMap: {
+            'foo': [
+              { ruleId: 'foo', tag: 1 },
+              { ruleId: 'foo' },
+            ],
+            'not foo': [
+              { ruleId: 'not foo' }
+            ],
+          }
+        }
+      };
+      expect(handlers.getResultsByRuleId('foo', context)).eql([
+        { ruleId: 'foo', tag: 1 },
+        { ruleId: 'foo' }
+      ]);
+    });
+
+    it('noops when there are no matching ruleId values', function() {
+      const sourceContext = makeSourceContext([
+        {
+          ruleId: 'foo'
+        }
+      ]);
+      const sinkContext = {
+        name: 'bar',
+        value: 'baz',
+      };
+
+      handlers.handlePathTraversal(sourceContext, sinkContext);
+      handlers.handleCommandInjection(sourceContext, sinkContext);
+      handlers.handleSqlInjection(sourceContext, sinkContext);
+
+      expect(sourceContext.findings.resultsMap['foo'][0].details).undefined;
+    });
+  });
+
+  describe('handlePathTraversal()', function() {
+    const sinkContextPositive = {
+      name: 'fs.readFileSync',
+      value: './../../../etc/passwd',
+      stack: []
+    };
+    const sinkContextNegative = {
+      name: 'fs.readFileSync',
+      value: 'index.js',
+      stack: []
+    };
+    const findings = {
+      path: './../../../etc/passwd',
+    };
+
+    [
+      {
+        blocks: false,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'path-traversal',
+            value: '../../../etc/passwd',
+            details: [],
+          }]
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          },
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          }
+        ]
+      },
+      {
+        blocks: true,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'path-traversal',
+            value: '../../../etc/passwd',
+            details: [],
+          }],
+          {
+            ['path-traversal']: { mode: 'block' }
+          }
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          },
+        ]
+      },
+      {
+        blocks: false,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'path-traversal',
+            value: '../../../etc/passwd',
+            details: [],
+          }],
+          {
+            ['path-traversal']: { mode: 'off' }
+          }
+        ),
+        expectedDetails: []
+      }
+    ].forEach(({ blocks, sourceContext, expectedDetails }) => {
+      it(makeTestDescription(blocks), function() {
+        const testFn = () => {
+          handlers.handlePathTraversal(sourceContext, sinkContextPositive);
+          handlers.handlePathTraversal(sourceContext, sinkContextPositive);
+          handlers.handlePathTraversal(sourceContext, sinkContextNegative);
+        };
+
+        const test = expect(testFn);
+        blocks ? test.to.throw('SecurityException') : test.not.to.throw();
+
+        expect(sourceContext.findings.resultsMap['path-traversal'][0].details).to.eql(expectedDetails);
+      });
+    });
+  });
+
+  describe('handleCmdInjection()', function() {
+    const sinkContextPositive = {
+      name: 'child_process.execSync',
+      value: 'ls; cat /etc/passwd',
+      stack: [],
+    };
+    const sinkContextNegative = {
+      name: 'child_process.execSync',
+      value: 'foo',
+      stack: []
+    };
+    const findings = {
+      boundaryIndex: 2,
+      endIndex: 19,
+      overrunIndex: 4,
+      startIndex: 2,
+    };
+
+    [
+      {
+        blocks: false,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'cmd-injection',
+            value: '; cat /etc/passwd',
+            details: [],
+          }]
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          },
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          }
+        ]
+      },
+      {
+        blocks: true,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'cmd-injection',
+            value: '; cat /etc/passwd',
+            details: [],
+          }], {
+            ['cmd-injection']: { mode: 'block' }
+          }
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          },
+        ]
+      },
+      {
+        blocks: false,
+        sourceContext: makeSourceContext(
+          [{
+            ruleId: 'cmd-injection',
+            value: '; cat /etc/passwd',
+            details: [],
+          }], {
+            ['cmd-injection']: { mode: 'off' }
+          }
+        ),
+        expectedDetails: []
+      }
+    ].forEach(({ blocks, sourceContext, expectedDetails }) => {
+      it(makeTestDescription(blocks), function() {
+        const testFn = () => {
+          handlers.handleCommandInjection(sourceContext, sinkContextPositive);
+          handlers.handleCommandInjection(sourceContext, sinkContextPositive);
+          handlers.handleCommandInjection(sourceContext, sinkContextNegative);
+        };
+
+        const test = expect(testFn);
+        blocks ? test.to.throw('SecurityException') : test.not.to.throw();
+
+        const cmdiResults = sourceContext.findings.resultsMap['cmd-injection'];
+
+        expect(cmdiResults[0].details).to.eql(expectedDetails);
+      });
+    });
+  });
+
+  describe('handleSqlInjection()', function() {
+    const sinkContextPositive = {
+      name: 'mysql.query',
+      value: 'select * from foo where col = "" and 1 = 1; --',
+      stack: [],
+    };
+    const sinkContextNegative = {
+      name: 'mysql.query',
+      value: 'select 1',
+      stack: [],
+    };
+    const findings = {
+      boundaryIndex: 30,
+      endIndex: 46,
+      overrunIndex: 31,
+      startIndex: 31,
+    };
+
+    [
+      {
+        blocks: false,
+        findings,
+        sourceContext: makeSourceContext(
+          [
+            {
+              ruleId: 'sql-injection',
+              value: '" and 1 = 1; --',
+              details: [],
+            }
+          ]
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          },
+          {
+            sinkContext: sinkContextPositive,
+            findings,
+          }
+        ]
+      },
+      {
+        blocks: true,
+        findings: {
+          startIndex: 0,
+          endIndex: 30,
+          overrunIndex: 0,
+          boundaryIndex: 0,
+        },
+        sourceContext: makeSourceContext(
+          [
+            {
+              ruleId: 'sql-injection',
+              // this is the exact value of the query - this is to get coverage
+              value: 'select * from foo where col = "" and 1 = 1; --',
+              details: [],
+            }
+          ],
+          {
+            ['sql-injection']: { mode: 'block' }
+          }
+        ),
+        expectedDetails: [
+          {
+            sinkContext: sinkContextPositive,
+            findings: {
+              startIndex: 0,
+              endIndex: 45,
+              overrunIndex: 0,
+              boundaryIndex: 0,
+            },
+          },
+        ]
+      },
+      {
+        blocks: false,
+        findings: {
+          startIndex: 0,
+          endIndex: 30,
+          overrunIndex: 0,
+          boundaryIndex: 0,
+        },
+        sourceContext: makeSourceContext(
+          [
+            {
+              ruleId: 'sql-injection',
+              value: '" and 1 = 1; --',
+              details: [],
+            }
+          ],
+          {
+            ['sql-injection']: { mode: 'off' }
+          }
+        ),
+        expectedDetails: []
+      }
+    ].forEach(({ analyis, blocks, sourceContext, expectedDetails }) => {
+      it(makeTestDescription(blocks), function() {
+        const testFn = () => {
+          handlers.handleSqlInjection(sourceContext, sinkContextPositive);
+          handlers.handleSqlInjection(sourceContext, sinkContextPositive);
+          handlers.handleSqlInjection(sourceContext, sinkContextNegative);
+        };
+
+        const test = expect(testFn);
+        blocks ? test.to.throw('SecurityException') : test.not.to.throw();
+
+        const sqliResults = sourceContext.findings.resultsMap['sql-injection'];
+        expect(sqliResults[0].details).to.eql(expectedDetails);
+      });
+    });
+  });
+
+  it.skip('handleSsjsInjection()', function() {});
+});

package/lib/input-tracing/handlers/nosql-injection-mongo.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/* c8 ignore start */
+// this is just the general structure of how to handle mongo sinks
+const util = require('util');
+
+const { simpleTraverse } = require('../../utils');
+
+function mongoSink(results, sinkContext) {
+  if (typeof sinkContext.value === 'object') {
+    return handleObjectValue(results, sinkContext.value);
+  } else if (typeof sinkContext.value === 'string') {
+    return handleStringValue(results, sinkContext.value);
+  }
+
+  return null;
+}
+
+function handleObjectValue(results, object) {
+  for (const result of results) {
+    simpleTraverse(object, function(path, type, value) {
+      if (type !== 'Key') {
+        return;
+      }
+      // the result value is the key that was found
+      if (result.value === value) {
+        // does the object at this path equal the user input?
+        let obj = object;
+        for (const p of path) {
+          obj = obj[p];
+        }
+        obj = obj[value];
+        // does the found object in the query equal the saved object?
+        if (util.isDeepStrictEqual(obj, object)) {
+          //
+        }
+      }
+    });
+  }
+}
+
+function handleStringValue(results, string) {
+  // nyi
+}
+
+module.exports = mongoSink;
+
+/* c8 ignore stop */

package/lib/input-tracing/index.js

@@ -0,0 +1,32 @@
+'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}
+ */
+module.exports = function(core) {
+  const inputTracing = core.protect.inputTracing = {};
+
+  // load the interfaces that will be used by input tracing instrumentation
+  require('./handlers')(core);
+
+  // load the instrumentation installers
+  require('./install/fs')(core);
+  require('./install/child-process')(core);
+  require('./install/mysql')(core);
+  require('./install/postgres')(core);
+
+  inputTracing.install = function() {
+    inputTracing.fsInstrumentation.install();
+    inputTracing.cpInstrumentation.install();
+    inputTracing.mysqlInstrumentation.install();
+    inputTracing.postgresInstrumentation.install();
+    // TODO: NODE-2360 (2260?)
+  };
+
+  return inputTracing;
+};

package/lib/input-tracing/install/README.md

@@ -0,0 +1 @@
+This is where to place sinks for input-tracing rules.

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

@@ -0,0 +1,45 @@
+'use strict';
+
+const { isString } = require('@contrast/common');
+const { patchType } = require('../constants');
+
+module.exports = function(core) {
+  const {
+    scopes: { sources, instrumentation },
+    patcher,
+    depHooks,
+    captureStacktrace,
+    protect: { inputTracing }
+  } = core;
+
+  function install() {
+    depHooks.resolve({ name: 'child_process' }, cp => {
+      ['exec', 'execSync'].forEach((method) => {
+        const name = `child_process.${method}`;
+        patcher.patch(cp, method, {
+          name,
+          patchType,
+          pre(data) {
+            if (instrumentation.isLocked()) return;
+
+            const sourceContext = sources.getStore()?.protect;
+            if (!sourceContext) return;
+
+            const value = data.args[0];
+            if (!value || !isString(value)) return;
+
+            const sinkContext = captureStacktrace(
+              { name, value },
+              { constructorOpt: data.hooked }
+            );
+            inputTracing.handleCommandInjection(sourceContext, sinkContext);
+          }
+        });
+      });
+    });
+  }
+
+  const cpInstrumentation = inputTracing.cpInstrumentation = { install };
+
+  return cpInstrumentation;
+};