@contrast/agent 4.32.0 → 5.0.0-alpha.1

package/lib/hooks/encoding.js

@@ -1,88 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-
-const distringuish = require('@contrast/distringuish');
-const logger = require('../core/logger')('contrast:hooks');
-
-// some functions in the standard library allow users to specify a string
-// encoding for their strings to be interpreted as. By default, all strings
-// in v8 are created using UTF8; however, once Distringuish is added to the
-// mix, strings that would previously be interpreted as UTF8 are now encoded
-// using UTF16. As such, we need to do a series of patches over standard
-// library functions.
-// It should be noted that not all functions handle encoding in the same way.
-// Some functions when asked for a specific encoding will perform encoding
-// operations to make sure its in the right encoding, other's will not.
-module.exports = function() {
-  hardPatchEncoding(Buffer.prototype, 'Buffer', 'indexOf', 0);
-  hardPatchEncoding(Buffer.prototype, 'Buffer', 'lastIndexOf', 0);
-  hardPatchEncoding(Buffer.prototype, 'Buffer', 'includes', 0);
-
-  hardPatchEncoding(Buffer, 'Buffer', 'alloc', 0);
-  hardPatchEncoding(Buffer.prototype, 'Buffer', 'fill', 0);
-};
-
-/**
- * Force JavaScript to create another copy of a given string
- * @param {String} str   string you want to copy
- */
-function copy(str) {
-  return ` ${str}`.slice(1);
-}
-
-/**
- * Patch a function that takes an encoding argument for externalized strings.
- * This is necessary because of the `binary' / `latin1' encodings which are
- * UTF-16 incompatible (unlike UTF-8, which is identical up to 0xFF).
- * This does a forced string copy to ensure it's in the default string encoding.
- *
- * @param {Object}    obj              Object prototype that is being patched.
- * @param {String}    objName          module name (using a param to be less hacky)
- * @param {String}    methodName       the function to patch
- * @param {Number}    strIndex         The index of the string argument thats being patched.
- *                                     Since there are multiple of these locations
- *                                     possible, provide a list of all of them.
- */
-function hardPatchEncoding(obj, objName, methodName, strIndex) {
-  // in the event that the Node API changes in some deprecating way that we don't
-  // catch, we just wont apply these patches. Given these encodings are still for
-  // edge-cases
-  if (!obj) {
-    logger.error(
-      `Failed to load encoding hook for ${objName}:${methodName}:${strIndex}`
-    );
-    return;
-  }
-  const origFn = obj[methodName];
-  // export the original function for testing.
-  module.exports[`${objName}.${methodName}`] = origFn;
-  obj[methodName] = function(...args) {
-    try {
-      // check each possible index (encoding can be a number of arguments and)
-      // it depends on the function.
-      // force to desired encoding by decoding to a buffer and then re-encoding.
-      if (typeof args[strIndex] === 'string' && distringuish.isExternal(args[strIndex])) {
-        args[strIndex] = copy(args[strIndex]);
-      }
-    } catch (err) {
-      logger.info(`Encoding patch for ${objName}.${methodName} failed. ${err}`);
-    }
-    return origFn.apply(this, args);
-  };
-}
-
-module.exports.copy = copy;
-module.exports.hardPatchEncoding = hardPatchEncoding;

package/lib/hooks/express-fileupload.js

