@contrast/protect 1.0.1 → 1.2.0

package/lib/error-handlers/index.js

@@ -4,9 +4,11 @@ module.exports = function(core) {
   const errorHandlers = core.protect.errorHandlers = {};
 
   require('./install/fastify3')(core);
+  require('./install/koa2')(core);
 
   errorHandlers.install = function() {
     errorHandlers.fastify3ErrorHandler.install();
+    errorHandlers.koa2ErrorHandler.install();
   };
 
   return errorHandlers;

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

@@ -0,0 +1,53 @@
+'use strict';
+
+const SecurityException = require('../../security-exception');
+const { patchType } = require('../constants');
+
+
+module.exports = function(core) {
+  const {
+    logger,
+    depHooks,
+    patcher,
+    scopes: { sources },
+    protect,
+  } = core;
+
+  const koa2ErrorHandler = protect.errorHandlers.koa2ErrorHandler = {};
+
+  koa2ErrorHandler.install = function () {
+    depHooks.resolve({ name: 'koa', version: '>=2.3.0' }, (Koa) => {
+      patcher.patch(Koa.prototype, 'handleRequest', {
+        name: 'Koa.Application',
+        patchType,
+        pre(data) {
+          const [ctx] = data.args;
+          patcher.patch(ctx, 'onerror', {
+            name: 'koa.ctx.onerror',
+            patchType,
+            around(org, data) {
+              const [err] = data.args;
+              const sourceContext = sources.getStore()?.protect;
+              const isSecurityException = SecurityException.isSecurityException(err);
+
+              if (isSecurityException && sourceContext) {
+                data.obj.body = '';
+                const blockInfo = sourceContext.findings.securityException;
+                sourceContext.block(...blockInfo);
+                return;
+              }
+
+              if (!sourceContext && isSecurityException) {
+                logger.info('source context not found; unable to handle response');
+              }
+
+              org();
+            }
+          });
+        }
+      });
+    });
+  };
+
+  return koa2ErrorHandler;
+};

package/lib/input-analysis/index.js

@@ -6,10 +6,12 @@ module.exports = function(core) {
   require('./handlers')(core);
   require('./install/http')(core);
   require('./install/fastify3')(core);
+  require('./install/koa2')(core);
 
   inputAnalysis.install = function() {
     inputAnalysis.httpInstrumentation.install();
     inputAnalysis.fastifyInstrumentation.install();
+    inputAnalysis.koaInstrumentation.install();
   };
 
   return inputAnalysis;

package/lib/input-analysis/install/co-body.js

@@ -0,0 +1,51 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  async function postHook(data) {
+    const { args: [, opts], result } = data;
+    if (result) {
+      const sourceContext = sources.getStore()?.protect;
+      if (!sourceContext) {
+        logger.debug('source context not available in `co-body` hook');
+      } else {
+        result.then((resolved) => {
+          const parsedBody = opts?.returnRawBody ? resolved.parsed : resolved;
+          sourceContext.parsedBody = parsedBody;
+          inputAnalysis.handleParsedBody(sourceContext, parsedBody);
+        });
+      }
+    }
+  }
+
+  return {
+    // Patch lower level parser - `co-body` used by `koa-body` and `koa-bodyparser`
+    install() {
+      depHooks.resolve({ name: 'co-body' }, (coBody) => {
+        coBody = patcher.patch(coBody, {
+          name: 'co-body',
+          patchType: 'framework-patch',
+          post: postHook
+        });
+
+        ['json', 'form', 'text'].forEach((property) => {
+          patcher.patch(coBody, property, {
+            name: `co-body.${property}`,
+            patchType: 'framework-patch',
+            post: postHook
+          });
+        });
+
+        return coBody;
+      }
+      );
+    }
+  };
+};

package/lib/input-analysis/install/cookie-parser.js

@@ -0,0 +1,48 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  return {
+  // Patch `cookie-parser` package
+    install() {
+      depHooks.resolve({ name: 'cookie-parser' }, (cookieParser) => patcher.patch(cookieParser, {
+        name: 'cookie-parser',
+        patchType: 'framework-patch',
+        post(data) {
+          data.result = patcher.patch(data.result, {
+            name: 'cookie-parser',
+            patchType: 'framework-patch',
+            pre(data) {
+              const [req, , origNext] = data.args;
+
+              async function contrastNext() {
+                const sourceContext = sources.getStore()?.protect;
+
+                if (!sourceContext) {
+                  logger.debug('source context not available in `cookie-parser` hook');
+                } else {
+                  if (req.cookies) {
+                    sourceContext.parsedCookies = req.cookies;
+                    inputAnalysis.handleCookies(sourceContext, req.cookies);
+                  }
+                }
+
+                await origNext();
+              }
+
+              data.args[2] = contrastNext;
+            }
+          });
+        }
+      })
+      );
+    }
+  };
+};

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

