@contrast/agent 4.32.19 → 5.0.0-alpha.10

package/lib/assess/index.js

@@ -1,35 +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 RestifyFrameworkInstrumentation = require('./restify');
-const FastifyFrameworkInstrumentation = require('./fastify');
-const KoaFrameworkInstrumentation = require('./koa');
-const HapiFrameworkInstrumentation = require('./hapi');
-const Loopback4FrameworkInstrumentation = require('./loopback4');
-const ExpressFrameworkInstrumentation = require('./express');
-const SpdyFrameworkInstrumentation = require('./spdy');
-const assessSources = require('./sources');
-
-module.exports = function(agent) {
-  new RestifyFrameworkInstrumentation(agent);
-  new FastifyFrameworkInstrumentation(agent);
-  new KoaFrameworkInstrumentation(agent);
-  new HapiFrameworkInstrumentation(agent);
-  new Loopback4FrameworkInstrumentation(agent);
-  new ExpressFrameworkInstrumentation(agent);
-  new SpdyFrameworkInstrumentation(agent);
-  assessSources.init(agent);
-};

package/lib/assess/koa/index.js

@@ -1,29 +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 AssessSources = require('./sources');
-const AssessSinks = require('./sinks');
-const RouteCoverage = require('./route-coverage');
-
-module.exports = class KoaInstrumentation {
-  constructor(agent) {
-    new AssessSources();
-    new AssessSinks(agent);
-    if (agent.isRouteCoverageEnabled()) {
-      new RouteCoverage();
-    }
-  }
-};

package/lib/assess/koa/route-coverage.js

@@ -1,114 +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 { createSignature, uniqueId } = require('../../util/route-info');
-const agentEmitter = require('../../agent-emitter');
-const moduleHook = require('../../hooks/require');
-const logger = require('../../core/logger')('hooks:koa');
-const { PATCH_TYPES } = require('../../constants');
-
-class RouteCoverage {
-  constructor() {
-    moduleHook.resolve(
-      { name: 'koa-router' },
-      this.registerRouteHandler.bind(this)
-    );
-    moduleHook.resolve(
-      { name: '@koa/router' },
-      this.registerRouteHandler.bind(this)
-    );
-  }
-
-  /**
-   * Registers handlers on handling a route to properly
-   * emit coverage and patches the handler to emit observation
-   *
-   * @param {Koa.Router} Router koa-router export
-   * @param {Object} metadata package meta from `@contrast/require-hook`
-   */
-  registerRouteHandler(Router, metadata) {
-    logger.debug(
-      `%s module loaded. installing route discovery hooks`,
-      metadata.name
-    );
-
-    patcher.patch(Router.prototype, 'register', {
-      name: 'koaRouter.prototype',
-      patchType: PATCH_TYPES.ROUTE_COVERAGE,
-      alwaysRun: true,
-      post: ({ args, result: layer }) => {
-        const [path, methods] = args;
-
-        // register will call itself recursively on each path in an array,
-        // so we don't need to handle the outer call
-        if (Array.isArray(path)) {
-          return;
-        }
-
-        // koa calls register with an empty array only for "use". and if it changes then
-        // "use" is better than "undefined".
-        const m = methods.length === 0 ? ['use'] : methods;
-
-        const id = this.emitRouteCoverage(path, m);
-
-        // If middleware is given as an array, then the array gets re-used per-layer.
-        // In that case, we only want to prepend our observation middleware once.
-        //
-        // NOTE: When more than one path is given as an arg, they will share a handler
-        // and the closure only captures the first. Because the handler is (by definition) the same
-        // for both paths, it may actually be correct to add an observation middleware for every
-        // individual path to the same middleware stack, because the observation of one path
-        // triggers the same handler as the others would have.
-        layer.stack.unshift(this.routeObservationMiddleware.bind(this, id));
-      }
-    });
-  }
-  /**
-   * emit the route coverage event
-   * @param {string} url the route registered url
-   * @param {string} method http method route is registered
-   * @return {string} id used when observation occurs before discovery
-   */
-  emitRouteCoverage(url, methods) {
-    const event = {};
-    const info = { signature: createSignature(url, methods) };
-    const id = uniqueId();
-    info.id = id;
-    event[id] = info;
-    agentEmitter.emit('route-discovery', event);
-    return id;
-  }
-
-  /**
-   * Defines an async handler to be added to front of layer stack
-   *
-   * @param {Koa.Context} ctx koa ctx
-   * @param {Function} next
-   */
-  async routeObservationMiddleware(id, ctx, next) {
-    const req = ctx.request;
-
-    if (req) {
-      const { url, method: verb } = req;
-      agentEmitter.emit('route-observation', { verb, id, url });
-    }
-
-    await next();
-  }
-}
-
-module.exports = RouteCoverage;