@@ -1,57 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-
-const patcher = require('../hooks/patcher');
-const { PATCH_TYPES } = require('../constants');
-const requireHook = require('../hooks/require');
-const agentEmitter = require('../agent-emitter');
-const logger = require('../core/logger')('contrast:hooks:express');
-
-function hook() {
-  requireHook.resolve({ name: 'express-fileupload' }, (fileupload) => {
-    logger.info('hooking express-fileupload middleware');
-    const hooked = patcher.patch(fileupload, {
-      name: 'express-fileupload',
-      patchType: PATCH_TYPES.FRAMEWORK,
-      alwaysRun: true,
-      post(data) {
-        data.result = patcher.patch(data.result, {
-          name: 'express.hookedFileUploadMiddleware',
-          patchType: PATCH_TYPES.FRAMEWORK,
-          alwaysRun: true,
-          pre(data) {
-            const [req, , next] = data.args;
-            data.args[2] = function contrastNext() {
-              try {
-                if (req.files) {
-                  agentEmitter.emit('assess.body', req, 'files');
-                }
-              } catch (err) {
-                logger.info(`Unable to patch express-fileupload. ${err}`);
-              }
-
-              next();
-            };
-          }
-        });
-      }
-    });
-
-    return hooked;
-  });
-}
-
-module.exports = hook;

package/lib/hooks/express-session.js

@@ -1,108 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-
-const _ = require('lodash');
-const { Signature, CallContext } = require('../assess/models');
-const { emitSessionEvent } = require('../hooks/frameworks/common');
-const patcher = require('../hooks/patcher');
-const { PATCH_TYPES } = require('../constants');
-const requireHook = require('../hooks/require');
-const logger = require('../core/logger')('contrast:hooks:express');
-const SessionEvent = require('../assess/response-scanning/cookies/events');
-const { signatures } = require('../assess/policy/signatures.json');
-const agentEmitter = require('../agent-emitter');
-const constants = require('../constants');
-const Helpers = require('../core/express/utils');
-
-const { SINK_TYPES } = constants;
-const { EVENTS } = Helpers;
-
-function hook() {
-  requireHook.resolve({ name: 'express-session' }, function(session) {
-    const signature = signatures['express-session'];
-    logger.info('hooking express-session middleware constructor');
-    // Return the hooked function as the export.
-    const hooked = patcher.patch(session, {
-      name: 'express.hookedSessionConstructor',
-      patchType: PATCH_TYPES.FRAMEWORK,
-      alwaysRun: true,
-      post(data) {
-        const options = data.args[0];
-
-        const sig = new Signature(signature);
-        // obfuscate the cookie secret
-        if (_.get(data.args, '[0].secret')) {
-          _.set(data.args, '[0].secret', '[HIDDEN]');
-        }
-
-        const ctxt = CallContext.create(data);
-        // event of when the session was initialized that will be reused for all
-        // session findings
-        const sessionEvent = new SessionEvent({
-          context: ctxt,
-          signature: sig,
-          source: 'P0',
-          options,
-          framework: 'express'
-        });
-
-        data.result = patcher.patch(data.result, {
-          name: 'express.hookedSessionMiddleware',
-          patchType: PATCH_TYPES.FRAMEWORK,
-          alwaysRun: true,
-          pre(data) {
-            const [, res] = data.args;
-            patcher.patch(res, 'setHeader', {
-              name: 'express.hookedSessionSetHeader',
-              patchType: PATCH_TYPES.SINK,
-              alwaysRun: true,
-              post(data) {
-                try {
-                  if (
-                    data.args[0] &&
-                    data.args[0].toLowerCase() === 'set-cookie'
-                  ) {
-                    emitSessionEvent({ any: sessionEvent });
-                  }
-                } catch (err) {
-                  logger.info(`Unable to patch res.setHeader. ${err}`);
-                }
-              }
-            });
-          },
-          post(data) {
-            const [, res] = data.args;
-            patcher.patch(res, 'end', {
-              patchType: PATCH_TYPES.SINK,
-              name: 'http.ServerResponse.end - express-session',
-              pre(data) {
-                agentEmitter.emit(
-                  EVENTS.REQUEST_SEND,
-                  data.args[0],
-                  SINK_TYPES.RESPONSE_BODY
-                );
-              }
-            });
-          }
-        });
-      }
-    });
-
-    return hooked;
-  });
-}
-
-module.exports = hook;

package/lib/hooks/fn-to-string.js

