@contrast/agentify 1.0.0

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright: 2022 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.

package/README.md

@@ -0,0 +1,3 @@
+# `@contrast/agentify`
+
+Deploy core services and instrumentation into an application.

package/lib/contrast-methods.js

@@ -0,0 +1,45 @@
+'use strict';
+
+module.exports = function(deps) {
+  /**
+   * Components e.g. Assess, Protect, can
+   * 1) configure rewriter to add desired ContrastMethod functions to source code
+   * 2) patch those functions on `contrastMethods.api` in order to add instrumentation
+   */
+  const contrastMethods = deps.contrastMethods = {
+    // TODO: Assess will require add'l methods
+    // TODO: ESM will require add'l methods
+    api: {
+      eval(v) {
+        return v;
+      },
+    },
+    installed: false,
+    getGlobal() {
+      return global;
+    }
+  };
+
+  contrastMethods.install = function() {
+    if (contrastMethods.installed) {
+      return;
+    }
+
+    const global = contrastMethods.getGlobal();
+
+    try {
+      Object.defineProperty(global, 'ContrastMethods', {
+        enumerable: true,
+        configurable: false,
+        value: contrastMethods.api
+      });
+      contrastMethods.installed = true;
+    } catch (err) {
+      // We should never expect this since the installation process is well
+      // controlled, but still we should have the defensive code.
+      deps.logger.error({ err }, 'Unable to install global.ContrastMethods');
+    }
+  };
+
+  return deps.contrastMethods;
+};

package/lib/contrast-methods.test.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+
+describe('agentify contrast-methods', function() {
+  let contrastMethods;
+  let core;
+
+  beforeEach(function() {
+    const mocks = require('../../test/mocks');
+    core = mocks.core();
+    core.logger = mocks.logger();
+    contrastMethods = require('./contrast-methods')(core);
+  });
+
+  describe('api.eval()', function() {
+    it('acts as identity function', function() {
+      [{}, null, 1, 'two', undefined].forEach(v => {
+        expect(v).to.equal(contrastMethods.api.eval(v));
+      });
+    });
+  });
+
+  describe('.getGlobal', function() {
+    it('returns global :)', function() {
+      expect(contrastMethods.getGlobal()).to.equal(global);
+    });
+  });
+
+  describe('.install', function() {
+    let globalMock;
+    let contrastMethods;
+
+    beforeEach(function() {
+      contrastMethods = require('./contrast-methods')(core);
+      globalMock = {};
+      sinon.stub(contrastMethods, 'getGlobal').returns(globalMock);
+    });
+
+    it('installs on global', function() {
+      expect(globalMock.ContrastMethods).not.to.exist;
+      contrastMethods.install();
+      expect(globalMock.ContrastMethods).to.exist;
+      expect(() => {
+        delete globalMock.ContrastMethods;
+      }).throw(/Cannot delete property/);
+    });
+
+    it('installs just once', function() {
+      expect(globalMock.ContrastMethods).not.to.exist;
+      contrastMethods.install();
+      contrastMethods.install();
+      expect(globalMock.ContrastMethods).to.equal(contrastMethods.api);
+    });
+
+    describe('installation failure handing', function() {
+      beforeEach(function() {
+        Object.defineProperty(globalMock, 'ContrastMethods', {
+          configurable: false,
+          value: 'does not matter for test'
+        });
+      });
+      it('logs error when global.ContrastMethods cannot be redefined', function() {
+        contrastMethods.install();
+        const [{ err }, description] = core.logger.error.getCall(0).args;
+        expect(description).to.eql('Unable to install global.ContrastMethods');
+        expect(err.message).to.eql('Cannot redefine property: ContrastMethods');
+      });
+    });
+  });
+});

package/lib/function-hooks.js

