@contrast/agentify 1.32.0 → 1.34.0

package/lib/diagnostics.js

@@ -18,6 +18,8 @@
 const fs = require('fs/promises');
 const path = require('path');
 
+const { primordials: { JSONStringify } } = require('@contrast/common');
+
 module.exports = function init(core) {
   async function logDiagnosticFiles() {
     const { config, logger } = core;
@@ -32,13 +34,13 @@ module.exports = function init(core) {
     return Promise.all([
       fs.writeFile(
         path.join(report_path, 'contrast_effective_config.json'),
-        JSON.stringify(effectiveConfig, null, 2)
+        JSONStringify(effectiveConfig, null, 2)
       ).catch((err) => {
         logger.warn({ err }, 'unable to write effective config file');
       }),
       fs.writeFile(
         path.join(report_path, 'contrast_system_info.json'),
-        JSON.stringify(systemInfo, null, 2)
+        JSONStringify(systemInfo, null, 2)
       ).catch((err) => {
         logger.warn({ err }, 'unable to write system info file');
       }),

package/lib/function-hooks.js

@@ -21,6 +21,8 @@ const IS_RETURN_REGEX = /^return\W/;
 const FUNCTION_DECL = 'function _contrast_';
 const VARIABLE_DECL = 'const _contrast_fn = ';
 
+const { primordials: { StringPrototypeReplace, StringPrototypeSplit, RegExpPrototypeExec, FunctionPrototypeToString } } = require('@contrast/common');
+
 /**
  * Injects some context around a function's toString() to make it syntactically
  * valid. The `swc` parser expects input to be a valid `Statement` like one of
@@ -40,23 +42,23 @@ const VARIABLE_DECL = 'const _contrast_fn = ';
  */
 function contextualize(code) {
   // in case the class is anonymous we need to prepend a variable declaration.
-  if (IS_CLASS_REGEX.exec(code)) {
+  if (RegExpPrototypeExec.call(IS_CLASS_REGEX, code)) {
     return `${VARIABLE_DECL}${code}`;
   }
 
   // if the function is a return, we don't need to add context.
-  if (!IS_RETURN_REGEX.exec(code)) {
-    const [orig] = code.split('{');
+  if (!RegExpPrototypeExec.call(IS_RETURN_REGEX, code)) {
+    const [orig] = StringPrototypeSplit.call(code, '{');
     let lineOne = orig;
 
     // 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) {
+    if (!RegExpPrototypeExec.call(IS_FUNCTION_REGEX, lineOne) && lineOne.indexOf('=>') === -1) {
       lineOne = `${FUNCTION_DECL}${lineOne}`;
     }
     lineOne = `${VARIABLE_DECL}${lineOne}`;
 
-    code = code.replace(orig, lineOne);
+    code = StringPrototypeReplace.call(code, orig, lineOne);
   }
 
   return code;
@@ -70,8 +72,6 @@ module.exports = function (deps) {
     patcher: { hookedFunctions },
   } = deps;
 
-  const toString = patcher.unwrap(Function.prototype.toString);
-
   const functionHooks = (deps.functionHooks = {
     installed: false,
     cache: new WeakMap(),
@@ -88,9 +88,9 @@ module.exports = function (deps) {
     try {
       let unwritten = contextualize(code);
       unwritten = rewriter.unwriteSync(unwritten);
-      unwritten = unwritten.replace(FUNCTION_DECL, '');
-      unwritten = unwritten.replace(VARIABLE_DECL, '');
-      unwritten = unwritten.replace(/;\s*$/, ''); // removes trailing semicolon/whitespace
+      unwritten = StringPrototypeReplace.call(unwritten, FUNCTION_DECL, '');
+      unwritten = StringPrototypeReplace.call(unwritten, VARIABLE_DECL, '');
+      unwritten = StringPrototypeReplace.call(unwritten, /;\s*$/, ''); // removes trailing semicolon/whitespace
       return unwritten;
     } catch (err) {
       logger.warn({ err, code }, 'Failed to unwrite function code');
@@ -114,7 +114,7 @@ module.exports = function (deps) {
 
         let code;
         if (hookedFunctions.has(data.obj)) {
-          code = toString.call(hookedFunctions.get(data.obj).fn);
+          code = FunctionPrototypeToString.call(hookedFunctions.get(data.obj).fn);
         } else {
           code = orig();
         }
@@ -135,7 +135,7 @@ module.exports = function (deps) {
   };
 
   functionHooks.uninstall = function () {
-    Function.prototype.toString = toString;
+    Function.prototype.toString = FunctionPrototypeToString;
   };
 
   return functionHooks;

package/lib/index.d.ts

@@ -15,6 +15,7 @@
 
 import { Installable } from '@contrast/common';
 import { Config } from '@contrast/config';
+import { Perf } from '@contrast/perf';
 import { Core as _Core } from '@contrast/core';
 import { Deadzones } from '@contrast/deadzones';
 import { DepHooks } from '@contrast/dep-hooks';
@@ -53,6 +54,7 @@ declare module 'node:module' {
 
 export interface Core extends _Core {
   config: Config;
+  Perf: Perf;
   logger: Logger;
   depHooks: DepHooks;
   patcher: Patcher

package/lib/index.js

@@ -16,6 +16,7 @@
 'use strict';
 
 const Module = require('module');
+
 const {
   assertValidOpts,
   preStartupValidation,
@@ -53,7 +54,7 @@ const DEFAULT_INSTALL_ORDER = [
 ];
 
 /**
- * Utility for making agents: entrypoints indended to be run via --require, --loader, --import.
+ * Utility for making agents: entrypoints intended to be run via --require, --loader, --import.
  * Composes all needed dependencies during factory instantiation, and installs various components
  * that alter an application's environment in order for composed features to operate e.g. request scopes,
  * source code rewrite hooks etc.
@@ -62,9 +63,13 @@ const DEFAULT_INSTALL_ORDER = [
  */
 module.exports = function init(core = {}) {
   core.startTime = process.hrtime.bigint();
+  if (!core.Perf) {
+    core.Perf = require('@contrast/perf');
+  }
 
   let _callback;
   let _opts;
+  const _perf = new core.Perf('agentify');
 
   core.agentify = async function agentify(callback, opts = {}) {
     // options are hardcoded, so if this throws it's going to be in testing/dev situation
@@ -126,7 +131,10 @@ module.exports = function init(core = {}) {
         await plugin.install();
       }
     } catch (err) {
-      // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
+      console.error(err);
+      console.error(ERROR_MESSAGE);
+
+     // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
       logger.error({ err }, ERROR_MESSAGE);
     }
   }
@@ -194,7 +202,7 @@ module.exports = function init(core = {}) {
       if (isDefault) {
         mod = mod.default;
       }
-      mod(core);
+      _perf.wrapInit(mod, spec)(core);
 
       // perform any validations that can take place now that this module is loaded.
       if (name === 'logger') {
@@ -215,11 +223,10 @@ module.exports = function init(core = {}) {
     // IntentionalError is used when the agent is disabled by config. We want
     // to abort the installation but not issue any messages.
     if (!(err instanceof IntentionalError)) {
+      console.error(err);
+      console.error(ERROR_MESSAGE);
       if (core.logger) {
-        core.logger.error({ err }, ERROR_MESSAGE);
-      } else {
-        console.error(err);
-        console.error(ERROR_MESSAGE);
+        core.logger?.error?.({ err }, ERROR_MESSAGE);
       }
     }
   }

package/lib/index.test.js

@@ -4,10 +4,17 @@ const { expect } = require('chai');
 const proxyquire = require('proxyquire');
 const sinon = require('sinon');
 const mocks = require('@contrast/test/mocks');
+const Perf = require('@contrast/perf');
 
 describe('agentify', function () {
   const Module = require('module');
   let agentify, preRunMain, runMain;
+  const allAgentify = new Map();
+  // the sinon stubs are captured in beforeEach(), before the agentify call,
+  // because the Perf wrapper will replace them on the core object. this way we
+  // can still determine that the function was called/not called as expected.
+  let loggerError;
+  let depHooksInstall;
 
   beforeEach(function () {
     // added because the config validation code verifies that the agent has
@@ -19,21 +26,33 @@ describe('agentify', function () {
     agentify = proxyquire('.', {
       '@contrast/logger': {
         default(core) {
-          return core.logger = mocks.logger();
+          core.logger = mocks.logger();
+          loggerError = core.logger.error;
+          return core.logger;
         }
       },
       '@contrast/dep-hooks'(core) {
-        return core.depHooks = mocks.depHooks();
+        core.depHooks = mocks.depHooks();
+        depHooksInstall = core.depHooks.install;
+        return core.depHooks;
       },
     })();
     preRunMain = sinon.stub();
     runMain = sinon.stub(Module, 'runMain');
   });
 
+  afterEach(function() {
+    Perf.fromAllToMap('agentify', allAgentify);
+  });
+
   after(function() {
     delete process.env.CONTRAST__API__API_KEY;
     delete process.env.CONTRAST__API__SERVICE_KEY;
     delete process.env.CONTRAST__API_USER_NAME;
+    const stats = Perf.getStats(allAgentify);
+    for (const [key, { n, totalMicros, mean }] of stats.entries()) {
+      console.log(key, n, totalMicros, 'nsec', mean, 'mean');
+    }
   });
 
   it('invoking with callback will initialize and patch runMain', async function () {
@@ -46,16 +65,16 @@ describe('agentify', function () {
 
     expect(preRunMain).to.have.been.calledWith(core);
     expect(runMain).to.have.been.called;
-    expect(core.depHooks.install).to.have.been.called;
-    expect(core.logger.error).not.to.have.been.called;
+    expect(depHooksInstall).to.have.been.called;
+    expect(loggerError).not.to.have.been.called;
   });
 
   it('will not run install methods when installOrder option is empty array', async function () {
-    const core = await agentify(preRunMain, { installOrder: [] });
+    const _core = await agentify(preRunMain, { installOrder: [] });
     await Module.runMain();
 
-    expect(core.depHooks.install).not.to.have.been.called;
-    expect(core.logger.error).not.to.have.been.called;
+    expect(depHooksInstall).not.called;
+    expect(loggerError).not.called;
   });
 
 
@@ -121,7 +140,7 @@ describe('agentify', function () {
 
     await Module.runMain();
 
-    expect(core.depHooks.install).not.to.have.been.called;
+    expect(depHooksInstall).not.to.have.been.called;
     expect(runMain).to.have.been.called;
     expect(core.logger.error).to.have.been.calledWith({ err });
   });

package/lib/rewrite-is-deadzoned.js

@@ -37,9 +37,10 @@ const DEADZONED_PATHS = [
   'browserify',
   'bson',
   'bunyan',
-  '@cyclonedx',
+  'chai', // not sure why chai was rewritten
   'coffeescript',
   'compression',
+  '@cyclonedx',
   'etag',
   // 'cookie', // todo: verify this doesn't break sources/propagation (*)
   // 'cookie-signature', // (*)

package/lib/utils.js

@@ -25,12 +25,15 @@ const {
   }
 } = require('../package.json');
 
+const { primordials: { StringPrototypeSlice, StringPrototypeSplit, StringPrototypeTrim } } = require('@contrast/common');
+
 /**
  * Performs various startup validation checks. All checks throw errors when they
  * fail so startup/installation stops.
  * @param {string} core.nodeEngines
  */
 function preStartupValidation(core) {
+  assertNoExperimentalFeatureFlags();
   assertSupportedNodeVersion(core.nodeEngines || nodeEngines);
   assertSupportedPreloadUsage();
 }
@@ -45,16 +48,31 @@ function preStartupValidation(core) {
 function assertSupportedNodeVersion(engines) {
   if (!semver.satisfies(process.version, engines)) {
     let validRanges = '';
-    engines.split('||').forEach((range) => {
+    StringPrototypeSplit.call(engines, '||').forEach((range) => {
       const minVersion = semver.minVersion(range).toString();
-      const maxVersion = range.split('<').pop()
-        .trim();
+      const maxVersion = StringPrototypeTrim.call(StringPrototypeSplit.call(range, '<').pop());
       validRanges += `${minVersion} and ${maxVersion}, `;
     });
     throw new Error(`Contrast only officially supports Node LTS versions between ${validRanges}but detected ${process.version}.`);
   }
 }
 
+/**
+ * Checks that no experimental feature flags are used.
+ * @throws {Error}
+ */
+function assertNoExperimentalFeatureFlags() {
+  const {
+    execArgv,
+    env: { NODE_OPTIONS },
+  } = process;
+
+  if (execArgv.some(arg => arg.includes('--experimental')) || NODE_OPTIONS?.includes('--experimental')) {
+    const msg = 'Contrast Agent does not support experimental features.';
+    throw new Error(msg);
+  }
+}
+
 /**
  * Checks that the correct preload flag is used given running node version.
  * @throws {Error}
@@ -72,8 +90,8 @@ function assertSupportedPreloadUsage() {
   if (CSI_EXPOSE_CORE === 'no-validate') return;
 
   // eslint-disable-next-line newline-per-chained-call
-  const [major, minor] = version.slice(1).split('.').map(Number);
-  const nodeOptionArgs = (NODE_OPTIONS || '').split(/\s+/).filter((v) => v);
+  const [major, minor] = StringPrototypeSplit.call(StringPrototypeSlice.call(version, 1), '.').map(Number);
+  const nodeOptionArgs = StringPrototypeSplit.call(NODE_OPTIONS || '', /\s+/).filter((v) => v);
   const allArgsToCheck = [...execArgv, ...nodeOptionArgs];
 
   let checkOccurred = false;
@@ -150,5 +168,6 @@ module.exports = {
   assertValidOpts,
   assertSupportedNodeVersion,
   assertSupportedPreloadUsage,
+  assertNoExperimentalFeatureFlags,
   preStartupValidation,
 };

package/lib/utils.test.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+
+const {
+  assertValidOpts,
+  assertSupportedNodeVersion,
+  assertSupportedPreloadUsage,
+  assertNoExperimentalFeatureFlags,
+} = require('./utils');
+
+describe('preStartupValidation', function() {
+
+  describe('assertValidOpts', function() {
+    it('Does not validate when noValidate is true', function() {
+      const opts = {
+        noValidate: true
+      };
+      expect(assertValidOpts(opts)).to.be.undefined;
+    });
+
+    it('Throws an error if install order is incorrect', function() {
+      const opts = {
+        installOrder: [
+          'telemetry',
+          'reporter',
+          'startupValidation'
+        ]
+      };
+      expect(() => assertValidOpts(opts)).to.throw('The \'installOrder\' option must include \'reporter\' as first element. found \'telemetry\'');
+    });
+  });
+
+  describe('assertSupportedNodeVersion', function() {
+
+    let engines;
+    beforeEach(function() {
+      engines = '>=16.9.1 <17 || >=18.7.0 <19 || >=20.6.0 <21 || >= 22.5.1 <23';
+    });
+
+    it('Does not throw an error if process.version is supported', function() {
+      sinon.stub(process, 'version').value('v22.9.0');
+      expect(assertSupportedNodeVersion(engines)).to.be.undefined;
+    });
+
+    it('Throws an error if process.version is unsupported', function() {
+      sinon.stub(process, 'version').value('v14.0.0');
+      expect(() => assertSupportedNodeVersion(engines)).to.throw('Contrast only officially supports Node LTS versions between 16.9.1 and 17, 18.7.0 and 19, 20.6.0 and 21, 22.5.1 and 23, but detected v14.0.0');
+    });
+
+  });
+
+  describe('assertSupportedPreloadUsage', function() {
+
+    it('does not throw an err if --import flag is used (>= 18.19.0)', function() {
+      sinon.stub(process, 'execArgv').value(['--import', '@contrast/agent']);
+      sinon.stub(process, 'version').value('v22.9.0');
+      expect(assertSupportedPreloadUsage()).to.be.true;
+    });
+
+    it('throws an err if --import flag is used (<= 18.19.0)', function() {
+      sinon.stub(process, 'execArgv').value(['--import', '@contrast/agent']);
+      sinon.stub(process, 'version').value('v18.18.0');
+      expect(() => assertSupportedPreloadUsage()).to.throw('Contrast requires that Node LTS versions >= 18.19.0 use the --import flag for ESM support');
+    });
+
+    it('throws an err if --loader flag is used (>= 18.19.0)', function() {
+      sinon.stub(process, 'execArgv').value(['--loader', '@contrast/agent']);
+      sinon.stub(process, 'version').value('v18.20.0');
+      expect(() => assertSupportedPreloadUsage()).to.throw('Contrast requires that Node versions less than 18.19.0 use the --loader flag for ESM support');
+    });
+
+  });
+
+  describe('assertNoExperimentalFeatureFlags', function() {
+    describe('process.execArgv', function() {
+      it('Does not throw an error if no experimental feature flag is used', function() {
+        sinon.stub(process, 'execArgv').value(['--import', '@contrast/agent']);
+        expect(assertNoExperimentalFeatureFlags()).to.be.undefined;
+      });
+
+      it('Throws an error if an experimental feature flag is used', function() {
+        sinon.stub(process, 'execArgv').value(['--experimental-feature', '--import', '@contrast/agent']);
+        expect(() => assertNoExperimentalFeatureFlags()).to.throw('Contrast Agent does not support experimental features.');
+      });
+    });
+
+    describe('NODE_OPTIONS', function() {
+
+      const origNodeOptions = process.env?.NODE_OPTIONS;
+
+      afterEach(function() {
+        process.env.NODE_OPTIONS = origNodeOptions;
+      });
+
+      it('Does not throw an error if no experimental feature flag is used', function() {
+        process.env.NODE_OPTIONS = '--import @contrast/agent';
+        expect(assertNoExperimentalFeatureFlags()).to.be.undefined;
+      });
+
+      it('Throws an error if an experimental feature flag is used', function() {
+        process.env.NODE_OPTIONS = '--experimental-feature --import @contrast/agent';
+        expect(() => assertNoExperimentalFeatureFlags()).to.throw('Contrast Agent does not support experimental features.');
+      });
+    });
+
+  });
+
+});

package/lib/validators.js

@@ -15,7 +15,7 @@
 
 'use strict';
 
-const { IntentionalError } = require('@contrast/common');
+const { IntentionalError, primordials: { ArrayPrototypeSlice, StringPrototypeToLowerCase } } = require('@contrast/common');
 
 // v4 accepted `-c` or `--configFile` option in argv, but v5 does not. so if
 // something that looks like a config flag is present on the command line, we
@@ -49,8 +49,8 @@ function getConfigFlag(argv) {
       // let's not because that seems false-negative prone.
 
       // if the next arg is another flag, then this isn't a contrast config flag
-      if (!argv[i + 1].startsWith('-') && argv[i + 1].toLowerCase().includes('contrast')) {
-        return argv.slice(i, i + 2);
+      if (!argv[i + 1].startsWith('-') && StringPrototypeToLowerCase.call(argv[i + 1]).includes('contrast')) {
+        return ArrayPrototypeSlice.call(argv, i, i + 2);
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agentify",
-  "version": "1.32.0",
+  "version": "1.34.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)",
@@ -17,20 +17,21 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.25.0",
-    "@contrast/config": "1.33.0",
-    "@contrast/core": "1.37.0",
-    "@contrast/deadzones": "1.7.0",
-    "@contrast/dep-hooks": "1.5.0",
-    "@contrast/esm-hooks": "2.11.0",
+    "@contrast/common": "1.26.0",
+    "@contrast/config": "1.34.0",
+    "@contrast/core": "1.39.0",
+    "@contrast/deadzones": "1.9.0",
+    "@contrast/dep-hooks": "1.7.0",
+    "@contrast/esm-hooks": "2.13.0",
     "@contrast/find-package-json": "^1.1.0",
-    "@contrast/instrumentation": "1.15.0",
-    "@contrast/logger": "1.10.0",
-    "@contrast/metrics": "1.13.0",
-    "@contrast/patcher": "1.9.0",
-    "@contrast/reporter": "1.32.0",
-    "@contrast/rewriter": "1.13.0",
-    "@contrast/scopes": "1.6.0",
+    "@contrast/instrumentation": "1.17.0",
+    "@contrast/logger": "1.12.0",
+    "@contrast/metrics": "1.15.0",
+    "@contrast/patcher": "1.11.0",
+    "@contrast/perf": "1.2.0",
+    "@contrast/reporter": "1.34.0",
+    "@contrast/rewriter": "1.15.0",
+    "@contrast/scopes": "1.8.0",
     "semver": "^7.6.0"
   }
 }