@@ -1,106 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-const patcher = require('./patcher');
-const { PATCH_TYPES } = require('../constants');
-const logger = require('../core/logger')('contrast:hooks:fn-to-string');
-
-const IS_CLASS_REGEX = /^class\W/;
-const IS_FUNCTION_REGEX = /^(async\s+)?function\W/;
-const IS_RETURN_REGEX = /^return\W/;
-const METHOD_CONTEXT = 'function _contrast_';
-const FUNCTION_CONTEXT = 'const _contrast_fn = ';
-
-/**
- * Create some code context around a function to make it syntactically valid
- * the three general types of syntactic function definitions are:
- *   - functions (declared with the function keyword)
- *   - arrow functions
- *   - class methods
- * @param   {string} code the user code
- * @returns {string}      the contextualized function
- */
-const contextualizeFunction = (code) => {
-  // Classes themselves are functions, so we need to exit early to avoid
-  // clobbering the `class` keyword.
-  if (IS_CLASS_REGEX.exec(code)) return code;
-  const [orig] = code.split('{');
-
-  let lineOne = orig;
-
-  // if the function is a return, we don't need to add context.
-  if (!IS_RETURN_REGEX.exec(lineOne)) {
-    // When stringified, class methods look like normal function without the
-    // `function` keyword. We can normalize this by prepending `function`.
-    if (!IS_FUNCTION_REGEX.exec(lineOne) && lineOne.indexOf('=>') === -1) {
-      lineOne = `${METHOD_CONTEXT}${lineOne}`;
-    }
-    lineOne = `${FUNCTION_CONTEXT}${lineOne}`;
-
-    code = code.replace(orig, lineOne);
-  }
-
-  return code;
-};
-
-/**
- * hooks the Function.prototype.toString method
- * undo our rewritten code so users won't see it
- */
-module.exports = function hookFunctionToString(agent) {
-  const rewrite = require('../core/rewrite')(agent);
-
-  logger.debug('deploying function toString patch');
-
-  // function --> unwritten toString
-  const results = new WeakMap();
-
-  patcher.patch(Function.prototype, 'toString', {
-    name: 'Function',
-    patchType: PATCH_TYPES.MISC,
-    alwaysRun: true,
-    pre(data) {
-      if (results.has(data.obj)) {
-        data.result = patcher.preempt(results.get(data.obj));
-      }
-    },
-    post(data) {
-      if (results.has(data.obj)) {
-        data.result = results.get(data.obj);
-        return;
-      }
-      let code = data.result;
-      // only fix the code if it has something we replaced
-      if (code.indexOf('ContrastMethods') !== -1) {
-        // cannot parse lone function expressions that are not part of an assignment.
-        try {
-          code = contextualizeFunction(code);
-          code = rewrite.unwrite(code);
-          code = code.replace(METHOD_CONTEXT, '');
-          code = code.replace(FUNCTION_CONTEXT, '');
-          code = code.replace(/;$/, ''); // removes trailing semicolon
-        } catch (err) {
-          logger.warn('Failed to unwrite code: %s, at: %o', data.result, err);
-          code = data.result;
-        }
-      }
-
-      results.set(data.obj, code);
-      data.result = code;
-    }
-  });
-};
-
-module.exports.contextualizeFunction = contextualizeFunction;

package/lib/hooks/frameworks/base.js