@@ -0,0 +1,118 @@
+'use strict';
+
+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 = ';
+
+module.exports = function (deps) {
+  const {
+    rewriter,
+    logger,
+    patcher,
+    patcher: { hookedFunctions },
+  } = deps;
+
+  const toString = patcher.unwrap(Function.prototype.toString);
+
+  const functionHooks = (deps.functionHooks = {
+    installed: false,
+    cache: new WeakMap(),
+  });
+
+  /**
+   * 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
+   */
+  functionHooks.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;
+  };
+
+  /**
+   * Returns the rewritten function code. If an error occurs during rewriting,
+   * we log the error and code information and return the original code string.
+   * @param {string} code string value of the JavaScript function
+   * @returns {string} the code rewritten to remove Contrast tokens
+   */
+  functionHooks.unwrite = function (code) {
+    // cannot parse lone function expressions that are not part of an assignment.
+    try {
+      let unwritten = functionHooks.contextualizeFunction(code);
+      unwritten = rewriter.unwrite(unwritten);
+      unwritten = unwritten.replace(METHOD_CONTEXT, '');
+      unwritten = unwritten.replace(FUNCTION_CONTEXT, '');
+      unwritten = unwritten.replace(/;$/, ''); // removes trailing semicolon
+      return unwritten;
+    } catch (err) {
+      logger.warn({ err, code }, 'Failed to unwrite function code');
+      return code;
+    }
+  };
+
+  functionHooks.install = function () {
+    if (deps.functionHooks.installed) return;
+
+    logger.debug('deploying function toString patch');
+
+    patcher.patch(Function.prototype, 'toString', {
+      name: 'Function.prototype.toString',
+      patchType: 'function-hooks',
+      around(orig, data) {
+        // rewriting is expensive, but should caching be configurable?
+        if (functionHooks.cache.has(data.obj)) {
+          return functionHooks.cache.get(data.obj);
+        }
+
+        let code;
+        if (hookedFunctions.has(data.obj)) {
+          code = toString.call(hookedFunctions.get(data.obj).fn);
+        } else {
+          code = orig();
+        }
+
+        let result = code;
+
+        if (code.indexOf('ContrastMethods')) {
+          const unwritten = functionHooks.unwrite(code);
+          functionHooks.cache.set(data.obj, unwritten);
+          result = unwritten;
+        }
+
+        return result;
+      },
+    });
+
+    functionHooks.installed = true;
+  };
+
+  functionHooks.uninstall = function () {
+    Function.prototype.toString = toString;
+  };
+
+  return functionHooks;
+};

