@contrast/agent 3.11.10

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright: 2021 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,111 @@
+# 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.
+
+## Getting Started
+
+Existing Contrast Node.js agent users should install and update the Contrast
+Node.js agent from [npm](https://www.npmjs.com/). Auto-update for the Node.js
+agent is no longer supported. 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
+
+### Using [CommonJS (CJS)](https://nodejs.org/docs/latest-v12.x/api/modules.html) Modules
+
+CommonJS is the original Node.js module system. CJS modules are loaded with the
+`const module = require('module')` syntax.
+
+When instrumenting an application written with CJS modules, use the following
+method to start the application.
+
+```
+    Usage: node -r @contrast/agent app-main.js [agent arguments] -- [app arguments]
+
+    Options:
+
+        -h, --help               output usage information
+        -V, --version            output the version number
+        -c, --configFile <path>  path to agent config file
+```
+
+### Using [ECMAScript Modules (ESM)](https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_ecmascript_modules)
+
+> NOTE: ECMAScript instrumentation is experimental and Contrast requires at least Node version 14.15.0 for support.
+
+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 method to start the application. This is the appropriate method for
+instrumenting an application that uses CJS, ESM, or a combination of both.
+
+```
+    Usage: node --experimental-loader @contrast/agent/esm.mjs app-main.mjs [agent arguments] -- [app arguments]
+
+    Options:
+
+        -h, --help               output usage information
+        -V, --version            output the version number
+        -c, --configFile <path>  path to agent config file
+```
+
+### Configuration
+
+The agent expects that the `contrast_security.yaml` configuration file exists in
+the application's root directory (where the `package.json` file usually resides).
+
+If you need to specify a different location for the configuration file you can
+use either the `-c` or `--configFile` command-line arguments or provide the
+`CONTRAST_CONFIG_PATH` environment variable:
+
+```
+node -r @contrast/agent app-main.js -c /path/to/config.yml
+node -r @contrast/agent app-main.js --configFile /path/to/config.yml
+CONTRAST_CONFIG_PATH=/path/to/config.yml node -r @contrast/agent app-main.js
+```
+
+The minimum required `contrast_security.yaml` setup should look something like
+this:
+
+```
+api:
+  url: https://app.contrastsecurity.com
+  user_name: contrast_user
+  api_key: demo
+  service_key: demo
+```
+
+| Property        | Description                                                                 |
+| :-------------- | :-------------------------------------------------------------------------- |
+| api.api_key     | Organization's API key                                                      |
+| api.user_name   | Contrast user account ID (In most cases, this is your login ID)             |
+| api.service_key | Contrast user account service key                                           |
+| api.url         | Address of the Contrast installation you would like your agent to report to |
+
+For detailed installation and configuration instructions, see the [Node.js Agent documentation](https://docs.contrastsecurity.com/installation-nodeconfig.html).

package/agent-loader.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+Copyright: 2021 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.
+*/
+const process = require('process');
+const path = require('path');
+const fs = require('fs');
+
+function load() {
+  cleanArgv();
+  require('./loader.js');
+  let PATH;
+
+  // for local development
+  if (fs.existsSync(`${__dirname + path.sep}lib`)) {
+    PATH = './lib/contrast';
+  } else {
+    PATH = './lib.asar/contrast';
+  }
+
+  return require(PATH);
+}
+
+/**
+ * TODO: Remove w/ release of v3.0.0.
+ * We do this to prevent bad restart argument passed by buggy app-update code in
+ * older agents. We filter out the known bad option iff if it is used as an
+ * agent argument (occurrance is before -- in argument list).
+ */
+function cleanArgv() {
+  process.argv = process.argv.filter((value) => {
+    if (value === '--') {
+      module.exports.seenDashDash = true;
+      return true;
+    }
+    return value === '--agent.auto_update.enable false'
+      ? module.exports.seenDashDash
+      : true;
+  });
+}
+
+module.exports = load();
+module.exports.load = load;
+module.exports.cleanArgv = cleanArgv;
+module.exports.seenDashDash = false;

package/bin/VERSION

@@ -0,0 +1 @@
+2.26.0

package/bootstrap.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+Copyright: 2021 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.
+*/
+
+const startTime = process.hrtime();
+
+const Module = require('module');
+const loader = require('./agent-loader');
+const orig = Module.runMain;
+
+/**
+ * Calling contrast bootstrapping
+ * process before invoking the main
+ * script from cli
+ */
+Module.runMain = async function(...args) {
+  try {
+    const { enabled } = await loader.init(process.argv);
+    if (enabled) {
+      await loader.bootstrap(process.argv);
+    }
+    await loader.resetArgs(process.argv[0], process.argv[1]);
+    loader.logTime(startTime, 'agent');
+    const appStartTime = process.hrtime();
+    orig.apply(this, args);
+    loader.logTime(appStartTime, 'application');
+    loader.logTime(startTime, 'agent & application');
+  
+  } catch(err) {
+    console.error(err);
+    process.exit(-1);
+  }
+};

package/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+Copyright: 2021 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.
+*/
+
+const startTime = process.hrtime();
+
+const loader = require('./agent-loader');
+
+async function exec() {
+  const { script, enabled } = await loader.init(process.argv, true);
+
+  // only bootstrap if agent is enabled
+  if (enabled) {
+    await loader.bootstrap(process.argv);
+  }
+
+  loader.logTime(startTime, 'agent');
+
+  const appStartTime = process.hrtime();
+  await loader.run(process.argv[0], script);
+  loader.logTime(startTime);
+  loader.logTime(appStartTime, 'application');
+  loader.logTime(startTime, 'agent & application');
+}
+
+exec();

package/esm.mjs

@@ -0,0 +1,102 @@
+/**
+Copyright: 2021 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 { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import { dirname } from 'path';
+import fs from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const loader = require('./agent-loader.js');
+const { enabled } = await loader.init(process.argv);
+if (enabled) {
+  await loader.bootstrap(process.argv);
+}
+await loader.resetArgs(process.argv[0], process.argv[1]);
+
+const LIB_PATH = fs.existsSync(`${__dirname}/lib`) ? 'lib' : 'lib.asar';
+const agent = require(`./${LIB_PATH}/agent.js`);
+const logger = require(`./${LIB_PATH}/core/logger/index.js`)('contrast:esm-loaders');
+const rewriter = require(`./${LIB_PATH}/core/rewrite-babel/index.js`)(agent);
+const helpers = require(`./${LIB_PATH}/hooks/module/helpers.js`);
+
+const loadedFromCache = new Set();
+
+/**
+ * The `getSource` hook is used to provide a custom method for retrieving source
+ * code. In our case, we check for previously rewritten ESM files in our cache
+ * location and return the string content of said files if they exist. If no
+ * cached file is located, we fall back to the default Node method for reading
+ * source code.
+ *
+ * @see https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_code_getsource_code_hook
+ * @param {string} url
+ * @param {{ format: string }} context
+ * @param {Function} defaultGetSource
+ * @returns {Promise<{ source: string | SharedArrayBuffer | Uint8Array }>}
+ */
+export async function getSource(url, context, defaultGetSource) {
+  const filename = fileURLToPath(url);
+  logger.debug('getSource %s', filename);
+  try {
+    const cached = helpers.find(agent, filename);
+    if (!cached) return defaultGetSource(url, context, defaultGetSource);
+    loadedFromCache.add(filename);
+    return { source: cached };
+  } catch (err) {
+    logger.warn(
+      'Failed to locate cached rewrite for %s, err: %o',
+      filename,
+      err
+    );
+
+    return defaultGetSource(url, context, defaultGetSource);
+  }
+}
+
+/**
+ * The `transformSource` hook implements our source-code rewriting whenever an
+ * ECMAScript Module file is loaded. Before the string content of a loaded ESM
+ * file is parsed by Node, we rewrite in a manner similar to our current
+ * `Module._compile` instrumentation. If a cached file was returned by the
+ * `getSource` hook above, we can skip rewriting by returning the cached result.
+ *
+ * @see https://nodejs.org/docs/latest-v12.x/api/esm.html#esm_code_transformsource_code_hook
+ * @param {string | SharedArrayBuffer | Uint8Array} source
+ * @param {{ format: string, url: string }} context
+ * @param {Function} defaultTransformSource
+ * @returns {Promise<{ source: string | SharedArrayBuffer | Uint8Array }>}
+ */
+export async function transformSource(source, context, defaultTransformSource) {
+  const filename = fileURLToPath(context.url);
+  logger.debug('transformSource %s', filename);
+  let result;
+  try {
+    if (loadedFromCache.has(filename)) return { source };
+
+    result = rewriter.rewriteFile(source, filename, { sourceType: 'module' });
+    helpers.cacheWithSourceMap(agent, filename, result);
+    return { source: result.code };
+  } catch (err) {
+    logger.error(
+      'Failed to compile rewritten code for %s, err: %o, rewritten code %s, compiling original code.',
+      filename,
+      err,
+      result.code
+    );
+    return defaultTransformSource(source, context, defaultTransformSource);
+  }
+}