@@ -1,103 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-
-const {
-  AsyncStorage,
-  KEYS: { REQUEST }
-} = require('../../core/async-storage');
-const RequestFactory = require('../../reporter/models/utils/request-factory');
-const CleanStack = require('../../util/clean-stack');
-const agentEmitter = require('../../agent-emitter');
-
-/** @typedef {import('../../agent').ContrastAgent} Agent */
-
-class BaseFramework {
-  /**
-   * @param {Object} opts
-   * @param {string} opts.id
-   * @param {Agent} opts.agent
-   */
-  constructor({ id, agent } = {}) {
-    this.id = id;
-    this.agent = agent;
-    this.emitter = agentEmitter;
-  }
-
-  /**
-   * Proxy for the agent configuration.
-   * @returns {Object} Agent configuration
-   */
-  get config() {
-    return this.agent.config;
-  }
-
-  /**
-   * Returns the file and lineNumber of the top-most stackframe representing
-   * application code. The result should be a path, relative to the application
-   * directory, to the filename of the frame as well as the line number.
-   * Formatted as: /path/to/file.js:100
-   * -- Note --
-   * The current imlementation uses a CleanStack instance in order to generate
-   * a stackframe from which to obtain the information. This can be expensive.
-   * @returns {string}
-   */
-  getAppCodeLocation() {
-    const limit = Error.stackTraceLimit;
-    Error.stackTraceLimit = 50;
-    const frame = new CleanStack()
-      .build()
-      .stack.find(
-        (frame) => frame && frame.file && frame.file.indexOf('node_modules') < 0
-      );
-    Error.stackTraceLimit = limit;
-
-    if (frame) {
-      const { file, lineNumber } = frame;
-      const relativeFile = (file || '').replace(this.agent.appInfo.appDir, '');
-      return `${relativeFile}:${lineNumber || ''}`;
-    } else {
-      return null;
-    }
-  }
-
-  /**
-   * Common logic for sub-classes to update the context w/ the appropriate model
-   * @param {any} request The framework-specific request instance
-   * @param {Function} Ctor The framework-specific request model
-   */
-  static setFrameworkRequest(request, Ctor) {
-    const ctxt = AsyncStorage.getContext();
-    if (ctxt) {
-      ctxt[REQUEST] = RequestFactory.make(request, Ctor);
-    }
-  }
-
-  /**
-   * Adds a key to the framework request model when it exists as a source
-   * Instead of instantiating a request model, we will just add a key
-   * to the request in the async storage
-   *
-   * @param {Object} values keys on request model to update
-   */
-  decorateRequest(values) {
-    const ctxt = AsyncStorage.getContext();
-    if (ctxt) {
-      ctxt.updateRequestModel(values);
-    }
-  }
-}
-
-module.exports = BaseFramework;

package/lib/hooks/frameworks/common.js