package/lib/function-hooks.test.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const { expect } = require('chai');
+const functionHooks = require('./function-hooks');
+
+describe('agentify function-hooks', function () {
+  let coreMock;
+
+  beforeEach(function () {
+    const mocks = require('../../test/mocks');
+
+    coreMock = mocks.core();
+    coreMock.patcher = mocks.patcher();
+    coreMock.logger = mocks.logger();
+    coreMock.depHooks = mocks.depHooks();
+    coreMock.scopes = mocks.scopes();
+    coreMock.rewriter = mocks.rewriter();
+  });
+
+  it('should install function hooks', function () {
+    functionHooks(coreMock);
+    coreMock.functionHooks.install();
+    expect(coreMock.functionHooks.installed).to.be.true;
+  });
+
+  it('should skip if it is already installed', function () {
+    functionHooks(coreMock);
+    coreMock.functionHooks.installed = true;
+    coreMock.functionHooks.install();
+
+    expect(coreMock.logger.debug).to.not.have.been.called;
+  });
+
+  it('should return cached value when the function is already called', function () {
+    const functionA = function sum(a, b) {
+      eval(global.ContrastMethods.eval('2 + 2'));
+      return a + b;
+    };
+
+    const cachedValue = 'cachedValue';
+
+    functionHooks(coreMock);
+
+    coreMock.functionHooks.cache.set(functionA, cachedValue);
+
+    const data = {
+      obj: functionA,
+    };
+
+    let result;
+    coreMock.patcher.patch.callsFake((prototype, method, options) => {
+      result = options.around(() => ({}), data);
+    });
+
+    coreMock.functionHooks.install();
+
+    expect(result).to.eql(cachedValue);
+  });
+
+  it('should call the function itself when the function is not hooked', function () {
+    const functionA = function sum(a, b) {
+      eval(global.ContrastMethods.eval('2 + 2'));
+      return a + b;
+    };
+
+    functionHooks(coreMock);
+
+    const data = {
+      obj: functionA,
+    };
+
+    let result;
+    coreMock.patcher.patch.callsFake((prototype, method, options) => {
+      result = options.around(functionA.toString.bind(functionA), data);
+    });
+
+    const unwriteResult = `function sum(a, b) {
+      eval(2 + 2);
+      return a + b;
+      }`;
+
+    coreMock.rewriter.unwrite.callsFake((data) => unwriteResult);
+
+    coreMock.functionHooks.install();
+
+    expect(result).to.eql(unwriteResult);
+    expect(coreMock.functionHooks.cache.get(data.obj)).to.eql(unwriteResult);
+  });
+
+  it('should the call the original function of the hooked function', function () {
+    const functionA = function sum(a, b) {
+      eval(global.ContrastMethods.eval('2 + 2'));
+      return a + b;
+    };
+
+    const functionB = function sum(a, b) {
+      eval(global.ContrastMethods.eval('2 + 2'));
+      return a + b + 2;
+    };
+
+    functionHooks(coreMock);
+
+    const weekMap = coreMock.patcher.hookedFunctions;
+    weekMap.set(functionA, { fn: functionB });
+
+    const data = {
+      obj: functionA,
+    };
+
+    let result;
+    coreMock.patcher.patch.callsFake((prototype, method, options) => {
+      result = options.around(functionA.toString.bind(functionA), data);
+    });
+
+    const unwriteResult = `function sum(a, b) {
+      eval(2 + 2);
+      return a + b + 2;
+      }`;
+
+    coreMock.rewriter.unwrite.callsFake((data) => unwriteResult);
+
+
+    coreMock.functionHooks.install();
+
+    expect(result).to.eql(unwriteResult);
+    expect(coreMock.functionHooks.cache.get(data.obj)).to.eql(unwriteResult);
+  });
+
+  it('should log warning message when there is a problem unwriting the code', function () {
+    const err = new Error('Error');
+    const functionA = function sum(a, b) {
+      eval(global.ContrastMethods.eval('2 + 2'));
+      return a + b;
+    };
+
+    functionHooks(coreMock);
+
+    const data = {
+      obj: functionA,
+    };
+
+    coreMock.patcher.patch.callsFake((prototype, method, options) => {
+      options.around(functionA.toString.bind(functionA), data);
+    });
+
+    coreMock.rewriter.unwrite.throws(err);
+
+    coreMock.functionHooks.install();
+
+    expect(coreMock.logger.warn).to.have.been.calledWith({ err, code: functionA.toString() }, 'Failed to unwrite function code');
+  });
+
+  it('should call the original toString if the function is not hooked', function() {
+    const functionA = () => 1;
+    functionHooks(coreMock);
+    coreMock.functionHooks.install();
+
+    const resultOfA = functionA.toString();
+
+    expect(resultOfA).to.eqls('() => 1');
+  });
+
+  it('should uninstall the hooks', function() {
+    const { toString } = Function.prototype;
+    const functionA = () => 1;
+    functionHooks(coreMock);
+    coreMock.functionHooks.install();
+    coreMock.functionHooks.uninstall();
+
+    const resultOfA = functionA.toString();
+
+    expect(resultOfA).to.eqls('() => 1');
+    expect(Function.prototype.toString).to.eqls(toString);
+  });
+});

package/lib/index.d.ts

@@ -0,0 +1,37 @@
+import RequireHook from '@contrast/require-hook';
+import { Logger } from '@contrast/logger';
+
+interface AgentifyOptions {
+  install: boolean;
+  svcList: string[];
+}
+
+interface AgentOptions<T> {
+  install: boolean;
+  preRunMain: PreRunMain<T>;
+}
+
+declare class Agent<T> {
+  constructor(deps: T, opts: AgentOptions<T>);
+  hookRunMain(): void;
+  handleInstallFailure(err: Error): Promise<void>;
+  install(): Promise<void>;
+}
+
+interface PreRunMain<T> {
+  (core: T, agent: Agent<T>): void | Promise<void>;
+}
+
+export interface Agentify<T> {
+  (preRunMain: PreRunMain<T>, opts?: AgentifyOptions): Agent<T>;
+}
+
+interface Core<T> {
+  readonly depHooks: RequireHook;
+  readonly logger: Logger;
+  agentify: Agentify<T>;
+}
+
+declare function init<T>(core: Core<T>): Agentify<T>;
+
+export = init;