package/lib/assess/koa/sinks/index.js

@@ -1,25 +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.
-*/
-const XssSink = require('./xss');
-const RedirectSink = require('./unvalidated-redirect');
-const ResponseScanning = require('./response-scanning');
-
-module.exports = class FastifySinks {
-  constructor(agent) {
-    new XssSink(agent);
-    new RedirectSink(agent);
-    new ResponseScanning();
-  }
-};

package/lib/assess/koa/sinks/response-scanning.js

@@ -1,40 +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 agentEmitter = require('../../../agent-emitter');
-const {
-  constants: { EVENTS },
-  utils: { isJSON }
-} = require('../../../core/koa');
-const { emitSendEvent } = require('../../../hooks/frameworks/common');
-
-class KoaResponseScanning {
-  constructor() {
-    this.registerResponseScanningHandler();
-  }
-
-  /**
-   * registers a koa `onSend` hook to emit a `send` event
-   * for response scanning assess rules
-   */
-  registerResponseScanningHandler() {
-    agentEmitter.on(EVENTS.RES_END, (ctx) => {
-      const body = isJSON(ctx.body) ? JSON.stringify(ctx.body) : ctx.body;
-      emitSendEvent(body);
-    });
-  }
-}
-
-module.exports = KoaResponseScanning;

package/lib/assess/koa/sinks/unvalidated-redirect.js

@@ -1,96 +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 moduleHook = require('../../../hooks/require');
-const patcher = require('../../../hooks/patcher');
-const logger = require('../../../core/logger')('hooks:koa');
-const { Signature, CallContext } = require('../../models');
-const policy = require('../../policy');
-const { get } = require('lodash');
-const { PATCH_TYPES } = require('../../../constants');
-
-class KoaRedirectSink {
-  constructor(agent) {
-    this.common = require('../../sinks/common')(agent);
-    this.rules = get(policy, 'rules');
-    this.ruleId = 'unvalidated-redirect';
-    this.disallowedTags = ['url-encoded'];
-    const methodName = 'redirect';
-    this.methodName = methodName;
-    this.signature = new Signature({
-      moduleName: 'ctx',
-      methodName,
-      isModule: true
-    });
-
-    this.instrumentResponse();
-  }
-
-  /**
-   * checks if an assess rule is enabled in policy
-   * @param {string} ruleId assess rule id
-   */
-  get enabled() {
-    return get(this.rules, `${this.ruleId}.enabled`);
-  }
-
-  /**
-   * Adds a hook for when koa/lib/reply is required
-   */
-  instrumentResponse() {
-    moduleHook.resolve(
-      { name: 'koa', file: 'lib/response' },
-      this.registerUnvalidatedRedirectHandler.bind(this)
-    );
-  }
-
-  /**
-   * Patches `Response.prototype.redirect` for
-   * `unvalidated-redirect` checking
-   *
-   * @param {Koa.Response} Response outgoing response
-   */
-  registerUnvalidatedRedirectHandler(Response) {
-    const self = this;
-    const { isVulnerable, requiredTags, report } = this.common;
-    const { disallowedTags, ruleId, methodName, signature } = this;
-
-    logger.info('loading ctx.redirect hooks');
-    patcher.patch(Response, methodName, {
-      name: 'koa.Response.prototype',
-      patchType: PATCH_TYPES.ASSESS_SINK,
-      alwaysRun: true,
-      post(data) {
-        if (!self.enabled) {
-          return;
-        }
-        const [url] = data.args;
-        if (isVulnerable({ input: url, disallowedTags, requiredTags })) {
-          const ctxt = CallContext.create({
-            obj: data.obj,
-            args: [url],
-            result: url,
-            stackOpts: {
-              constructorOpt: data.hooked
-            }
-          });
-          report({ ruleId, signature, input: url, ctxt });
-        }
-      }
-    });
-  }
-}
-
-module.exports = KoaRedirectSink;