@@ -1,191 +0,0 @@
-/**
-Copyright: 2023 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.
-*/
-'use strict';
-
-const _ = require('lodash');
-const agentEmitter = require('../../agent-emitter');
-const {
-  AsyncStorage,
-  KEYS: { RES, REQUEST }
-} = require('../../core/async-storage');
-const { INPUT_TYPES } = require('../../constants');
-const SinkEvent = require('../../protect/models/sink-event');
-const SourceEvent = require('../../protect/models/source-event');
-const logger = require('../../core/logger')('contrast:hooks:frameworks:common');
-
-const getRawResponse = (response) => _.get(response, 'raw.res');
-const getRawRequest = (request) => _.get(request, 'raw.req');
-
-const createSinkEvent = (data, type, id) => new SinkEvent({ data, id, type });
-const createSourceEvent = (frameworkRequest, req, res, dataPath, type, id) =>
-  new SourceEvent({
-    _incomingMessage: req,
-    _serverResponse: res,
-    dataPath,
-    dataOwner: frameworkRequest,
-    id,
-    request: frameworkRequest,
-    type
-  });
-
-module.exports.getRawRequest = getRawRequest;
-module.exports.getRawResponse = getRawResponse;
-module.exports.createSinkEvent = createSinkEvent;
-module.exports.createSourceEvent = createSourceEvent;
-
-/**
- * Alerts listeners that there are watchable properties on the request
- * but emitting the request and the property name.
- *
- * @param {hapi.Request} request The request object we're emitting
- */
-module.exports.emitWatchableObjects = function emitWatchableObjects(request) {
-  agentEmitter.emit('assess.body', request, 'payload');
-  agentEmitter.emit('assess.cookies', request, 'state');
-  agentEmitter.emit('assess.headers', request, 'headers');
-  agentEmitter.emit('assess.query', request, 'query');
-  agentEmitter.emit('assess.params', request, 'params');
-  agentEmitter.emit('assess.body', request, 'payload.data.file');
-};
-
-/**
- * emit a protect lifecycle source event
- * @param {Object}  frameworkRequest
- * @param {IncomingMessage} req http request object
- * @param {ServerResponse} res http response object
- * @param {string} dataPath object property accessor for `request'
- * @param {string} type from constants.js/INPUT_TYPES
- * @param {string} id framework id
- */
-module.exports.emitSourceEvent = function emitSourceEvent(
-  frameworkRequest,
-  req,
-  res,
-  dataPath,
-  type,
-  id
-) {
-  const reqPath = _.get(frameworkRequest, dataPath);
-  if (_.isEmpty(reqPath)) {
-    return;
-  }
-
-  const sourceEvent = createSourceEvent(
-    frameworkRequest,
-    req,
-    res,
-    dataPath,
-    type,
-    id
-  );
-  agentEmitter.emit('protect.source', sourceEvent);
-};
-
-module.exports.emitSinkEvent = function emitSinkEvent(
-  data,
-  type,
-  id,
-  checkObj = true
-) {
-  if (checkObj && _.isEmpty(data)) {
-    return;
-  }
-
-  agentEmitter.emit('protect.sink', createSinkEvent(data, type, id));
-};
-
-/**
- * emits a protect source event of type MULTIPART_NAME
- *
- * @param {Object} params
- * @param {String} params.id id of agentEmitter
- * @param {String} params.name name of file
- */
-module.exports.emitMultipartNameSource = function emitMultipartNameSource({
-  id,
-  name
-}) {
-  const type = INPUT_TYPES.MULTIPART_NAME;
-  // This will result in a UserInput whose name matches its value.
-  const data = { [name]: name };
-  const event = new SourceEvent({ id, type, data });
-  agentEmitter.emit('protect.source', event);
-};
-
-/**
- * emits a protect source event of type MULTIPART_VALUE
- *
- * @param {Object} params
- * @param {String} params.id id of agentEmitter
- * @param {Object} params.fields parsed multipart form data fields
- */
-module.exports.emitMultipartValueSource = function emitMultipartValueSource({
-  id,
-  data
-}) {
-  const type = INPUT_TYPES.MULTIPART_VALUE;
-  const event = new SourceEvent({ id, type, data });
-  agentEmitter.emit('protect.source', event);
-};
-
-/**
- * Gets framework request model and response headers from AsyncStorage
- * If headers are passed in, it will use those as responseHeaders
- * Note: headers are only passed in for Fastify as it obfuscates the headers
- * until it calls res.writeHead/res.end
- *
- * @param {Object} headers response headers from Fastify request
- * @return { Object} request,responseHeaders of a request
- */
-const getHttpData = (headers) => {
-  const ctx = AsyncStorage.getContext();
-  if (!ctx) {
-    logger.warn(
-      'request storage context not accessible: %s',
-      new Error().stack
-    );
-    return null;
-  }
-  const { [REQUEST]: request, [RES]: res } = ctx;
-  return { request, responseHeaders: headers || res.getHeaders() };
-};
-
-/**
- * Gets the request and response headers from async storage and emits a send event
- * used for a lot of the response scanning http rules
- *
- * @param {Object} body passed to response
- * @param {Object} headers response headers
- */
-module.exports.emitSendEvent = function emitSendEvent(body, headers) {
-  const httpData = getHttpData(headers);
-  if (httpData) {
-    const { request, responseHeaders } = httpData;
-    agentEmitter.emit('send', { request, responseHeaders, body });
-  }
-};
-
-/**
- * Gets the framework request and res from AsyncStorage and properly emits the session event used for
- *
- * @param {Object} events SessionEvent objects
- */
-module.exports.emitSessionEvent = function emitSessionEvent(events) {
-  const httpData = getHttpData();
-  if (httpData) {
-    const { request, responseHeaders } = httpData;
-    agentEmitter.emit('session', { request, responseHeaders, events });
-  }
-};