package/lib/index.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const Module = require('module');
+
+const defaultOpts = {
+  install: true,
+  svcList: [
+    'reporter',
+    'contrastMethods',
+    'instrumentationLocks',
+    'sources',
+    'protect',
+    'depHooks',
+    'rewriteHooks',
+    'functionHooks',
+  ]
+};
+
+module.exports = function(deps) {
+  // compose add'l local services
+  require('./sources')(deps);
+  require('./contrast-methods')(deps);
+  require('./instrumentation-locks')(deps);
+  require('./function-hooks')(deps);
+  require('./rewrite-hooks')(deps);
+  // TODO: NODE-2229
+
+  /**
+   * The interface is a function, which when called, will hook runMain
+   * @param {function} preRunMain
+   * @param {object} opts
+   */
+  function agentify(preRunMain, opts = defaultOpts) {
+    if (typeof preRunMain !== 'function') {
+      throw new Error('Invalid usage: first argument must be a function');
+    }
+
+    opts.preRunMain = preRunMain;
+
+    if (opts !== defaultOpts) {
+      opts = { ...defaultOpts, ...opts };
+    }
+
+    return new Agent(deps, opts);
+  }
+
+  deps.agentify = agentify;
+
+  return agentify;
+};
+
+class Agent {
+  /**
+   *
+   * @param {object} deps dependencies
+   * @param {object} opts
+   * @param {function} opts.preRunMain custom function for registering services
+   * @param {boolean} opts.install whether to automatically install
+   */
+  constructor(deps, opts) {
+    const self = this;
+    const { config, logger } = deps;
+
+    this.deps = deps;
+    this.opts = opts;
+    this.runMain = Module.runMain;
+
+    /**
+     * This is one side effect that will always occur, even with `install: false`.
+     * The act of calling `agentify()` is enough to cause this side effect, by design.
+     */
+    Module.runMain = async function(...args) {
+      try {
+        logger.info('Starting the Contrast agent');
+        logger.debug({ config }, 'Agent configuration');
+
+        await opts.preRunMain(deps);
+        if (opts.install) {
+          await self.install();
+        }
+      } catch (err) {
+        await self.handleInstallFailure(err);
+      }
+      return self.runMain.apply(this, args);
+    };
+  }
+
+  /**
+   * Original `runMain` will get called after this.
+   *
+   * TODO: Consider proper UNINSTALLATION and normal startup w/o agent
+   *
+   * @param {error} err Error thrown during install
+   */
+  async handleInstallFailure(err) {
+    this.deps.logger.error(
+      { err },
+      'A fatal agent installation error has occurred. The application will be run without instrumentation.'
+    );
+  }
+
+  async install() {
+    for (const svcName of this.opts.svcList) {
+      this.deps.logger.trace('installing service: %s', svcName);
+      const svc = this.deps[svcName];
+      if (svc && svc.install) {
+        await svc.install();
+      }
+    }
+  }
+}
+
+module.exports.Agent = Agent;