@@ -0,0 +1,53 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  return {
+    // Patch `formidable`
+    install() {
+      depHooks.resolve({ name: 'formidable' }, (formidable) => {
+        formidable.IncomingForm.prototype.parse = patcher.patch(formidable.IncomingForm.prototype.parse, {
+          name: 'Formidable.IncomingForm.prototype.parse',
+          patchType: 'framework-patch',
+          pre(data) {
+            const origCb = data.args[1];
+
+            function hookedCb(...cbArgs) {
+              const sourceContext = sources.getStore()?.protect;
+              const [, fields, files] = cbArgs;
+
+              if (!sourceContext) {
+                logger.debug('source context not available in `formidable` hook');
+              } else {
+                if (fields) {
+                  sourceContext.parsedBody = fields;
+                  inputAnalysis.handleParsedBody(sourceContext, fields);
+                }
+                if (files) {
+                  logger.debug('Check for vulnerable filename upload nyi');
+                  // CHECK FILENAME - NYI
+                }
+              }
+
+              if (origCb && typeof origCb === 'function') {
+                // Should we explicitly run in the current source context?
+                origCb.apply(this, cbArgs);
+              }
+            }
+
+            data.args[1] = hookedCb;
+          }
+        });
+
+        return formidable;
+      });
+    }
+  };
+};

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

@@ -0,0 +1,137 @@
+'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 koa module instrumentation
+   */
+  function install() {
+    depHooks.resolve({ name: 'koa', version: '>=2.3.0' }, (Koa) => {
+      const coBodyPatch = require('./co-body.js')(core);
+      const multerPatch = require('./multer')(core);
+      const formidablePatch = require('./formidable')(core);
+      const qsPatch = require('./qs')(core);
+      const cookieParserPatch = require('./cookie-parser')(core);
+      const universalCookiePatch = require('./universal-cookie')(core);
+
+
+      function contrastStartMiddleware(ctx, next) {
+        if (ctx.query && Object.keys(ctx.query).length) {
+          const sourceContext = sources.getStore()?.protect;
+
+          if (!sourceContext) {
+            logger.debug('source context not available in `qs` hook');
+          } else if (!('parsedQuery' in sourceContext)) {
+            sourceContext.parsedQuery = ctx.query;
+            inputAnalysis.handleQueryParams(sourceContext, ctx.query);
+          }
+
+        }
+        return next();
+      }
+
+      // mark these middleware as ours
+      contrastStartMiddleware._isContrastStartMiddleware = true;
+
+      patcher.patch(Koa.prototype, 'use', {
+        name: 'Koa.Application',
+        patchType: 'framework-patch',
+        pre({ obj: app }) {
+          // if not already inserted, insert the initial middleware.
+          if (
+            app.middleware &&
+              (!app.middleware[0] || !app.middleware[0]._isContrastStartMiddleware)
+          ) {
+            app.middleware.splice(0, 0, contrastStartMiddleware);
+          }
+        }
+      });
+
+      // Patch `koa-router` and `@koa/router` to handle parsed params
+      ['koa-router', '@koa/router'].forEach(router => {
+        depHooks.resolve(
+          { name: router, file: 'lib/layer.js' },
+          (layer) => {
+            layer.prototype = patcher.patch(layer.prototype, 'params', {
+              name: `[${router}].layer.prototype`,
+              patchType: 'framework-patch',
+              post({ result }) {
+                const sourceContext = sources.getStore()?.protect;
+
+                if (!sourceContext) {
+                  logger.debug(`source context not available in \`[${router}].layer\` hook`);
+                } else {
+                  if (Object.keys(result).length) {
+                    sourceContext.parsedParams = result;
+                    inputAnalysis.handleUrlParams(sourceContext, result);
+                  }
+                }
+              }
+            });
+
+            return layer;
+          });
+      });
+
+      // Patch `koa-cookie`
+      depHooks.resolve({ name: 'koa-cookie' }, (koaCookie) => {
+        const { default: cookieParser } = koaCookie;
+        koaCookie.default = patcher.patch(cookieParser, {
+          name: 'koa-cookie',
+          patchType: 'framework-patch',
+          post(data) {
+            data.result = patcher.patch(data.result, {
+              name: 'koa-cookie',
+              patchType: 'framework-patch',
+              pre(data) {
+                const [ctx, origNext] = data.args;
+
+                async function contrastNext() {
+                  const sourceContext = sources.getStore()?.protect;
+
+                  if (!sourceContext) {
+                    logger.debug('source context not available in `koa-cookie` hook');
+                  } else {
+                    if (ctx.cookie) {
+                      sourceContext.parsedCookies = ctx.cookie;
+                      inputAnalysis.handleCookies(sourceContext, ctx.cookie);
+                    }
+                  }
+
+                  await origNext();
+                }
+
+                data.args[1] = contrastNext;
+              }
+            });
+          }
+        });
+      });
+
+      coBodyPatch.install();
+      multerPatch.install();
+      formidablePatch.install();
+      qsPatch.install();
+      cookieParserPatch.install();
+      universalCookiePatch.install();
+    });
+  }
+
+  const koaInstrumentation = inputAnalysis.koaInstrumentation = {
+    install
+  };
+
+  return koaInstrumentation;
+};

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