package/lib/assess/koa/sinks/xss.js

@@ -1,127 +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 { Signature, CallContext } = require('../../models');
-const policy = require('../../policy');
-const { get } = require('lodash');
-const agentEmitter = require('../../../agent-emitter');
-const {
-  constants: { EVENTS }
-} = require('../../../core/koa');
-const stackFactory = require('../../../core/stacktrace').singleton;
-
-class KoaXssSink {
-  constructor(agent) {
-    this.common = require('../../sinks/common')(agent);
-    this.rules = get(policy, 'rules');
-    this.moduleName = 'koa';
-    this.ruleId = 'reflected-xss';
-    this.signature = new Signature({
-      moduleName: this.moduleName,
-      methodName: 'ctx.body', // only part used for the custom mapping
-      isModule: true
-    });
-
-    this.registerStackCaptureHandler();
-    this.registerResEndHandler();
-  }
-
-  /**
-   * checks if an assess rule is enabled in policy
-   */
-  get enabled() {
-    return get(this.rules, `${this.ruleId}.enabled`);
-  }
-
-  /**
-   * Adds a listeners for when `ctx.body` is set and if body is tracked
-   * it will create a new stack
-   */
-  registerStackCaptureHandler() {
-    /**
-     * @param {Object} params
-     * @param {Koa.Context} params.ctx
-     * @param {Boolean} params.tracked is body tracked?
-     */
-    agentEmitter.on(EVENTS.CTX_BODY, ({ ctx, tracked }) => {
-      if (tracked) {
-        ctx._cs_stack = getStacktrace();
-      }
-
-      ctx._cs_stack = null;
-    });
-  }
-
-  /**
-   * Implements a koa `onRoute` hook to wrap the handler
-   * if it is a promise
-   */
-  registerResEndHandler() {
-    const {
-      report,
-      isVulnerable,
-      xss: { disallowedTags },
-      requiredTags
-    } = this.common;
-    const { ruleId, signature } = this;
-
-    agentEmitter.on(EVENTS.RES_END, (ctx) => {
-      if (!this.enabled) {
-        return;
-      }
-
-      const { body } = ctx;
-
-      if (
-        isVulnerable({
-          input: body,
-          disallowedTags,
-          requiredTags,
-          ruleId
-        })
-      ) {
-        // the source should be building a stack when body is set, but if
-        // it doesn't, the report will give some garbage code location like
-        // process._nextTick()
-        const { _cs_stack } = ctx;
-        // The CallContext instance will use _cs_stack function if defined,
-        // otherwise will generate one based on stackOpts
-        const ctxt = CallContext.create({
-          obj: ctx.response,
-          args: [body],
-          result: body,
-          stacktrace: _cs_stack,
-          stackOpts: {
-            constructorOpt: agentEmitter.emit
-          }
-        });
-
-        if (_cs_stack) {
-          ctxt.stack = _cs_stack;
-        }
-
-        report({ ruleId, signature, input: body, ctxt });
-      }
-    });
-  }
-}
-
-function getStacktrace() {
-  return stackFactory.createSnapshot({
-    constructorOpt: agentEmitter.emit
-  });
-}
-
-module.exports = KoaXssSink;

package/lib/assess/koa/sources.js