package/lib/index.test.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const chai = require('chai');
+const { expect } = chai;
+const sinon = require('sinon');
+
+describe('agentify', function() {
+  const Module = require('module');
+  let core;
+  let agentify;
+  let runMain;
+
+  beforeEach(function() {
+    const factory = require('.');
+    const mocks = require('../../test/mocks');
+
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.depHooks = mocks.depHooks();
+    core.scopes = mocks.scopes();
+    core.patcher = mocks.patcher();
+    agentify = factory(core);
+    runMain = sinon.stub(Module, 'runMain');
+  });
+
+  describe('factory', function() {
+    it('invoking with callback will initialize and patch runMain', async function() {
+      let ranFlag;
+
+      agentify((deps) => {
+        expect(deps).to.equal(core);
+        ranFlag = true;
+      }, {
+        svcList: ['depHooks']
+      });
+
+      await Module.runMain();
+
+      expect(ranFlag).to.be.true;
+      expect(runMain).to.be.called;
+      expect(core.depHooks.install).to.have.been.called;
+      expect(core.logger.error).not.to.been.called;
+    });
+
+    it('will not run install methods opts = { install: false }', async function() {
+      const a = agentify(() => {}, { install: false });
+      sinon.spy(a, 'install');
+
+      await Module.runMain();
+
+      expect(a.install).not.to.have.been.called;
+      expect(core.logger.error).not.called;
+    });
+
+    it('handles errors in pre runMain hook (init)', async function() {
+      const err = new Error('bonk');
+      const a = agentify(() => {
+        throw err;
+      });
+      sinon.spy(a, 'install');
+      sinon.spy(a, 'handleInstallFailure');
+
+      await Module.runMain();
+
+      expect(a.handleInstallFailure).to.have.been.calledWith(err);
+      expect(a.install).to.not.have.been.called;
+      expect(core.logger.error).calledWith({ err }, 'A fatal agent installation error has occurred. The application will be run without instrumentation.');
+    });
+
+    //
+    it('instantiation handles "unregistered" services', async function() {
+      agentify((deps) => 0, {
+        install: true,
+        svcList: ['foo']
+      });
+
+      // Having non-existent service in list is handled during initialization
+      await Module.runMain();
+
+      expect(core.logger.error).not.called;
+    });
+
+    it('requires init function arg', function() {
+      expect(() => {
+        agentify('not a function');
+      }).to.throw('Invalid usage: first argument must be a function');
+    });
+  });
+});

package/lib/instrumentation-locks.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const Module = require('module');
+
+module.exports = function(deps) {
+  const {
+    patcher: { patch },
+    scopes: { instrumentation }
+  } = deps;
+
+  deps.instrumentationLocks = {
+    install() {
+      const name = 'Module.prototype.require';
+      const store = {
+        name: `${name}`,
+        lock: true,
+      };
+
+      // `require` has sinks and propagators that run
+      patch(Module.prototype, 'require', {
+        name,
+        patchType: 'instrumentation-lock',
+        around(next, data) {
+          if (!instrumentation.isLocked()) {
+            return instrumentation.run(store, next);
+          }
+          return next();
+        }
+      });
+
+      // likely more to come e.g. v4 deadzones
+    }
+  };
+
+  return deps.instrumentationLocks;
+};

package/lib/instrumentation-locks.test.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const Module = require('module');
+const instrumentationLocks = require('./instrumentation-locks');
+const mocks = require('../../test/mocks');
+
+describe('agentify instrumentation-locks', function () {
+  let core, storeSpy;
+
+  beforeEach(function () {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.scopes = require('@contrast/scopes')(core);
+    core.patcher = require('@contrast/patcher')(core);
+    storeSpy = sinon.stub();
+
+    const origRequire = Module.prototype.require;
+    sinon.stub(Module.prototype, 'require').callsFake(function (...args) {
+      storeSpy(core.scopes.instrumentation.getStore());
+      return origRequire.call(this, ...args);
+    });
+
+    instrumentationLocks(core);
+    core.instrumentationLocks.install();
+  });
+
+  it('require gets called with instrumentation locked', function () {
+    // side effects are in place for this to exercise properly
+    require('crypto');
+    expect(storeSpy).to.have.been.calledWith({
+      lock: true,
+      name: 'Module.prototype.require',
+    });
+  });
+
+  it('will not run with lock if already locked', function () {
+    // side effects are in place for this to exercise properly
+    core.scopes.instrumentation.run({ lock: true, name: 'test' }, () => {
+      // target here is arbitrary
+      require('events');
+
+      expect(storeSpy).to.have.been.calledWith({
+        lock: true,
+        name: 'test',
+      });
+
+      expect(storeSpy).to.not.have.been.calledWith({
+        lock: true,
+        name: 'Module.prototype.require',
+      });
+    });
+  });
+});