@@ -0,0 +1,52 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  return {
+    // Patch `multer`
+    install() {
+      depHooks.resolve({ name: 'multer', file: 'lib/make-middleware.js' }, (multerMakeMiddleware) => patcher.patch(multerMakeMiddleware, {
+        name: 'multer.make-middleware',
+        patchType: 'framework-patch',
+        post(data) {
+          data.result = patcher.patch(data.result, {
+            name: 'multerMiddleware',
+            patchType: 'framework-patch',
+            pre(data) {
+              const [req, , origNext] = data.args;
+
+              async function contrastNext() {
+
+                const sourceContext = sources.getStore()?.protect;
+
+                if (!sourceContext) {
+                  logger.debug('source context not available in `multer` hook');
+                } else {
+                  if (req.body) {
+                    sourceContext.parsedBody = req.body;
+                    inputAnalysis.handleParsedBody(sourceContext, req.body);
+                  }
+                  if (req.file || req.files) {
+                    logger.debug('Check for vulnerable filename upload nyi');
+                    // CHECK FILENAME - NYI
+                  }
+                }
+
+                await origNext();
+              }
+
+              data.args[2] = contrastNext;
+            }
+          });
+        }
+      }));
+    }
+  };
+};

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

@@ -0,0 +1,40 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  return {
+    // Patch `qs`
+    install() {
+      depHooks.resolve({ name: 'qs' },
+        (qs) => patcher.patch(qs, 'parse', {
+          name: 'qs',
+          patchType: 'framework-patch',
+          post({ args, result }) {
+            if (result && Object.keys(result).length) {
+              const sourceContext = sources.getStore()?.protect;
+
+              if (!sourceContext) {
+                logger.debug('source context not available in `qs` hook');
+
+              // We need to run analysis for the `qs` result only when it's used as a query parser.
+              // `qs` is used also for parsing bodies, but these cases we handle individually with
+              // the respective library that's using it (e.g. `formidable`, `co-body`) because in
+              // some cases its use is optional and we cannot rely on it.
+              } else if (sourceContext.reqData?.queries === args[0]) {
+                sourceContext.parsedQuery = result;
+                inputAnalysis.handleQueryParams(sourceContext, result);
+              }
+            }
+          }
+        })
+      );
+    }
+  };
+};

package/lib/input-analysis/install/universal-cookie.js

@@ -0,0 +1,34 @@
+'use strict';
+
+module.exports = (core) => {
+  const {
+    depHooks,
+    patcher,
+    logger,
+    scopes: { sources },
+    protect: { inputAnalysis },
+  } = core;
+
+  return {
+  // Patch `universal-cookie` package
+    install() {
+      depHooks.resolve({ name: 'universal-cookie', file: 'cjs/utils.js' }, (uCookieUtils) => patcher.patch(uCookieUtils, 'parseCookies', {
+        name: 'universal-cookie.utils',
+        patchType: 'framework-patch',
+        post({ result }) {
+          if (result && Object.keys(result).length) {
+            const sourceContext = sources.getStore()?.protect;
+
+            if (!sourceContext) {
+              logger.debug('source context not available in `universal-cookie` hook');
+            } else {
+              sourceContext.parsedCookies = result;
+              inputAnalysis.handleCookies(sourceContext, result);
+            }
+          }
+        }
+      })
+      );
+    }
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/protect",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Contrast service providing framework-agnostic Protect support",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -24,8 +24,9 @@
     "@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",
+    "@contrast/core": "1.1.0",
+    "@contrast/scopes": "1.0.0",
+    "@contrast/esm-hooks": "1.1.0",
     "async-hook-domain": "^2.0.4",
     "builtin-modules": "^3.2.0"
   }

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

@@ -1,142 +0,0 @@
-'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.test.mjs

@@ -1,11 +0,0 @@
-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');
-  });
-});