@contrast/agentify 1.20.0 → 1.21.0

package/lib/index.js

@@ -19,6 +19,14 @@ const Module = require('module');
 const { IntentionalError } = require('@contrast/common');
 
 const ERROR_MESSAGE = 'An error prevented the Contrast agent from installing. The application will be run without instrumentation.';
+/**
+ * Specific agents may want to add their startup validation to this list as needed.
+ * We have to install the reporter first since installation is contingent on TS onboarding responses.
+ * Otherwise, the order of installing side effects doesn't matter too much. Ideally, the installations
+ * that most affect the environment and "normal" execution of things should be done lastly e.g. modifying prototypes.
+ * A good rule might be to install in the order such that side-effects that are easier to undo should be done first.
+ * With that rule in mind, ESM support is the most complex (loader agent) so it should come last.
+ */
 const DEFAULT_INSTALL_ORDER = [
   'reporter',
   'contrastMethods',
@@ -32,16 +40,87 @@ const DEFAULT_INSTALL_ORDER = [
   'routeCoverage',
   'libraryAnalysis',
   'heapSnapshots',
+  'metrics',
   'rewriteHooks',
   'functionHooks',
-  'metrics',
+  'esmHooks',
 ];
 
 /**
+ * Utility for making agents: entrypoints indended 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.
  * @param {any} core
  * @returns {import('.').Agentify}
  */
 module.exports = function init(core = {}) {
+  let _callback;
+  let _opts;
+
+  core.agentify = async function agentify(callback, opts = {}) {
+    _callback = callback;
+    _opts = opts;
+    _opts.type = _opts.type ?? 'cjs';
+    _opts.installOrder = _opts.installOrder ?? DEFAULT_INSTALL_ORDER;
+
+    // for 'cjs' we hook runMain and install prior to running it
+    if (_opts.type === 'cjs') {
+      if (typeof callback !== 'function') {
+        throw new Error('Invalid usage: first argument must be a function');
+      }
+      const { runMain } = Module;
+      /**
+       * This is one side effect that will always occur, even with `installOrder: []`.
+       * The act of calling `agentify()` is enough to cause this side effect, by design.
+       */
+      Module.runMain = async function (...args) {
+        await install();
+        return runMain.apply(this, args);
+      };
+    } else {
+      // for 'esm' we load esm-hooks support, which will install lastly
+      const { default: esmHooks } = await import('@contrast/esm-hooks/lib/index.mjs');
+      esmHooks(core);
+
+      await install();
+    }
+
+    return core;
+  };
+
+  async function install() {
+    const { config, logger } = core;
+
+    try {
+      for (const err of config._errors) {
+        throw err; // move this into config itself since we now handle errors
+      }
+
+      logger.info('Starting %s v%s', core.agentName, core.agentVersion);
+      logger.info({ config }, 'Agent configuration');
+
+      const plugin = await _callback?.(core);
+
+      for (const svcName of _opts.installOrder ?? []) {
+        const svc = core[svcName];
+        if (svc?.install) {
+          logger.trace('installing service: %s', svcName);
+          await svc.install();
+        }
+      }
+
+      if (plugin?.install) {
+        await plugin.install();
+      }
+
+      core.logDiagnosticFiles(); // should this be moved into a separate install side-effect?
+    } catch (err) {
+      // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
+      logger.error({ err }, ERROR_MESSAGE);
+    }
+  }
+
   try {
     require('@contrast/core/lib/messages')(core);
     require('@contrast/config')(core);
@@ -49,8 +128,6 @@ module.exports = function init(core = {}) {
       throw core.config._errors[0];
     }
     require('@contrast/logger').default(core);
-
-    // @contrast/info ?
     require('@contrast/core/lib/agent-info')(core);
     require('@contrast/core/lib/system-info')(core);
     require('@contrast/core/lib/app-info')(core);
@@ -62,77 +139,20 @@ module.exports = function init(core = {}) {
     require('@contrast/dep-hooks')(core);
     require('@contrast/patcher')(core);
     require('@contrast/core/lib/capture-stacktrace')(core);
-
     require('@contrast/rewriter')(core); // merge contrast-methods?
     require('@contrast/core/lib/contrast-methods')(core); // can we remove dependency on patcher?
-
     require('@contrast/scopes')(core);
     require('@contrast/deadzones')(core);
     require('@contrast/reporter').default(core);
     require('@contrast/instrumentation')(core);
     require('@contrast/metrics')(core);
 
-    // compose add'l local services
+    // compose additional local services
     require('./heap-snapshots')(core);
     require('./sources')(core);
     require('./function-hooks')(core);
     require('./log-diagnostic-files')(core); // this doesn't really belong in agentify
     require('./rewrite-hooks')(core);
-
-    /**
-     * The interface is a function, which when called, will hook runMain
-     * @type {import('.').Agentify}
-     */
-    core.agentify = function agentify(
-      preRunMain,
-      { installOrder = DEFAULT_INSTALL_ORDER } = {},
-    ) {
-      if (typeof preRunMain !== 'function') {
-        throw new Error('Invalid usage: first argument must be a function');
-      }
-
-      const { runMain } = Module;
-      const { config, logger } = core;
-
-      /**
-       * This is one side effect that will always occur, even with `installOrder: []`.
-       * The act of calling `agentify()` is enough to cause this side effect, by design.
-       */
-      Module.runMain = async function (...args) {
-        try {
-          for (const err of config._errors) {
-            throw err; // move this into config itself since we now handle errors
-          }
-
-          logger.info('Starting %s v%s', core.agentName, core.agentVersion);
-          // pino serializers know how to log redacted values and omit certain props
-          logger.info({ config }, 'Agent configuration');
-
-          const plugin = await preRunMain(core);
-
-          for (const svcName of installOrder ?? []) {
-            const svc = core[svcName];
-            if (svc?.install) {
-              logger.trace('installing service: %s', svcName);
-              await svc.install();
-            }
-          }
-
-          if (plugin?.install) {
-            await plugin.install();
-          }
-
-          core.logDiagnosticFiles(); // should this be moved into a separate install side-effect?
-        } catch (err) {
-          // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
-          logger.error({ err }, ERROR_MESSAGE);
-        }
-
-        return runMain.apply(this, args);
-      };
-
-      return core;
-    };
   } catch (err) {
     // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
     core.agentify = function agentify() {
@@ -151,3 +171,5 @@ module.exports = function init(core = {}) {
 
   return core.agentify;
 };
+
+module.exports.DEFAULT_INSTALL_ORDER = DEFAULT_INSTALL_ORDER;

package/lib/rewrite-hooks.js

@@ -44,8 +44,6 @@ module.exports = function init(core) {
           inject: true,
           wrap: true,
         };
-        // if threadInfo is present, this is running with --loader or --import
-        core.threadInfo?.post('rewrite', options);
 
         const { code } = core.rewriter.rewrite(content, options);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agentify",
-  "version": "1.20.0",
+  "version": "1.21.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,17 +17,17 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.18.0",
-    "@contrast/config": "1.25.0",
-    "@contrast/core": "1.29.0",
+    "@contrast/common": "1.19.0",
+    "@contrast/config": "1.26.0",
+    "@contrast/core": "1.30.0",
     "@contrast/deadzones": "1.1.2",
     "@contrast/dep-hooks": "1.3.1",
-    "@contrast/esm-hooks": "2.2.0",
-    "@contrast/instrumentation": "1.5.0",
-    "@contrast/logger": "1.7.2",
-    "@contrast/metrics": "1.4.0",
+    "@contrast/esm-hooks": "2.3.0",
+    "@contrast/instrumentation": "1.6.0",
+    "@contrast/logger": "1.8.0",
+    "@contrast/metrics": "1.5.0",
     "@contrast/patcher": "1.7.1",
-    "@contrast/reporter": "1.24.0",
+    "@contrast/reporter": "1.25.0",
     "@contrast/rewriter": "1.4.2",
     "@contrast/scopes": "1.4.0"
   }

package/lib/initialize.mjs

@@ -1,156 +0,0 @@
-/*
- * Copyright: 2024 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.
- */
-
-import Module from 'node:module';
-// want to only initialize some of the agent if main thread. not sure that's really
-// possible. based on logging, it looks like all of the low-level hooks (rewrite-injection,
-// assess-dataflow-propagators, assess-dataflow-sink ContrastMethods, and function-hooks)
-// are added in both the main thread and the loader thread. But all other modules are loaded
-// in the main thread. presumably, this is because the assess module was loaded in both
-// threads, registered the appropriate patchers in each, so both convert 'import' (statement
-// or function) to 'require'.
-//
-import { isMainThread, threadId } from 'node:worker_threads';
-
-const ERROR_MESSAGE = 'An error prevented the Contrast agent from installing. The application will be run without instrumentation.';
-const DEFAULT_INSTALL_ORDER = [
-  'reporter',
-  'contrastMethods',
-  'deadzones',
-  'scopes',
-  'sources',
-  'architectureComponents',
-  'assess',
-  'protect',
-  'depHooks',
-  'esmHooks',
-  'routeCoverage',
-  'libraryAnalysis',
-  'heapSnapshots',
-  'rewriteHooks',
-  'functionHooks',
-  'metrics',
-];
-
-const require = Module.createRequire(import.meta.url);
-let startupError;
-
-/**
- * @param {object} { core = {}, options = {} }
- */
-async function loadModules({ core = {}, options = {} }) {
-  try {
-    require('@contrast/core/lib/messages')(core);
-    require('@contrast/config')(core);
-    if (core.config._errors?.length) {
-      throw core.config._errors[0];
-    }
-    require('@contrast/logger').default(core);
-
-    const thread = isMainThread ? 'main' : 'loader';
-    core.logger.trace({ tid: threadId }, 'initializing core modules in %s thread', thread);
-
-    if (isMainThread) {
-      // @contrast/info ?
-      require('@contrast/core/lib/agent-info')(core);
-      require('@contrast/core/lib/system-info')(core);
-      require('@contrast/core/lib/app-info')(core);
-      if (core.appInfo._errors?.length) {
-        throw core.appInfo._errors[0];
-      }
-      require('@contrast/core/lib/sensitive-data-masking')(core);
-      require('@contrast/core/lib/is-agent-path')(core);
-      require('@contrast/dep-hooks')(core);
-    }
-
-    const { default: install } = await import('@contrast/esm-hooks');
-    const esmHooks = await install(core);
-    core.esmHooks = esmHooks;
-
-    if (isMainThread) {
-      require('@contrast/patcher')(core);
-      require('@contrast/core/lib/capture-stacktrace')(core);
-    }
-
-    require('@contrast/rewriter')(core); // merge contrast-methods?
-
-    if (isMainThread) {
-      require('@contrast/core/lib/contrast-methods')(core); // can we remove dependency on patcher?
-
-      require('@contrast/scopes')(core);
-      require('@contrast/deadzones')(core);
-      require('@contrast/reporter').default(core);
-      require('@contrast/instrumentation')(core);
-      require('@contrast/metrics')(core);
-
-      require('./heap-snapshots')(core);
-      require('./sources')(core);
-      require('./function-hooks')(core);
-      require('./log-diagnostic-files')(core); // this doesn't really belong in agentify
-      require('./rewrite-hooks')(core);
-    }
-
-  } catch (err) {
-    // TODO: Consider proper UNINSTALLATION and normal startup w/o agent
-    if (core.logger) {
-      core.logger.error({ err, threadId }, ERROR_MESSAGE);
-    } else {
-      console.error(new Error(ERROR_MESSAGE, { cause: err }));
-    }
-    startupError = err;
-  }
-  return core;
-}
-
-async function startAgent({ core, options = {} }) {
-  if (startupError) return;
-
-  const { executor, installOrder = DEFAULT_INSTALL_ORDER } = options;
-  const { config, logger } = core;
-
-  // this should be moved into config because errors are handled here now.
-  for (const error of config._errors) {
-    throw error;
-  }
-
-  logger.info({ tid: threadId }, 'Starting %s v%s', core.agentName, core.agentVersion);
-  logger.info({ config }, 'Agent configuration');
-
-  let plugin;
-  if (typeof executor === 'function') {
-    plugin = await executor(core);
-  }
-
-  for (const svcName of installOrder ?? []) {
-    const svc = core[svcName];
-    if (svc?.install) {
-      logger.trace({ tid: threadId }, 'installing service: %s', svcName);
-      await svc.install();
-    }
-  }
-
-  if (plugin?.install) {
-    await plugin.install();
-  }
-
-  // should this be moved into a separate install side-effect?
-  if (isMainThread) {
-    core.logDiagnosticFiles();
-  }
-
-  return core;
-}
-
-export { loadModules, startAgent };