package/lib/rewrite-hooks.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const Module = require('module');
+
+module.exports = function(deps) {
+  const origCompile = Module.prototype._compile;
+
+  deps.rewriteHooks = {
+
+    install() {
+      if (!deps.config.agent.node.enable_rewrite) return;
+
+      Module.prototype._compile = function(content, filename) {
+        let compiled;
+        const { code } = deps.rewriter.rewrite(content, { filename });
+        try {
+          compiled = origCompile.call(this, code, filename);
+        } catch (err) {
+          deps.logger.error(
+            { err },
+            'Failed to compile rewritten code for %s, rewritten code %s, compiling original code.',
+            filename,
+            code
+          );
+          compiled = origCompile.call(this, content, filename);
+        }
+
+        return compiled;
+      };
+    },
+
+    restore() {
+      Module.prototype._compile = origCompile;
+    }
+  };
+
+  return deps.rewriteHooks;
+};

package/lib/rewrite-hooks.test.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const sinon = require('sinon');
+const { expect } = require('chai');
+const Module = require('module');
+
+const testCode = require.resolve('../test/resources/file');
+
+describe('agentify rewrite-hooks', function() {
+  let core, rewriteHooks, origCompileSpy;
+
+  beforeEach(function() {
+    const mocks = require('../../test/mocks');
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.agentify = mocks.agentify();
+    core.config = mocks.config();
+    core.config.agent.node.enable_rewrite = true;
+    core.rewriter = mocks.rewriter();
+    origCompileSpy = sinon.spy(Module.prototype, '_compile');
+    rewriteHooks = require('./rewrite-hooks')(core);
+    rewriteHooks.install();
+  });
+
+  afterEach(function() {
+    delete require.cache[testCode];
+    rewriteHooks.restore();
+  });
+
+  it('Should not rewrite code when enable_rewrite is false', function() {
+    sinon.restore();
+    core.config.agent.node.enable_rewrite = false;
+    rewriteHooks = require('./rewrite-hooks')(core);
+    rewriteHooks.install();
+    require('../test/resources/file');
+    expect(core.rewriter.rewrite).to.not.have.been.called;
+  });
+
+  it('Should rewrite code', function() {
+    require('../test/resources/file');
+    expect(core.rewriter.rewrite).to.have.been.calledWith(
+      sinon.match.string,
+      { filename: testCode }
+    );
+    expect(core.logger.error).to.not.have.been.called;
+    expect(origCompileSpy).to.have.been.calledWith(
+      "const ContrastMethods = global.ContrastMethods\n/* eslint-disable */\n'use strict'\nconst variable = 'variable';\n",
+      testCode
+    );
+  });
+
+  it('Should log error if module contains a SyntaxError', function() {
+    core.rewriter.rewrite.callsFake((content) => ({
+      code: content.replace('const variable', 'const variable const a')
+    }));
+    require('../test/resources/file');
+    expect(core.rewriter.rewrite).to.have.been.calledWith(
+      sinon.match.string,
+      { filename: testCode }
+    );
+    expect(core.logger.error).to.have.been.calledWith(
+      {
+        err: sinon.match({
+          message: 'Missing initializer in const declaration'
+        })
+      },
+      'Failed to compile rewritten code for %s, rewritten code %s, compiling original code.',
+      testCode,
+      sinon.match('const variable const a')
+    );
+    expect(origCompileSpy).to.have.been.calledWith(
+      "/* eslint-disable */\n'use strict'\nconst variable = 'variable';\n",
+      testCode
+    );
+  });
+});

package/lib/sources.js

