@contrast/agentify 1.20.1 → 1.22.0

package/lib/function-hooks.js

@@ -78,7 +78,7 @@ module.exports = function (deps) {
     // cannot parse lone function expressions that are not part of an assignment.
     try {
       let unwritten = functionHooks.contextualizeFunction(code);
-      unwritten = rewriter.unwrite(unwritten);
+      unwritten = rewriter.unwriteSync(unwritten);
       unwritten = unwritten.replace(METHOD_CONTEXT, '');
       unwritten = unwritten.replace(FUNCTION_CONTEXT, '');
       unwritten = unwritten.replace(/;\s*$/, ''); // removes trailing semicolon/whitespace

package/lib/index.d.ts

@@ -13,21 +13,36 @@
  * way not consistent with the End User License Agreement.
  */
 
-import { Config } from '@contrast/config';
 import { Installable } from '@contrast/common';
+import { Config } from '@contrast/config';
+import { Core as _Core } from '@contrast/core';
 import { Logger } from '@contrast/logger';
 import { Rewriter } from '@contrast/rewriter';
 import RequireHook from '@contrast/require-hook';
+import { Patcher } from '@contrast/patcher';
+import { Scopes } from '@contrast/scopes';
+import { Deadzones } from '@contrast/deadzones';
+import { ReporterBus } from '@contrast/reporter';
 
 declare module 'module' {
   class Module {
     /**
+     * @see https://github.com/nodejs/node/blob/main/lib/internal/modules/cjs/loader.js
+     * @param content The source code of the module
+     * @param filename The file path of the module
+     */
+    _compile(content: string, filename: string);
+
+    static _extensions: {
+      /**
        * @see https://github.com/nodejs/node/blob/main/lib/internal/modules/cjs/loader.js
-       * @param content The source code of the module
+       * @param module The module to compile
        * @param filename The file path of the module
        */
-    _compile(content: string, filename: string);
+      ['.js'](module: import('module'), filename: string);
+    };
   }
+
   export = Module;
 }
 
@@ -36,13 +51,17 @@ declare module 'node:module' {
   export = Module;
 }
 
-// TODO: this is now much larger with all of the existing core deps
-export interface Core {
-  readonly config: Config;
-  readonly depHooks: RequireHook;
-  readonly logger: Logger;
-  readonly rewriter: Rewriter;
-  readonly threadInfo: any;
+export interface Core extends _Core {
+  config: Config;
+  logger: Logger;
+  depHooks: RequireHook;
+  patcher: Patcher
+  rewriter: Rewriter;
+  scopes: Scopes;
+  deadzones: Deadzones;
+  reporter: ReporterBus;
+  instrumentation: any;
+  metrics: any;
 }
 
 export interface AgentifyOptions {
@@ -50,13 +69,13 @@ export interface AgentifyOptions {
 }
 
 export interface PreRunMain {
-  (core: any): Installable | void | Promise<Installable | void>;
+  (core: Core): Installable | void | Promise<Installable | void>;
 }
 
 export interface Agentify {
-  (preRunMain: PreRunMain, opts?: AgentifyOptions): any;
+  (preRunMain: PreRunMain, opts?: AgentifyOptions): Installable | void;
 }
 
-declare function init(core: any): Agentify;
+declare function init(core: Partial<Core>): Agentify;
 
 export = init;

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,89 @@ 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 = {}) {
+  core.startTime = process.hrtime.bigint();
+
+  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 +130,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 +141,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 +173,5 @@ module.exports = function init(core = {}) {
 
   return core.agentify;
 };
+
+module.exports.DEFAULT_INSTALL_ORDER = DEFAULT_INSTALL_ORDER;

package/lib/rewrite-hooks.js

@@ -16,7 +16,7 @@
 
 'use strict';
 
-const Module = require('module');
+const Module = require('node:module');
 
 /**
  * @param {import('.').Core & {
@@ -25,11 +25,12 @@ const Module = require('module');
  * @returns {import('@contrast/common').Installable}
  */
 module.exports = function init(core) {
+  const js = Module._extensions['.js'];
   const { _compile } = Module.prototype;
 
   core.rewriteHooks = {
     install() {
-      if (!core.config.agent.node.enable_rewrite) return;
+      if (!core.config.agent.node.rewrite.enable) return;
 
       /**
        * @see https://github.com/nodejs/node/blob/main/lib/internal/modules/cjs/loader.js
@@ -37,35 +38,58 @@ module.exports = function init(core) {
        * @param {string} filename The file path of the module
        */
       Module.prototype._compile = function (content, filename) {
-        let result;
+        /** @type {import('@contrast/rewriter').RewriteOpts} */
         const options = {
           filename,
           isModule: false,
           inject: true,
           wrap: true,
+          trim: false,
         };
-        // if threadInfo is present, this is running with --loader or --import
-        core.threadInfo?.post('rewrite', options);
 
-        const { code } = core.rewriter.rewrite(content, options);
+        const result = core.rewriter.rewriteSync(content, options);
 
         try {
-          result = _compile.call(this, code, filename);
+          const compiled = Reflect.apply(_compile, this, [result.code, filename]);
+
+          if (core.config.agent.node.rewrite.cache.enable) {
+            core.rewriter.cache.write(filename, result);
+          }
+
+          return compiled;
         } catch (err) {
           core.logger.warn(
             { err },
             'Failed to compile rewritten code for %s, compiling original code.',
             filename,
           );
-          result = _compile.call(this, content, filename);
+
+          return Reflect.apply(_compile, this, [content, filename]);
         }
+      };
+
+      /**
+       * @see https://github.com/nodejs/node/blob/main/lib/internal/modules/cjs/loader.js
+       * @param {Module} module The module to compile
+       * @param {string} filename The file path of the module
+       */
+      Module._extensions['.js'] = function (module, filename) {
+        if (!core.config.agent.node.rewrite.cache.enable) {
+          return Reflect.apply(js, this, [module, filename]);
+        }
+
+        const cached = core.rewriter.cache.readSync(filename);
 
-        return result;
+        // If cached, short circuit the _extensions method and go straight to compile.
+        return cached
+          ? Reflect.apply(_compile, module, [cached, filename])
+          : Reflect.apply(js, this, [module, filename]);
       };
     },
 
     uninstall() {
       Module.prototype._compile = _compile;
+      Module._extensions['.js'] = js;
     }
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agentify",
-  "version": "1.20.1",
+  "version": "1.22.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,18 +17,18 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.18.0",
-    "@contrast/config": "1.25.0",
-    "@contrast/core": "1.29.1",
+    "@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.1",
-    "@contrast/instrumentation": "1.5.0",
-    "@contrast/logger": "1.7.2",
-    "@contrast/metrics": "1.4.0",
+    "@contrast/esm-hooks": "2.4.0",
+    "@contrast/instrumentation": "1.6.0",
+    "@contrast/logger": "1.8.0",
+    "@contrast/metrics": "1.6.0",
     "@contrast/patcher": "1.7.1",
-    "@contrast/reporter": "1.24.0",
-    "@contrast/rewriter": "1.4.2",
+    "@contrast/reporter": "1.25.1",
+    "@contrast/rewriter": "1.5.0",
     "@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 };