@contrast/agent 5.0.0-beta.9 → 5.0.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright: 2023 Contrast Security, Inc
+Copyright: 2024 Contrast Security, Inc
 Contact: support@contrastsecurity.com
 License: Commercial
 

package/README.md

@@ -0,0 +1,151 @@
+# Contrast Security Node.js Agent
+
+This package will enable instrumentation of your Node.js application for
+security anaylsis and runtime protection by [Contrast Security](https://www.contrastsecurity.com).
+
+Unlike legacy application security testing solutions, Contrast produces accurate
+results without dependence on application security experts. Accuracy comes from
+Contrast's patented Deep Security Instrumentation technology, which integrates
+the most effective elements of Interactive (IAST), Static (SAST), and Dynamic
+(DAST) application security testing technology, software composition analysis
+(SCA), and configuration analysis, and delivers them directly to applications.
+
+Contrast produces a continuous stream of accurate vulnerability and compliance
+risk information whenever and wherever software is run. Development, QA and
+Security teams get results as they develop and test software, enabling them to
+find and fix security flaws early in the software lifecycle, when they are
+easiest and cheapest to remediate.
+
+## New in version 5
+
+- The agent no longer ships or operates with the `contrast-service` "sidecar" executables. This allows for a drastically smaller download and simplified deployments.
+
+- Framework support includes `express`, `koa`, and `fastify`, with others soon to come.
+
+- The agent does not respond to any command-line configuration flags. Configuration options can be set using environment variables and/or `contrast_security.yaml` file. If you were previously using the agent's `-c` CLI option to set the location of your configuration file, you can use `CONTRAST_CONFIG_PATH` environment variable instead. See more about configuration [below](#configuration).
+
+- Structured logging.
+
+- Ablility to run Assess and Protect modes concurrently.
+
+
+## Getting Started
+
+Existing Contrast Node.js agent users should install and update the Contrast
+Node.js agent from [npm](https://www.npmjs.com/). The Contrast Node.js agent follows semantic
+versioning (`major.minor.patch`).
+
+An API key, provided by Contrast Security, is required for the agent to function.
+
+Ensure you have installed the latest LTS (Long Term Support) version of [Node.js](http://nodejs.org/)
+
+To install from npm using the command line (run from the app root directory):
+
+```sh
+$ npm install @contrast/agent
+```
+
+## Usage
+
+### [CommonJS (CJS) Applications](https://nodejs.org/docs/latest-v12.x/api/modules.html)
+
+CommonJS is the original Node.js module system. CJS modules are loaded with the
+`const module = require('module')` syntax.
+
+When instrumenting an application written this way, without EJS modules or ESM dependencies, use the following
+method to start the application.
+
+```sh
+  node -r @contrast/agent app-main.js [app arguments]
+```
+
+### [ECMAScript (ESM) Applications](https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_ecmascript_modules)
+
+ECMAScript modules are the _new_ official standard format to package JavaScript
+code for reuse. ES Modules are loaded with the `import module from 'module'`
+syntax.
+
+When instrumenting an application that utilizes ECMAScript Modules, use the
+following methods to start the application. This is the appropriate method for
+instrumenting an application that uses CJS, ESM, or a combination of both.
+
+- Node versions `>=16.17.0` and `<18.19.0`:
+
+    ```sh
+    node --loader @contrast/agent app-main.mjs [app arguments]
+    ```
+
+- Node versions `>=18.19.0` and `<20.0.0`, or versions `>=20.6.0`:
+
+     ```sh
+     node --import @contrast/agent app-main.mjs [app arguments]
+     ```
+
+
+### Configuration
+
+#### File Locations
+
+The agent will look for the `contrast_security.yaml` configuration file in the following locations and order:
+
+1. Within the processes current working directory, that is `${process.cwd()}/contrast_security.yaml`.
+
+1. OS-specific configuration directories.
+
+    - Unix and MacOS systems:
+
+      - `/etc/contrast/node/contrast_security.yaml`, _then_
+
+      - `/etc/contrast/contrast_security.yaml`
+
+    - Win32 systems:
+
+      - `${process.env.ProgramData}\contrast\node\contrast_security.yaml`, _then_
+
+      - `${process.env.ProgramData}\contrast\contrast_security.yaml`
+
+1. Unix home directory.
+
+    - `~/.config/contrast/node/contrast_security.yaml`, _then_
+
+    - `~/.config/contrast/contrast_security.yaml`
+
+> Note: The optional `/node/` path segment is useful in cases where you want to organize configuration files by agent language:
+> ```
+> /etc
+>   /contrast
+>     /node/contrast_security.yaml
+>     /java/contrast_security.yaml
+>     /python/contrast_security.yaml
+> ```
+
+You can also specify the location of the configuration file with the `CONTRAST_CONFIG_PATH` environment variable:
+
+```sh
+CONTRAST_CONFIG_PATH=/path/to/config.yaml node -r @contrast/agent app-main.js
+```
+
+> Note:  If `process.env.CONTRAST_CONFIG_PATH` set, the agent will look at that location _only_. If there is an issue reading the configuration file from this location the agent will not look in the standard locations described above, but instead do the following:
+> 1. Halt instrumentation
+> 2. Communicate an error
+> 3. Run the application as if without Contrast
+
+#### Minimum Configuration Option Requirements
+
+The agent requires a minimum set of configuration options be set. They are described below as YAML.
+
+```yaml
+api:
+  # Organization's API key
+  api_key: dCBvm46uEJAUV2musNFb357SnvqYrlq1
+  # Contrast user account service key
+  service_key: PZU499KK3YD4X2DT
+  # Contrast user account ID (In most cases, this is your login ID)
+  user_name: agent_d228a527-130c-18cc-93b8-20096136ba0b@UserOrg
+  # Address to the Contrast backend. This will vary.
+  url: https://app.contrastsecurity.com
+```
+
+Visit https://agent.config.contrastsecurity.com/ to use our online tool for building your YAML file interactively.
+
+For detailed installation and configuration instructions, see the [Node.js Agent documentation](https://docs.contrastsecurity.com/en/install-node-js.html).

package/lib/check-flag-vs-node-version.mjs

@@ -0,0 +1,55 @@
+/*
+ * 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.
+ */
+//
+// check to see if we're running with the correct flag (--loader or --import)
+// for the right version of node. we do not function correctly when --loader
+// is used for node >= 20 or when --import is used for node < 20.
+//
+export default function checkImportVsLoaderVsNodeVersion() {
+  // allow testing to ignore these restrictions
+  const noValidate = process.env.CSI_EXPOSE_CORE === 'no-validate';
+  let flag;
+
+  const { execArgv, version } = process;
+  // eslint-disable-next-line newline-per-chained-call
+  const [major, minor] = version.slice(1).split('.').map(Number);
+  for (let i = 0; i < execArgv.length; i++) {
+    const loader = execArgv[i];
+    const agent = execArgv[i + 1];
+    if (['--import', '--loader', '--experimental-loader'].includes(loader) && agent?.startsWith('@contrast/agent')) {
+      flag = loader;
+      if (noValidate) {
+        return { flag, msg: '' };
+      }
+      if (loader === '--import') {
+        // loader is --import
+        if (major === 18 && minor >= 19 || major >= 20) {
+          return { flag, msg: '' };
+        }
+        if (major <= 18 && minor < 19) {
+          return { flag, msg: 'Contrast requires node versions less than 18.19.0 use the --loader flag for ESM support' };
+        }
+      } else {
+        // loader is either --loader or --experimental-loader (same thing)
+        if (major >= 20 || major === 18 && minor >= 19) {
+          return { flag, msg: 'Contrast requires node versions >= 18.19.0 use the --import flag for ESM support' };
+        }
+      }
+      break;
+    }
+  }
+  // i think we only get here if flag === '--loader' and node < 20
+  return { flag, msg: '' };
+}

package/lib/esm-hooks.mjs

@@ -0,0 +1,262 @@
+/*
+ * 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';
+import { readFile as rf } from 'node:fs/promises';
+import W from 'node:worker_threads';
+
+const logLoad = 1;
+const logResolve = 2;
+const logRequireAll = 4;
+const logApplication = 8; // eslint-disable-line no-unused-vars
+let log = 0;
+if (process.env.CSI_HOOKS_LOG) {
+  log = +process.env.CSI_HOOKS_LOG;
+}
+
+const [major, minor] = process.versions.node.split('.').map(it => +it);
+const isLT16_12 = major < 16 || (major === 16 && minor < 12);
+
+// import.meta.resolve('node-fetch') v20 became synchronous. not all that useful for now because
+// of the significant break in behavior. but the function is great - it resolves a specifier to the
+// file that would be loaded.
+// file:///home/bruce/github/csi/rasp-v3/node_modules/node-fetch/src/index.js
+
+const { default: core } = await import('./initialize.mjs');
+const { esmHooks: { mappings, fixPath, getFileType } } = core;
+
+const initialize = Module.register && async function(data) {
+  if (data?.port) {
+    data.port.on('message', _msg => {
+      // we don't currently send messages to the loader thread but when we do,
+      // this is where they will show up.
+      //console.log('ESM HOOK -> INIT -> MESSAGE', _msg);
+    });
+    data.port.postMessage({ type: 'keep-alive', data: 'hello from esm-hooks' });
+    data.port.unref();
+    // this is running in the loader thread. save thread info because it can't
+    // be set from the main thread.
+    if (W.isMainThread) {
+      throw new Error('initialize() called from main thread.');
+    }
+    core.threadInfo.isMainThread = false;
+    core.threadInfo.threadId = W.threadId;
+    core.threadInfo.port = data.port;
+    // the loader thread's post() sends via the port.
+    core.threadInfo.post = (type, data) => {
+      core.threadInfo.port.postMessage({ type, data });
+    };
+  }
+
+  log && console.log('ESM HOOK -> INIT');
+  // it's not clear to me why Module is present when initialize() is being
+  // executed in the loader thread. but it is. (code here originally loaded
+  // Module via createRequire(), but that is not necessary.)
+  const originalRequire = Module.prototype.require;
+  const originalCompile = Module.prototype._compile;
+  const originalExtensions = Module._extensions['.js'];
+  const originalLoad = Module._load;
+
+  // Module needs to be patched in the loader thread too. initialize() runs in
+  // that context.
+  Module.prototype.require = function(moduleId) {
+    (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> require(${moduleId})`);
+    return originalRequire.call(this, moduleId);
+  };
+
+  Module.prototype._compile = function(code, filename) {
+    (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> _compile(${filename})`);
+    return originalCompile.call(this, code, filename);
+  };
+
+  Module._extensions['.js'] = function(module, filename) {
+    (log & logRequireAll) && console.log(`CJS(init ${W.threadId}) -> _extensions[".js"]: ${filename}`);
+    return originalExtensions.call(this, module, filename);
+  };
+
+  Module._load = function(request, parent, isMain) {
+    (log & logLoad) && console.log(`CJS(init ${W.threadId}) -> _load(${request})`);
+    return originalLoad.call(this, request, parent, isMain);
+  };
+};
+
+const resolve = async function(specifier, context, nextResolve) {
+  (log & logResolve) && console.log(`ESM HOOK(${W.threadId}) -> RESOLVE -> ${specifier}`);
+  let isFlaggedToPatch = false;
+  if (context.parentURL) {
+    isFlaggedToPatch = context.parentURL.endsWith('csi-flag=', context.parentURL.length - 1);
+  }
+
+  // this needs to be generalized so it uses the execArgv value. the idea is to
+  // capture when the application actually starts. is this needed? i don't think so
+  // because the loaders aren't instantiated until esm-loader.mjs returns/register()s
+  // the hooks. i am leaving the comment here as a breadcrumb in case we need to
+  // capture the application start time. but we could 1) look at process.argv, 2)
+  // find the first argument, and 3) notice when that's loaded and capture that
+  // "now we are in the user's application".
+  //
+  //if (false) debugger;
+  //if (log & logApplication) {
+  //  const RE = /test-integration-servers\/express.m?js(\?.+)?$/;
+  //  if (specifier.match(RE) || context.parentURL?.match(RE)) {
+  //    console.log(`ESM HOOK(${W.threadId}) -> RESOLVE -> ${specifier} from ${context.parentURL}`);
+  //  }
+  //}
+
+  // this works for most of what we need to patch because they are not esm-native
+  // modules. but for esm-native modules, e.g., node-fetch, this won't work. they
+  // will need to be patched in the loader thread.
+  //
+  // We could walk up the parent chain to see if we should interpret this specifier
+  // as a module or commonjs, but it seems more straightforward to just always
+  // redirect. walking up the parent chain would let us avoid redirecting commonjs
+  // files. we could also call nextResolve() and let node tell us type of the file
+  // is but that would potentially create problems when other hooks, e.g., datadog,
+  // are in place.
+  //
+  // also we could check to see if this module's already been patched and skip this.
+  // not sure of that though; it might get loaded as a module, not a commonjs file,
+  // and that would be a problem. so when we start patching esm-native modules, we'll
+  // need a second "already patched" weakmap.
+  if (!isFlaggedToPatch && specifier in mappings) {
+    // eslint-disable-next-line prefer-const
+    let { url, format, target } = mappings[specifier];
+    // set flag to module or commonjs. i'm not sure this is needed but am keeping it
+    // in place until we have to implement esm-native module rewrites/wrapping. this
+    // is the point at which resolve() communicates to load().
+    //
+    // builtin's are probably the most likely to be loaded, so they're first.
+    // some tweaks might be needed when we start to patch esm-native modules
+    // in esm-native-code:
+    // https://nodejs.org/docs/latest-v20.x/api/esm.html#builtin-modules
+    // https://nodejs.org/docs/latest-v20.x/api/module.html#modulesyncbuiltinesmexports
+    if (target === 'builtin') {
+      url = `${url.href}?csi-flag=m`;
+      format = 'module';
+    } else if (target === 'commonjs') {
+      url = `${url.href}?csi-flag=c`;
+      format = getFileType(url) || format || 'commonjs';
+    } else if (target === 'module') {
+      url = `${url.href}?csi-flag=m`;
+      format = getFileType(url) || format || 'module';
+    } else {
+      throw new Error(`unexpected target ${target} for ${specifier}`);
+    }
+
+    return {
+      url,
+      format,
+      shortCircuit: true,
+    };
+  }
+
+  return protectedNextResolve(nextResolve, specifier, context);
+};
+
+// readFile is a live binding. we need to capture it so it won't be
+// altered by any patching later.
+const readFile = rf;
+
+const load = async function(url, context, nextLoad) {
+  (log & logLoad) && console.log(`ESM HOOK(${W.threadId}) -> LOAD ${url}`);
+
+  const urlObject = new URL(url);
+
+  if (urlObject.searchParams.has('csi-flag')) {
+    // target type will, i think, be used to determine if this will require extra
+    // processing of some sort for esm-native modules.
+    // eslint-disable-next-line no-unused-vars
+    const targetType = urlObject.searchParams.get('csi-flag');
+    const { pathname } = urlObject;
+
+    (log & logLoad) && console.log(`ESM HOOK(${W.threadId}) -> LOAD -> CSI FLAG ${pathname}`);
+
+    const source = await readFile(fixPath(pathname), 'utf8');
+    return {
+      source,
+      format: 'module',
+      shortCircuit: true,
+    };
+  }
+
+  if (urlObject.pathname.endsWith('.node')) {
+    const metaUrl = JSON.stringify(url);
+    const addon = urlObject.pathname;
+    return {
+      source: `require("node:module").createRequire(${metaUrl})("${addon}")`,
+      format: 'commonjs',
+      shortCircuit: true,
+    };
+  }
+
+  // if it's not a builtin, a .node addon, or a flagged file, it needs to be
+  // rewritten if it's a module.
+  if (urlObject.pathname.match(/(.js|.mjs|.cjs)$/)) {
+    // if it's not a module it will be rewritten by the require hooks.
+    const type = getFileType(urlObject);
+    if (type !== 'module') {
+      return nextLoad(url, context);
+    }
+
+    const filename = fixPath(urlObject.pathname);
+    const source = await readFile(filename, 'utf8');
+
+    const rewriteOptions = {
+      filename,
+      isModule: type === 'module',
+      inject: true,
+      wrap: type !== 'module', // cannot wrap modules
+    };
+
+    core.threadInfo.post('rewrite', rewriteOptions);
+
+    const result = core.rewriter.rewrite(source, rewriteOptions);
+
+    return {
+      source: result.code,
+      format: type || 'commonjs', // don't know what else to do here. log?
+      shortCircuit: true,
+    };
+  }
+  // this never gets called, so hmmm.
+  return nextLoad(url, context);
+};
+
+// from esmock: git@github.com:iambumblehead/esmock.git
+//
+// new versions of node: when multiple loaders are used and context
+// is passed to nextResolve, the process crashes in a recursive call
+// see: /esmock/issues/#48
+//
+// old versions of node: if context.parentURL is defined, and context
+// is not passed to nextResolve, the tests fail
+//
+// later versions of node v16 include 'node-addons'
+async function protectedNextResolve(nextResolve, specifier, context) {
+  if (context.parentURL) {
+    if (context.conditions.at(-1) === 'node-addons' || context.importAssertions || isLT16_12) {
+      return nextResolve(specifier, context);
+    }
+  }
+
+  return nextResolve(specifier);
+}
+
+export {
+  load,
+  resolve,
+  initialize,
+  // TODO: add for testing/verification
+  //loaderIsVerified as default
+};

package/lib/esm-loader.mjs

@@ -0,0 +1,149 @@
+/*
+ * 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';
+import W from 'node:worker_threads';
+import EventEmitter from 'node:events';
+
+import checkImportVsLoaderVsNodeVersion from './check-flag-vs-node-version.mjs';
+
+// might need to get exclude function here as opposed to deep within initialize
+// execution.
+// 1) core should be a singleton so it's always shared between modules
+// 2) core should include the redirect map.
+// 3) is the exclude function needed here as we move to async loading? if so,
+//    this will need to add the root directory(ies) to an exclude list.
+
+const logLoad = 1;
+// eslint-disable-next-line no-unused-vars
+const logResolve = 2;
+const logRequireAll = 4;
+let log = 0;
+if (process.env.CSI_HOOKS_LOG) {
+  log = +process.env.CSI_HOOKS_LOG;
+}
+
+// verify that we're running with the correct flag for the version of node.
+const { flag, msg } = checkImportVsLoaderVsNodeVersion();
+if (msg) {
+  console.error(msg);
+  throw new Error(msg);
+  // belt and suspenders
+  // eslint-disable-next-line no-unreachable
+  process.exit(1); // eslint-disable-line no-process-exit
+}
+
+//
+// if CJS hooks are not already setup, setup CJS hooks. each thread must patch
+// Module. I don't think this will be called more than once, but the flag is
+// in place just in case.
+//
+let core;
+
+if (!core) {
+  core = (await import('./initialize.mjs')).default;
+
+  // most of this can be removed; it's here for debugging. but considering the relatively
+  // low cost compared with loading a module, i'm leaving it in.
+  (log & logRequireAll) && console.log('ESM-LOADER executing CJS Module patching');
+  const originalRequire = Module.prototype.require;
+  const originalCompile = Module.prototype._compile;
+  const originalExtensions = Module._extensions['.js'];
+  const originalLoad = Module._load;
+  if (originalLoad?.name !== '__loadOverride') {
+    // debugger; // this is a good place to make a quick check if things aren't working
+  }
+
+  Module.prototype.require = function(moduleId) {
+    (log & logRequireAll) && console.log('CJS -> require() called for', moduleId);
+    return originalRequire.call(this, moduleId);
+  };
+
+  Module.prototype._compile = function(code, filename) {
+    (log & logRequireAll) && console.log('CJS -> _compile() called for', filename);
+    return originalCompile.call(this, code, filename);
+  };
+
+  Module._extensions['.js'] = function(module, filename) {
+    (log & logRequireAll) && console.log('CJS -> _extensions[".js"] called for', filename);
+    return originalExtensions.call(this, module, filename);
+  };
+
+  Module._load = function(request, parent, isMain) {
+    (log & logLoad) && console.log(`CJS(${W.threadId}) -> _load() ${request}`);
+    return originalLoad.call(this, request, parent, isMain);
+  };
+}
+
+core.threadInfo.syncEmitter = new EventEmitter();
+// abstract how notifications are posted so that the non-loader
+// code is not coupled to the implementation. the loader-thread
+// complement of this is in esm-hooks.
+//
+// specifically, this is the main thread and post() directly emits
+// the event while in the loader thread post() uses post.postMessage()
+// to communicate back to this (the main) thread.
+core.threadInfo.post = (type, data) => {
+  core.threadInfo.syncEmitter.emit(type, data);
+};
+
+//
+// setup ESM hooks
+//
+// if register exists this is 20.6.0 or later. we do not support
+// node 20 prior to 20.6.0 (or 20.9.0 when 20 became LTS).
+// news flash: backported register to node 18.19.0, so checking register
+// is no longer enough.
+//
+if (Module.register && flag === '--import') {
+  // this file should never be executed in the loader thread; this file creates
+  // the loader thread by calling register(). the loader thread must create its
+  // own copy of threadInfo and insert it into core.
+  if (!core.threadInfo.isMainThread) {
+    // only get an error in CI on node v18.
+    throw new Error('esm-loader.mjs should not be executed in the loader thread');
+  }
+  const { MessageChannel } = await import('node:worker_threads');
+  const { port1, port2 } = new MessageChannel();
+
+
+  core.threadInfo.port = port1;
+  // messages received on the port are re-emitted as standard node events. the
+  // body must contain the type; data can be undefined.
+  core.threadInfo.missingTypeCount = 0;
+  core.threadInfo.port.on('message', (body) => {
+    const { type, data } = body;
+    if (type) {
+      core.threadInfo.syncEmitter.emit(type, data);
+    } else {
+      core.threadInfo.missingTypeCount += 1;
+    }
+  });
+  core.threadInfo.port.unref();
+
+  // record the URL of the entry point.
+  core.threadInfo.url = import.meta.url;
+
+  // get relative URL
+  const url = new URL('./esm-hooks.mjs', import.meta.url);
+  await Module.register(url.href, import.meta.url, { data: { port: port2 }, transferList: [port2] });
+}
+
+// it's not possible to conditionally export, but exporting undefined
+// values is close.
+import * as hooks from './esm-hooks.mjs';
+const finalHooks = (Module.register && flag === '--import') ? {} : hooks;
+const { load, resolve } = finalHooks;
+export { load, resolve };

package/lib/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2023 Contrast Security, Inc
+ * Copyright: 2024 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -53,15 +53,22 @@ agentify((core) => {
   };
 
   core.npmVersionRange = npmEngine;
+  require('@contrast/telemetry')(core);
   require('@contrast/assess')(core);
   require('@contrast/architecture-components')(core);
   require('@contrast/library-analysis')(core);
   require('@contrast/route-coverage')(core);
   require('@contrast/protect')(core); // protect loads lastly, being the only non-passive feature
+
+  if (process.env.CSI_EXPOSE_CORE) {
+    const coreKey = Symbol.for('contrast:core');
+    global[coreKey] = core;
+  }
 }, {
   installOrder: [
     'reporter',
     'startupValidation',
+    'telemetry',
     'contrastMethods',
     'deadzones',
     'scopes',

package/lib/initialize.mjs

@@ -0,0 +1,132 @@
+/*
+ * 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.
+ */
+
+// this file is the bootstrap for starting the agent's loader. it needs to be executed
+// in the main thread and the loader thread. it should not try to load all the modules
+// required to fully instantiate the agent, but only those required to make the loader
+// work.
+
+import { default as semver } from 'semver';
+import { default as Module } from 'node:module';
+import { isMainThread, threadId } from 'node:worker_threads';
+
+const require = Module.createRequire(import.meta.url);
+
+const {
+  name: agentName,
+  version: agentVersion,
+  engines: {
+    node: nodeEngine,
+    npm: npmEngine
+  }
+} = require('../package.json');
+
+const installOrder = [
+  'reporter',
+  'startupValidation',
+  'contrastMethods',
+  'deadzones',
+  'scopes',
+  'sources',
+  'architectureComponents',
+  'assess',
+  'protect',
+  'depHooks',
+  'esmHooks',
+  'routeCoverage',
+  'libraryAnalysis',
+  'heapSnapshots',
+  'rewriteHooks',
+  'functionHooks',
+  'metrics',
+];
+
+//
+// In order to avoid breaking every test and function in the agent, agentify
+// isn't changed at all; initialize() replaces it with new behavior.
+//
+import { loadModules, startAgent } from '@contrast/agentify/lib/initialize.mjs';
+
+let core;
+
+if (!core) {
+  // self-identification
+  const me = import.meta.url;
+  // we can determine when the app is being run by examining this
+  const argv = process.argv.slice();
+  // we can tell how the agent was started by examining this. --loader/--import must
+  // be correct for the node version.
+  const execArgv = process.execArgv.slice();
+
+  core = { agentName, agentVersion, me, argv, execArgv };
+
+  core = await loadModules({ core, options: {} });
+
+  core = await startAgent({ core, options: { executor, installOrder } });
+
+  // self identification
+  // for communications between the main and loader thread (if present)
+  core.threadInfo = {
+    isMainThread,
+    threadId,
+    port: undefined, // filled in if there's a loader thread
+    post: () => {}, // replaced by appropriate function
+  };
+
+  if (process.env.CSI_EXPOSE_CORE) {
+    const coreKey = Symbol.for('contrast:core');
+    global[coreKey] = core;
+  }
+
+}
+
+
+export default core;
+
+async function executor(core) {
+  if (!semver.satisfies(process.version, nodeEngine)) {
+    let validRanges = '';
+    nodeEngine.split('||').forEach((range) => {
+      const minVersion = semver.minVersion(range).toString();
+      const maxVersion = range.split('<').pop()
+        .trim();
+      validRanges += `${minVersion} and ${maxVersion}, `;
+    });
+    throw new Error(`Contrast supports Node LTS versions between ${validRanges}but detected ${process.version}.`);
+  }
+
+  core.startupValidation = {
+    /**
+     *  This will run after we onboard to the UI and pick up any remote settings.
+     */
+    install() {
+      if (
+        !core.config.getEffectiveValue('assess.enable') &&
+        !core.config.getEffectiveValue('protect.enable')
+      ) {
+        throw new Error('Neither Assess nor Protect are enabled. Check local configuration and UI settings');
+      }
+    }
+  };
+
+  core.npmVersionRange = npmEngine;
+  require('@contrast/assess')(core);
+  require('@contrast/architecture-components')(core);
+  require('@contrast/library-analysis')(core);
+  require('@contrast/route-coverage')(core);
+  require('@contrast/protect')(core); // protect loads last; the other features are all passive
+
+  return core; // should this return core or just null/undefined?
+}

package/package.json

@@ -1,28 +1,33 @@
 {
   "name": "@contrast/agent",
-  "version": "5.0.0-beta.9",
+  "version": "5.0.0",
   "description": "Assess and Protect agents for Node.js",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
   "files": [
     "lib/"
   ],
+  "exports": {
+    "import": "./lib/esm-loader.mjs",
+    "require": "./lib/index.js"
+  },
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "engines": {
     "npm": ">=6.13.7 <7 || >= 8.3.1",
-    "node": ">=14.15.0 <15 || >=16.9.1 <17 || >=18.7.0 <19 || >=20.5.0 <21"
+    "node": ">=14.15.0 <15 || >=16.9.1 <17 || >=18.7.0 <19 || >=20.6.0 <21"
   },
   "scripts": {
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/agentify": "1.16.0",
-    "@contrast/architecture-components": "1.13.1",
-    "@contrast/assess": "1.17.0",
-    "@contrast/library-analysis": "1.14.0",
-    "@contrast/protect": "1.28.1",
-    "@contrast/route-coverage": "1.12.0",
+    "@contrast/agentify": "1.18.0",
+    "@contrast/architecture-components": "1.14.0",
+    "@contrast/assess": "1.20.0",
+    "@contrast/library-analysis": "1.15.1",
+    "@contrast/protect": "1.30.0",
+    "@contrast/route-coverage": "1.14.0",
+    "@contrast/telemetry": "1.2.0",
     "semver": "^7.3.7"
   }
 }