@@ -0,0 +1,63 @@
+'use strict';
+
+module.exports = function(core) {
+  const { depHooks, patcher, logger, scopes: { sources: sourcesStorage } } = core;
+  const sources = core.sources = {};
+
+  sources.install = function install() {
+    depHooks.resolve({ name: 'http' }, http => patchCreateServer({ serverSource: http, patchName: 'httpServer' }));
+    depHooks.resolve({ name: 'https' }, https => patchCreateServer({ serverSource: https, patchName: 'httpsServer' }));
+    depHooks.resolve({ name: 'http2' }, http2 => {
+      patchCreateServer({ serverSource: http2, patchName: 'http2Server' });
+      patchCreateServer({ serverSource: http2, patchName: 'http2SecureServer', constructorName: 'createSecureServer' });
+    });
+    depHooks.resolve({ name: 'spdy' }, spdy => patchCreateServer({ serverSource: spdy, patchName: 'spdyServer' }));
+  };
+
+  function patchCreateServer({ serverSource, patchName, constructorName = 'createServer' }) {
+    patcher.patch(serverSource, constructorName, {
+      name: patchName,
+      patchType: 'http-sources',
+      post: createServerPostHook(patchName)
+    });
+  }
+
+  function createServerPostHook(serverType) {
+    return function(data) {
+      const { result: server } = data;
+      const serverPrototype = server ? Object.getPrototypeOf(server) : null;
+
+      if (!serverPrototype) {
+        logger.error('Unable to patch server prototype, continue without instrumentation');
+        return;
+      }
+
+      patcher.patch(serverPrototype, 'emit', {
+        name: 'server.emit',
+        patchType: 'req-async-storage',
+        around: emitAroundHook(serverType)
+      });
+    };
+  }
+
+  function emitAroundHook(serverType) {
+    return function emitAroundHook(next, data) {
+      const { args: [event] } = data;
+
+      if (event !== 'request') return next();
+
+      const store = { serverType };
+
+      return sourcesStorage.run(store, next);
+    };
+  }
+
+  return {
+    install: sources.install,
+    functions: {
+      patchCreateServer,
+      createServerPostHook,
+      emitAroundHook
+    }
+  };
+};

package/lib/sources.test.js