@@ -1,145 +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 logger = require('../../core/logger')('contrast:hooks:koa:sources');
-const agentEmitter = require('../../agent-emitter');
-const {
-  constants: { EVENTS }
-} = require('../../core/koa');
-
-class KoaAssessSources {
-  constructor() {
-    agentEmitter.on(
-      EVENTS.REQ_START,
-      this.registerRequestStartHandler.bind(this)
-    );
-
-    agentEmitter.on(EVENTS.CTX_PARAMS, this.registerParamsHandler.bind(this));
-
-    agentEmitter.on(
-      EVENTS.CTX_REQUEST_BODY,
-      this.registerBodyHandler.bind(this)
-    );
-
-    agentEmitter.on(
-      EVENTS.CTX_REQUEST_HEADER,
-      this.registerHeaderHandler.bind(this)
-    );
-
-    agentEmitter.on(
-      EVENTS.MULTI_PART,
-      this.registerMultipartHandler.bind(this)
-    );
-    agentEmitter.on(EVENTS.COOKIE, this.registerCookieHandler.bind(this));
-  }
-
-  /**
-   * Handles emitting source events `assess.query` and `assess.headers` that are available when a request is handled in Koa
-   *
-   * @param {Koa.Context} ctx koa request ctx
-   */
-  registerRequestStartHandler(ctx) {
-    /**
-     * In Koa, there's a very strange system for parsing and storing querystrings.
-     * Strings are generally stored in a string format but are generally used as
-     * an object. In doing this, Koa parses between the two formats a number of
-     * times every single time ctx.query is read or written to. The code for this
-     * is in koa/request.js:~172. One of the places were the object format used
-     * by users is constant is in the ctx.request._querycache, where object
-     * forms are cached after being stored. We wrap this querycache in a
-     * membrane to track the data we cannot otherwise get at.
-     * @link:  https://github.com/koajs/koa/blob/master/lib/request.js#L172
-     * Passing a bogus 4th arg to the emit so that the getter fires first so _querycache is populated
-     * and assess will properly wrap the _querycache object
-     */
-    agentEmitter.emit(
-      'assess.query',
-      ctx.request,
-      '_querycache',
-      ctx.request.query
-    );
-
-    // Some earlier versions of koa use __defineGetter__ only (delegates module) to create
-    // the header and headers property on the request. The property does not have a setter.
-    // This causes an exception when we try to wrap the property in a membrane proxy. We use
-    // __lookupS/Getter__ because __defineGetter__ does not expose properties when using
-    // getOwnPropertyDescriptor on instances or prototypes. For these koa versions, for now,
-    // we won't track headers.
-    if (
-      ctx.request.__lookupGetter__('header') &&
-      !ctx.request.__lookupSetter__('header')
-    ) {
-      logger.debug(
-        'koa version does not allow setting of `request.header`. headers will not be tracked'
-      );
-      return;
-    }
-
-    agentEmitter.emit('assess.headers', ctx.request, 'header');
-  }
-
-  /**
-   * Handles when ctx.params is parsed by emitting `assess.params`
-   *
-   * @param {Koa.Context} ctx koa request ctx
-   */
-  registerParamsHandler(ctx) {
-    agentEmitter.emit('assess.params', ctx, 'params');
-  }
-
-  /**
-   * Handles when ctx.request.body is set by emitting `assess.body`
-   *
-   * @param {Koa.Context.Request} ctx koa request ctx
-   */
-  registerBodyHandler({ request }) {
-    agentEmitter.emit('assess.body', request, 'body');
-  }
-
-  /**
-   * Handles when ctx.request.header is called by emitting `assess.headers`
-   *
-   * @param {Koa.Context.Request} ctx koa request ctx
-   */
-  registerHeaderHandler({ request }) {
-    agentEmitter.emit('assess.headers', request, 'headers');
-  }
-
-  /**
-   * Handles when `koa-multer` middleware is run and properly parses
-   * a multipart form and puts the body on the `req`
-   *
-   * @param {Object} params
-   * @param {IncomingMessage} params.req
-   * @param {ServerResponse} param.res
-   */
-  registerMultipartHandler({ req }) {
-    agentEmitter.emit('assess.body', req, 'body');
-    agentEmitter.emit('assess.body', req, 'file');
-    agentEmitter.emit('assess.body', req, 'files');
-  }
-
-  /**
-   * Handles when `koa-cookie` middleware is run and properly parses
-   * a cookies that are put on ctx
-   *
-   * @param {Koa.Context.Request} ctx koa request ctx
-   */
-  registerCookieHandler(ctx) {
-    agentEmitter.emit('assess.cookies', ctx, 'cookie');
-  }
-}
-
-module.exports = KoaAssessSources;

package/lib/assess/loopback4/index.js

@@ -1,29 +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 AssessSinks = require('./sinks');
-const AssessSources = require('./sources');
-const RouteCoverage = require('./route-coverage');
-
-module.exports = class Loopback4Instrumentation {
-  constructor(agent) {
-    new AssessSinks(agent);
-    new AssessSources(agent);
-    if (agent.isRouteCoverageEnabled()) {
-      new RouteCoverage(agent);
-    }
-  }
-};