@@ -0,0 +1,196 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const sourcesModule = require('./sources');
+
+describe('agentify sources', function () {
+  let mocks, coreMock, depHooksMock, patcherMock, loggerMock, scopesMock;
+
+  beforeEach(function () {
+    mocks = require('../../test/mocks');
+    loggerMock = mocks.logger();
+    patcherMock = mocks.patcher();
+    depHooksMock = mocks.depHooks();
+    scopesMock = mocks.scopes();
+    coreMock = {
+      logger: loggerMock,
+      patcher: patcherMock,
+      depHooks: depHooksMock,
+      scopes: scopesMock,
+    };
+  });
+
+  describe('attaching the sources module to the core object', function () {
+    it('attaches the module to the core object', function () {
+      const sources = sourcesModule(coreMock);
+      expect(coreMock).to.haveOwnProperty('sources');
+      expect(coreMock.sources).to.haveOwnProperty('install');
+      expect(sources).to.haveOwnProperty('install');
+      expect(sources).to.haveOwnProperty('functions');
+    });
+  });
+
+  describe('installing instrumentation for HTTP type of sources', function () {
+    let argumentsMap, httpMock, httpsMock, http2Mock, spdyMock;
+
+    beforeEach(function () {
+      httpMock = { name: 'http' };
+      httpsMock = { name: 'https' };
+      http2Mock = { name: 'http2' };
+      spdyMock = { name: 'spdy' };
+      const patchType = 'http-sources';
+      argumentsMap = {
+        http: {
+          source: httpMock,
+          patcherArgs: [
+            [httpMock, 'createServer', { name: 'httpServer', patchType }],
+          ],
+        },
+        https: {
+          source: httpsMock,
+          patcherArgs: [
+            [httpsMock, 'createServer', { name: 'httpsServer', patchType }],
+          ],
+        },
+        http2: {
+          source: http2Mock,
+          patcherArgs: [
+            [http2Mock, 'createServer', { name: 'http2Server', patchType }],
+            [
+              http2Mock,
+              'createSecureServer',
+              { name: 'http2SecureServer', patchType },
+            ],
+          ],
+        },
+        spdy: {
+          source: spdyMock,
+          patcherArgs: [
+            [spdyMock, 'createServer', { name: 'spdyServer', patchType }],
+          ],
+        },
+      };
+      coreMock.depHooks.resolve.callsFake((moduleMetadata, callback) =>
+        callback(argumentsMap[moduleMetadata.name].source)
+      );
+    });
+
+    it('should call patcher.patch with the correct arguments from depHooks.resolve', function () {
+      const sources = sourcesModule(coreMock);
+      sources.install();
+
+      const callOrder = ['http', 'https', 'http2', 'http2', 'spdy'];
+      let consecutiveCalls = 0;
+
+      for (let i = 0; i < callOrder.length; i++) {
+        consecutiveCalls = callOrder[i] == 'http2' ? consecutiveCalls : 0;
+        const argument = (callNumber, argIndex) =>
+          patcherMock.patch.getCall(callNumber).args[argIndex];
+        const expectedArgument = (callNumber, argIndex, consecutiveCalls) =>
+          argumentsMap[callOrder[callNumber]].patcherArgs[consecutiveCalls][
+            argIndex
+          ];
+
+        expect(argument(i, 0)).to.equal(
+          expectedArgument(i, 0, consecutiveCalls)
+        );
+        expect(argument(i, 1)).to.equal(
+          expectedArgument(i, 1, consecutiveCalls)
+        );
+        expect(argument(i, 2)).to.include(
+          expectedArgument(i, 2, consecutiveCalls)
+        );
+
+        if (callOrder[i] == 'http2' && !consecutiveCalls) {
+          consecutiveCalls++;
+        }
+      }
+
+      expect(patcherMock.patch).to.have.been.callCount(callOrder.length);
+    });
+  });
+
+  describe('functions', function () {
+    let emitAroundHook, createServerPostHook, dataObj;
+
+    beforeEach(function () {
+      ({
+        functions: { createServerPostHook, emitAroundHook },
+      } = sourcesModule(coreMock));
+    });
+
+    describe('createServerPostHook', function () {
+      let serverMock, prototypeMock;
+      beforeEach(function () {
+        serverMock = {};
+        prototypeMock = {
+          emit() {},
+        };
+        dataObj = {
+          result: serverMock,
+        };
+        Object.setPrototypeOf(serverMock, prototypeMock);
+      });
+
+      it('calls patcher.patch() if proper data argument is supplied', function () {
+        createServerPostHook('httpServer')(dataObj);
+        expect(loggerMock.error).to.not.have.been.called;
+        expect(patcherMock.patch).to.have.been.calledWith(
+          prototypeMock,
+          'emit',
+          {
+            name: 'server.emit',
+            patchType: 'req-async-storage',
+            around: sinon.match.func
+          }
+        );
+      });
+
+      it('calls logger.error() if none or invalid data argument is supplied', function () {
+        createServerPostHook('httpServer')({});
+        expect(loggerMock.error).to.have.been.calledWith(
+          'Unable to patch server prototype, continue without instrumentation'
+        );
+        Object.setPrototypeOf(serverMock, null);
+        createServerPostHook('httpServer')(serverMock);
+        expect(loggerMock.error).to.have.been.called.calledTwice;
+        expect(patcherMock.patch).to.not.have.been.called;
+      });
+    });
+
+    describe('emitAroundHook', function () {
+      let nextFn, reqMock, resMock, eventMock;
+      beforeEach(function () {
+        reqMock = () => {
+          this.method = 'GET';
+          this.url = 'http://localhost';
+        };
+        resMock = () => {};
+        eventMock = 'request';
+        dataObj = {
+          args: [eventMock, reqMock, resMock],
+        };
+        nextFn = function () {
+          return {
+            sourcesStore: scopesMock.sources.getStore(),
+          };
+        };
+      });
+
+      it('executes the hooked nextFn in the provided context if the event name is "request"', function () {
+        const result = emitAroundHook('httpServer')(nextFn, dataObj);
+        expect(result.sourcesStore).to.deep.include({
+          serverType: 'httpServer',
+        });
+      });
+
+      it('executes the hooked nextFn without binding it to a context if the event name is not "request"', function () {
+        eventMock = 'listen';
+        dataObj.args[0] = eventMock;
+        const result = emitAroundHook('httpServer')(nextFn, dataObj);
+        expect(result.sourcesStore).to.equal(undefined);
+      });
+    });
+  });
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@contrast/agentify",
+  "version": "1.0.0",
+  "description": "Configures Contrast agent services and instrumentation within an application",
+  "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",
+  "engines": {
+    "npm": ">= 8.4.0",
+    "node": ">= 14.15.0"
+  },
+  "scripts": {
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {}
+}