@contrast/agent 4.11.0 → 4.12.0

package/bin/VERSION

@@ -1 +1 @@
-2.28.13
+2.28.14

package/lib/agent.js

@@ -31,8 +31,13 @@ class ContrastAgent {
   constructor() {
     /**
      * Instance of AppInfo containing application information.
-     * @member */
+     * @type {import('./app-info')}
+     */
     this.appInfo = null;
+
+    /** @type {import('./telemetry') */
+    this.telemetry = null;
+
     /**
      * Holds user settings for the agent
      * @member */
@@ -94,7 +99,9 @@ class ContrastAgent {
      */
     this.argv = process.argv;
     this.tsFeatureSet._subscribers.push(this.agentEmitter);
-    this.exclusions = new ExclusionFactory({ featureSet: this.tsFeatureSet });
+    this.exclusions = new ExclusionFactory({
+      featureSet: this.tsFeatureSet
+    });
     this.agentEmitter.on('application-settings', (applicationSettings) => {
       this.exclusions.updateSettings({
         settings: applicationSettings,

package/lib/app-info.js

@@ -14,87 +14,123 @@ Copyright: 2022 Contrast Security, Inc
 */
 'use strict';
 const os = require('os');
+const fs = require('fs');
 const path = require('path');
-
+const parentPackageJson = require('parent-package-json');
+const semver = require('semver');
+const { AGENT_INFO } = require('./constants');
 const logger = require('./core/logger')('contrast:appInfo');
-const fileFinder = require('./util/file-finder');
-const {
-  AGENT_INFO: { VERSION }
-} = require('./constants');
+
+const isContainer = () => {
+  try {
+    fs.statSync('/.dockerenv');
+    return true;
+  } catch (err) {
+    // if no docker env, check /proc/self/cgroup
+  }
+
+  try {
+    return fs.readFileSync('/proc/self/cgroup', 'utf8').includes('docker');
+  } catch (err) {
+    // if file not present,
+    return false;
+  }
+};
 
 /**
  * An AppInfo instance carries properties of the application being instrumented,
  * such as OS-related information, hostname, name and version information. The
  * name, version, and package.json data
  *
- * @class
- * @param {String} script File name/location for the app.
- * @param {} options Current configuration for the agent
- *
  * TODO(ehden): I'd like to get rid of this and put it more inline with what's happening in config/util.js,
  * but that's a bigger refactor and out of the scope of common config work.
  */
 class AppInfo {
+  /**
+   * @param {string} script File name/location for the app.
+   * @param {any} config Current configuration for the agent
+   */
   constructor(script, config) {
+    this.indexFile = path.resolve(script);
+    let isDir = false;
+
+    try {
+      const stats = fs.statSync(script);
+      isDir = stats.isDirectory();
+    } catch (err) {
+      // if we can't stat the start script we'll likely throw unless `app_root`
+      // is set. We'll let the logic below handle that.
+    }
+
     this.os = {
-      type: os.type(),
-      platform: os.platform(),
       architecture: os.arch(),
-      release: os.release()
+      platform: os.platform(),
+      release: os.release(),
+      type: os.type()
     };
     this.hostname = os.hostname();
-    const cmd = path.resolve(script);
-    logger.info('finding package.json for %s', cmd);
-    this.path = AppInfo.resolveAppPath(
-      config.agent.node.app_root,
-      path.dirname(cmd)
+    this.isContainer = isContainer();
+
+    logger.info('finding package.json for %s', this.indexFile);
+
+    // If started with `script` as a directory, append a file similar to below.
+    if (isDir) {
+      this.indexFile = path.join(this.indexFile, 'index.js');
+    }
+
+    const manifest = parentPackageJson(
+      // The `parent-package-json` library expects the start path to be a file,
+      // not a directory, so we append `package.json`. This lets us use the lib
+      // without changing the expected config option.
+      config.agent.node.app_root
+        ? path.join(config.agent.node.app_root, 'package.json')
+        : this.indexFile
     );
-    config.agent.node.app_root = this.path;
 
-    try {
-      this.appPackage = require(this.path);
-    } catch (e) {
+    if (!manifest) {
       throw new Error("Unable to find application's package.json.");
     }
-    this.name = config.application.name || this.appPackage.name;
 
-    const packageVersion = this.appPackage.version;
-    this.version = config.application.version || packageVersion;
-    this.serverVersion = config.server.version || VERSION;
+    /**
+     * Path to the application's package.json
+     * @type {string}
+     */
+    this.path = manifest.path;
+    logger.info('using package.json at %s', this.path);
 
-    logger.info('using appname %s', this.name);
+    /**
+     * Actual application location (directory containing package.json)
+     * @type {string}
+     */
+    this.appDir = path.dirname(this.path);
 
-    this.node_version = process.version;
-    this.app_dir = path.dirname(this.path);
-    this.appPath = config.application.path || this.app_dir;
-    this.indexFile = script; // cli.js, app.js, index.js, server.js... etc
-    this.serverName = config.server.name;
-    this.serverEnvironment = config.server.environment;
-  }
-
-  /**
-   * Returns the location of the app package
-   *
-   * @param {string} appRoot config.agent.node.app_root
-   * @param {string} scriptPath directory the script is in
-   * @returns {string} location of the app package
-   */
-  static resolveAppPath(appRoot, scriptPath) {
-    let packageLocation;
+    /**
+     * Contents of the application's package.json
+     * @type {Record<string, any>}
+     */
+    this.appPackage = manifest.parse();
 
-    if (appRoot) {
-      packageLocation = fileFinder.findFile(appRoot, 'package.json');
+    if (isDir) {
+      this.indexFile = path.resolve(this.appDir, this.appPackage.main);
     }
 
-    if (!packageLocation) {
-      packageLocation = fileFinder.findFile(scriptPath, 'package.json');
-    }
+    this.name = config.application.name || this.appPackage.name;
+    logger.info('using appname %s', this.name);
 
-    if (packageLocation) {
-      logger.info('using package.json at %s', packageLocation);
-    }
+    this.version = config.application.version || this.appPackage.version;
+    this.serverVersion = config.server.version || AGENT_INFO.VERSION;
 
-    return packageLocation;
+    this.nodeVersion = process.version;
+    this.nodeVersionMajor = semver.major(this.nodeVersion);
+
+    /**
+     * Configured application path to report
+     * @type {string}
+     */
+    this.appPath = config.application.path || this.appDir;
+
+    this.serverName = config.server.name;
+    this.serverEnvironment = config.server.environment;
   }
 }
 

package/lib/assess/loopback4/route-coverage.js

@@ -24,7 +24,7 @@ const { funcinfo } = require('@contrast/fn-inspect');
 class RouteCoverage {
   constructor(agent) {
     this.routes = new Map();
-    this.appDir = agent.appInfo.app_dir;
+    this.appDir = agent.appInfo.appDir;
     moduleHook.resolve(
       { name: '@loopback/rest', file: 'dist/router/routing-table.js' },
       this.patchRoutingTable.bind(this)

package/lib/contrast.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
 Copyright: 2022 Contrast Security, Inc
   Contact: support@contrastsecurity.com
@@ -13,13 +12,8 @@ Copyright: 2022 Contrast Security, Inc
   engineered, modified, repackaged, sold, redistributed or otherwise used in a
   way not consistent with the End User License Agreement.
 */
-/**
- * Process flows to bootstrapping user code with the node agent code
- *
- * @module lib/contrastAgent
- *
- */
 'use strict';
+
 const { program } = require('./core/config/options');
 const path = require('path');
 const os = require('os');
@@ -27,8 +21,6 @@ const semver = require('semver');
 const colors = require('./util/colors');
 const { AGENT_INFO } = require('./constants');
 const { VERSION, SUPPORTED_VERSIONS, NAME } = AGENT_INFO;
-const contrastAgent = module.exports;
-const Promise = require('bluebird');
 const Module = require('module');
 const sourceMapUtility = require('./util/source-map');
 const loggerFactory = require('./core/logger');
@@ -43,10 +35,18 @@ function getAgentSnippet() {
 }
 
 let AppInfo,
+  /** @type {import('./agent')} */
   agent = {},
   TSReporter,
-  tracker,
-  instrument;
+  instrument,
+  /** @type {import('./telemetry')} */
+  Telemetry,
+  tracker;
+
+/**
+ * Process flows to bootstrapping user code with the node agent code
+ */
+const contrastAgent = module.exports;
 
 /**
  * Who doesn't like ASCII art. Displays Matt's cat when CONTRAST_CAT env var is set to MATT
@@ -56,7 +56,6 @@ contrastAgent.showBanner = function showBanner() {
     const fs = require('fs');
     const file = path.resolve(__dirname, 'cat.txt');
     const cat = fs.readFileSync(file, 'utf8');
-    // eslint-disable-next-line no-console
     console.log(colors.red(cat));
   }
 
@@ -71,9 +70,10 @@ contrastAgent.showBanner = function showBanner() {
 contrastAgent.doImports = function doImports() {
   AppInfo = require('./app-info');
   agent = require('./agent');
-  tracker = require('./tracker');
   TSReporter = require('./reporter/ts-reporter');
   instrument = require('./instrumentation');
+  Telemetry = require('./telemetry');
+  tracker = require('./tracker');
 };
 
 /**
@@ -229,7 +229,7 @@ contrastAgent.prepare = function(...args) {
 
     if (isCli) {
       logger.error(
-        `DEPRECATED: Agent is started as runner. Please use '%s'`,
+        "DEPRECATED: Agent is started as runner. Please use '%s'",
         getAgentSnippet()
       );
     } else {
@@ -256,7 +256,7 @@ contrastAgent.prepare = function(...args) {
     }
 
     if (config.agent.node.dev.global_tracker) {
-      logger.debug('>> config.agent.node.dev.global_tracker enabled <<'); // eslint-disable-line
+      logger.debug('>> config.agent.node.dev.global_tracker enabled <<');
       global.contrast_tracker = tracker;
     }
 
@@ -271,6 +271,7 @@ contrastAgent.prepare = function(...args) {
 
     config.version = semver.valid(semver.coerce(VERSION));
     agent.appInfo = app;
+    agent.telemetry = new Telemetry(agent, config);
 
     config.override('application.name', app.name);
 
@@ -358,12 +359,11 @@ contrastAgent.init = async function(args, isCli = false) {
       }
     })
     .on('--help', function() {
-      // eslint-disable-next-line no-console
-      console.log(`
-Example:
-${colors.cyan(
-  `    $ ${getAgentSnippet()} -c ../contrast_security.yaml -- --appArg1 --appArg2 -e -t -c`
-)}`);
+      console.log('Example:');
+      console.log(
+        colors.cyan('\t$ %s -c ../contrast_security.yaml -- --appArg1 --appArg2 -e -t -c'),
+        getAgentSnippet(),
+      );
     });
 
   await program.parseAsync(args);
@@ -407,7 +407,9 @@ contrastAgent.resetArgs = function(nodePath, script) {
   process.argv = agent.config
     ? [nodePath, script].concat(agent.config.application.args)
     : process.argv;
-  const isPrimary = !agent.hasOwnProperty('cluster') || agent.cluster.isPrimary;
+  const isPrimary =
+    !Object.prototype.hasOwnProperty.call(agent, 'cluster') ||
+    agent.cluster.isPrimary;
   const location = isPrimary ? 'Entering main' : 'Entering fork';
 
   logger.debug('%s at %s', location, script);

package/lib/hooks/frameworks/base.js

@@ -66,7 +66,7 @@ class BaseFramework {
 
     if (frame) {
       const { file, lineNumber } = frame;
-      const relativeFile = (file || '').replace(this.agent.appInfo.app_dir, '');
+      const relativeFile = (file || '').replace(this.agent.appInfo.appDir, '');
       return `${relativeFile}:${lineNumber || ''}`;
     } else {
       return null;

package/lib/hooks/module/helpers.js

@@ -36,7 +36,7 @@ let appDirRegex;
  * @returns {string}
  */
 const getCachedFilename = (agent, filename) => {
-  appDirRegex = appDirRegex || new RegExp(`^(${agent.appInfo.app_dir})?`);
+  appDirRegex = appDirRegex || new RegExp(`^(${agent.appInfo.appDir})?`);
   if (os.platform() === 'win32') {
     filename = filename.replace(/C:/i, '');
   }

package/lib/instrumentation.js

@@ -89,7 +89,7 @@ function collectLibInfo(agent) {
       require('./hooks/module/extensions')();
       libUsage.listen(evalFrequency);
     }
-    libraries.getPackageLibraries(agent, eluEnabled).then((libs) => {
+    libraries.getLibInfo(agent, eluEnabled).then((libs) => {
       agentEmitter.emit('appinfo', { libs });
     });
   }

package/lib/libraries.js

@@ -13,176 +13,160 @@ Copyright: 2022 Contrast Security, Inc
   way not consistent with the End User License Agreement.
 */
 'use strict';
-const Promise = require('bluebird');
-const stringify = require('json-stable-stringify');
-const _ = require('lodash');
-const path = require('path');
-const util = require('util');
 
-const {
-  AGENT_INFO: { NAME }
-} = require('./constants');
-const logger = require('./core/logger')('contrast:libraries');
+const { stat } = require('fs').promises;
+const stringify = require('json-stable-stringify');
+const Module = require('module');
+const { AGENT_INFO } = require('./constants');
 const { runInNoInstrumentationScope } = require('./core/async-storage/scopes');
+const logger = require('./core/logger')('contrast:libraries');
 const listInstalled = require('./list-installed');
 const AppUpdate = require('./reporter/models/app-update');
 
 const DEADZONE_NAME = 'agent: libraries';
 
-// Note: do not use bluebird.promisify here as it will break tests by leaking
-// NO_INSTRUMENTATION Scope across tests. see:
-// https://contrast.atlassian.net/wiki/spaces/~18775625/pages/1222052407/Async+Context+when+a+Promise+is+returned+from+runInScope
-const stat = util.promisify(require('fs').stat);
+/**
+ * @typedef {import('./list-installed').Result} Result
+ */
 
 /**
- * Scan dependencies recursively to determine dependents.
- * @param {Object} deps the formatted object from formatDependencies
+ * Searches a list of paths and returns the first valid path found.
+ * @param {string[]} paths
+ * @returns {Promise<string | undefined>}
+ */
+const findNodeModsPath = async (paths) =>
+  // this functions similarly to `Bluebird.map() with concurrency: 1
+  paths.reduce(async (prev, path) => {
+    if (await prev) return prev;
+
+    try {
+      await stat(path);
+      return path;
+    } catch (err) {
+      return undefined;
+    }
+  }, Promise.resolve());
+
+/**
+ * Filters out the agent as a dependency, formats libraries, and keeps track of
+ * nested modules.
+ *
+ * @param {{ [key: string]: Result | string }} deps collection of dependencies from app root
  * @param {Map<string, Set<string>} requiredBy
- * @returns {Map<string, Set<string>}
+ * @param {string} parent the name of the module requiring the current when nested
+ * @return {{ [key: string]: Result }} formatted object
  */
-function setRequiredBy(deps, requiredBy = new Map()) {
-  _.forEach(deps, (dep, depName) => {
-    _.forEach(dep.dependencies, (depOfDep, depOfDepName) => {
-      const set = requiredBy.has(depOfDepName)
-        ? requiredBy.get(depOfDepName)
-        : new Set();
-
-      set.add(depName);
-      requiredBy.set(depOfDepName, set);
-    });
-
-    setRequiredBy(dep.dependencies, requiredBy);
-  });
+const formatDependencies = (deps, requiredBy, parent) =>
+  Object.entries(deps || {}).reduce((result, [key, val]) => {
+    if (key === AGENT_INFO.NAME) {
+      return result;
+    }
+
+    if (parent) {
+      const set = requiredBy.has(key) ? requiredBy.get(key) : new Set();
+
+      set.add(parent);
+      requiredBy.set(key, set);
+    }
+
+    if (typeof val === 'string') {
+      result[key] = {
+        name: key,
+        version: val,
+        dependencies: {}
+      };
+      return result;
+    }
+
+    if (!val.name) val.name = key;
+
+    val.dependencies = formatDependencies(val.dependencies, requiredBy, key);
+    result[key] = val;
 
-  return requiredBy;
-}
+    return result;
+  }, {});
 
 /**
  * Recursively adds each dependency as a library which is used later
  * for reporting inventory and class usage
  *
- * @param {Object} deps  collection of dependencies
+ * @param {{ [key: string]: Result }} deps the formatted object from formatDependencies
  * @param {Map<string, Set<string>} requiredBy map containing data regarding dependents
- * @param {Object} agent agent instance
+ * @param {import('./agent')} agent agent instance
  */
-function processDependencies(deps, requiredBy, agent) {
-  for (const key in deps) {
-    const dep = deps[key];
-    if (!dep.name) {
-      dep.name = key;
-    }
-
+const processDependencies = (deps, requiredBy, agent) => {
+  Object.values(deps).forEach((dep) => {
     dep._requiredBy = requiredBy.has(dep.name)
       ? Array.from(requiredBy.get(dep.name))
       : [];
 
     const newLib = AppUpdate.addLib(dep, agent);
-    // check its deps as well
+    // If this is the first time we've checked this dep, check its deps as well.
     if (newLib) {
       processDependencies(dep.dependencies, requiredBy, agent);
     }
-  }
-}
-
-/**
- * compares module name with agent name
- *
- * @param {string} modeName
- * @return {Boolean} if modName matches agent, returns true
- */
-function isAgent(modName) {
-  return modName === NAME;
-}
+  });
+};
 
 /**
- * Filters out the agent as a dependency
- * Formats libraries as { 'mod-name': { <mod package.json deets } }
+ * Traverses entire dependency tree to report library inventory
  *
- * @param {Object} deps collection of dependencies from app root
- * @return {Object} formatted object
+ * @param {import('./agent')} agent agent instance
+ * @param {boolean} eluEnabled flag to get composition for each module
+ * @returns {AppUpdate.libraries}
  */
-function formatDependencies(deps) {
-  return _.reduce(
-    deps,
-    (result, value, key) => {
-      if (isAgent(key)) {
-        return result;
+const getLibInfo = async (agent, eluEnabled) =>
+  runInNoInstrumentationScope(async () => {
+    try {
+      const boundRequire = Module.createRequire(agent.appInfo.path);
+      const paths = boundRequire.resolve.paths(agent.appInfo.path);
+      const nodeModsPath = await findNodeModsPath(paths);
+
+      if (!nodeModsPath) {
+        logger.error(
+          `unable to read installed dependencies because a node_modules directory could not be detected given a package.json located at %s - use the agent.node.app_root configuration variable if installed in non-standard location`,
+          agent.appInfo.path
+        );
+        return AppUpdate.libraries;
       }
 
-      if (typeof value === 'object') {
-        result[key] = value;
-      } else {
-        result[key] = {
-          name: key,
-          version: value
-        };
+      logger.debug('detected node_modules at %s', nodeModsPath);
+      const data = await listInstalled(nodeModsPath, logger);
+
+      logger.debug(
+        'package.json dependencies: %s',
+        // _dependencies contains { name: version } info
+        stringify(data._dependencies, { space: 2 })
+      );
+      logger.debug(
+        'package.json devDependencies: %s',
+        stringify(data.devDependencies, { space: 2 })
+      );
+
+      const requiredBy = new Map();
+      const dependencies = formatDependencies(data.dependencies, requiredBy);
+      processDependencies(dependencies, requiredBy, agent);
+
+      const libs = AppUpdate.libraries;
+      if (eluEnabled) {
+        logger.info('recursively scanning dependencies');
+        // this functions similarly to `Bluebird.map()` with concurrency: 1
+        await Object.values(libs).reduce(async (prev, lib) => {
+          await prev;
+          return lib.getComposition();
+        }, Promise.resolve());
       }
 
-      return result;
-    },
-    {}
-  );
-}
+      logger.info(
+        'finished library inventory for %s dependencies',
+        Object.keys(libs).length
+      );
 
-/**
- * Traverses entire dependency tree to report library inventory
- *
- * @param {Object} agent agent instance
- * @param {Boolean} eluEnabled flag to get composition for each module
- */
-function getPackageLibraries(agent, eluEnabled) {
-  const appRoot = _.get(agent, 'appInfo.path');
-  return runInNoInstrumentationScope(() => {
-    const dir = path.dirname(appRoot);
-
-    let nodeModsExists = false;
-    return stat(`${dir + path.sep}node_modules`)
-      .then(() => {
-        nodeModsExists = true;
-        return listInstalled(dir, logger);
-      })
-      .then((data) => {
-        logger.debug(
-          'package.json dependencies: %s',
-          stringify(data._dependencies, { space: 2 })
-        );
-        logger.debug(
-          'package.json devDependencies: %s',
-          stringify(data.devDependencies, { space: 2 })
-        );
-        const dependencies = formatDependencies(data.dependencies);
-        const requiredBy = setRequiredBy(dependencies);
-        return processDependencies(dependencies, requiredBy, agent);
-      })
-      .then(() => {
-        if (eluEnabled) {
-          logger.info('recursively scanning dependencies');
-          const libs = _.values(AppUpdate.libraries);
-          return Promise.map(libs, (lib) => lib.getComposition(), {
-            concurrency: 1
-          });
-        }
-      })
-      .then(() => {
-        const libs = AppUpdate.libraries;
-        logger.info(
-          'finished library inventory for %s dependencies',
-          Object.keys(libs).length
-        );
-
-        return libs;
-      })
-      .catch((err) => {
-        if (!nodeModsExists) {
-          logger.error(
-            `unable to read install dependencies because node_modules are not installed in app root (${dir}) - use agent.node.app_root configuration if installed in non-standard location`
-          );
-        } else {
-          logger.error('unable to read installed dependencies. %o', err);
-        }
-        return AppUpdate.libraries;
-      });
+      return libs;
+    } catch (err) {
+      logger.error('unable to read installed dependencies. %o', err);
+      return AppUpdate.libraries;
+    }
   }, DEADZONE_NAME);
-}
 
-module.exports.getPackageLibraries = getPackageLibraries;
+module.exports.getLibInfo = getLibInfo;

package/lib/list-installed.js

@@ -21,6 +21,19 @@ const {
 
 const execFile = util.promisify(require('child_process').execFile);
 
+/**
+ * @typedef {Object} Result
+ * @property {string} name
+ * @property {string} version
+ * @property {{ [key: string]: Result | string }} dependencies
+ * @property {{ [key: string]: Result | string }} devDependencies
+ */
+
+/**
+ * @param {string} cwd directory in which we want to execute `npm ls`
+ * @param {*} logger
+ * @returns {Promise<Result>}
+ */
 module.exports = async function listInstalled(cwd, logger) {
   const env = { ...process.env, NODE_OPTIONS: undefined };
   const args = ['--silent', 'ls', '--json', '--prod', '--long'];

package/lib/reporter/models/app-update/index.js

@@ -160,7 +160,7 @@ module.exports = class AppUpdate {
 
   /**
    * returns collection of libraries
-   * @return {Object}
+   * @return {{ [key: string]: Library }}
    */
   static get libraries() {
     const data = {};

package/lib/reporter/translations/to-protobuf/dtm/agent-startup.js

@@ -22,18 +22,18 @@ const {
 
 module.exports = function AgentStartup({
   config = { server: {} },
-  appInfo: { app_dir, serverEnvironment, serverVersion, version } = {}
+  appInfo: { appDir, serverEnvironment, serverVersion, version } = {}
 } = {}) {
   const serverName = config.server.name;
   const { tags, type } = config.server;
-  app_dir = config.server.path || app_dir;
+  appDir = config.server.path || appDir;
 
   return new dtm.AgentStartup({
     1: VERSION, //           2 version
     2: serverEnvironment, // 3 environment
     3: tags, //              4 tags
     4: serverName, //        5 server_name
-    5: app_dir, //           6 server_path
+    5: appDir, //            6 server_path
     6: type, //              7 server_type
     7: serverVersion //      8 server_version
   });

package/lib/telemetry.js

@@ -0,0 +1,188 @@
+/**
+Copyright: 2022 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.
+*/
+'use strict';
+
+const { default: axios } = require('axios');
+const { createHash } = require('crypto');
+const findCacheDir = require('find-cache-dir');
+const { promises: fs } = require('fs');
+const { default: getMac } = require('getmac');
+const os = require('os');
+const path = require('path');
+const process = require('process');
+const { v4: uuid } = require('uuid');
+const { AGENT_INFO } = require('./constants');
+const logger = require('./core/logger')('contrast:telemetry');
+
+const TELEMETRY_URL = 'https://telemetry.nodejs.contrastsecurity.com/';
+const TELEMETRY_VERSION = 'v0'; // TODO: set this to v1 when format is established.
+
+const {
+  CONTRAST_AGENT_TELEMETRY_OPTOUT,
+  CONTRAST_DEV,
+  CONTRAST_SCREENER
+} = process.env;
+
+// TODO: LINK
+const DISCLAIMER = `The Contrast Node Agent collects usage data in order to help us improve compatibility and security coverage.
+The data is anonymous and does not contain application data. It is collected by Contrast and is never shared.
+You can opt-out of telemetry by setting the CONTRAST_AGENT_TELEMETRY_OPTOUT environment variable to '1' or 'true'.
+`;
+// Read more about the Node Agent's telemetry: TODO
+// `;
+
+const LOG_MESSAGE = `Telemetry is now active.
+You can opt-out of telemetry by setting the CONTRAST_AGENT_TELEMETRY_OPTOUT environment variable to '1' or 'true'.
+`;
+
+module.exports = class Telemetry {
+  /**
+   * @param {import('./agent')} agent
+   * @param {any} config
+   */
+  constructor(agent, config) {
+    const { appInfo } = agent;
+    this.appInfo = appInfo;
+    this.config = config;
+    this.disabled =
+      CONTRAST_AGENT_TELEMETRY_OPTOUT === 'true' ||
+      CONTRAST_AGENT_TELEMETRY_OPTOUT === '1';
+
+    if (this.disabled) {
+      logger.info(
+        'Telemetry opt-out in effect. All usage data collection is suppressed.'
+      );
+      return;
+    }
+    this.printDisclaimer();
+
+    try {
+      // Returns the "first" valid MAC address for the machine, throwing if none
+      // is found.
+      const mac = getMac();
+
+      const hash = createHash('sha256').update(mac);
+      this.instanceId = hash.copy().digest('hex');
+      this.applicationId = hash.update(appInfo.name).digest('hex');
+    } catch (err) {
+      // If getMac fails we fall back to generating a UUID. "Unstable"
+      // identifiers such as these are prefixed with an underscore.
+      const id = uuid();
+
+      this.instanceId = `_${id}`;
+      this.applicationId = this.instanceId;
+    }
+
+    this.metrics = this.createMetricsClient();
+    this.tags = {
+      isCustomerEnv: this.isCustomerEnv(),
+      applicationId: this.applicationId,
+      osArch: appInfo.os.architecture,
+      osPlatform: appInfo.os.platform,
+      osRelease: appInfo.os.release,
+      isContainer: appInfo.isContainer,
+      agent: AGENT_INFO.NAME,
+      agentVersion: AGENT_INFO.VERSION,
+      isAssess: agent.isInAssessMode(),
+      isProtect: agent.isInDefendMode(),
+      nodeVersion: appInfo.nodeVersion,
+      nodeVersionMajor: appInfo.nodeVersionMajor,
+      telemetryVersion: TELEMETRY_VERSION
+    };
+
+    this.sendStartupData();
+  }
+
+  async printDisclaimer() {
+    const filePath = path.resolve(
+      findCacheDir({ name: AGENT_INFO.NAME }) || os.tmpdir(),
+      '.telemetry-disclaimer'
+    );
+
+    try {
+      await fs.stat(filePath);
+      // If we've previously shown our disclaimer we log the shorter message.
+      logger.info(LOG_MESSAGE);
+    } catch (err) {
+      // When there's no file `stat` throws an error. That means we haven't
+      // yet shown our disclaimer.
+      console.log(DISCLAIMER);
+      logger.info(DISCLAIMER);
+      try {
+        await fs.writeFile(filePath, DISCLAIMER);
+      } catch (err) {
+        // if we can't write, oh well.
+      }
+    }
+  }
+
+  /**
+   * @returns {import('axios').AxiosInstance}
+   */
+  createMetricsClient() {
+    const userAgent = `${AGENT_INFO.NAME}/${AGENT_INFO.VERSION}`;
+
+    return axios.create({
+      baseURL: new URL('/api/v1/telemetry/metrics/node', TELEMETRY_URL).href,
+      headers: {
+        'User-Agent': userAgent
+      }
+    });
+  }
+
+  /**
+   * Logic to determine whether we are reporting a customer's application.
+   * Naive for the time being.
+   * @returns {boolean}
+   */
+  isCustomerEnv() {
+    if (CONTRAST_SCREENER || CONTRAST_DEV) return false;
+    return true;
+  }
+
+  /**
+   * @param {string} path
+   * @param {{ [field: string]: number ]}} fields
+   */
+  async sendMetrics(path, fields) {
+    return this.metrics.post(path, [
+      {
+        timestamp: new Date().toISOString(),
+        instance: this.instanceId,
+        tags: this.tags,
+        fields
+      }
+    ]);
+  }
+
+  async sendStartupData() {
+    try {
+      // snapshotted when we send our startup data.
+      const memoryUsage = process.memoryUsage();
+
+      await this.sendMetrics('startup', {
+        numCpus: os.cpus().length,
+        memTotal: os.totalmem(),
+        memHeapTotal: memoryUsage.heapTotal,
+        memHeapUsed: memoryUsage.heapUsed,
+        memExternal: memoryUsage.external,
+        memRss: memoryUsage.rss,
+        uptime: process.uptime()
+      });
+    } catch (err) {
+      logger.warn('telemetry update failed: %s', err.toJSON());
+    }
+  }
+};

package/lib/util/traverse.js

@@ -158,24 +158,28 @@ function traverse(obj, fn, visitor, maxDepth) {
   traverseObject(obj, visitor, maxDepth);
 }
 
-function traverseObject(obj, visitor, remainingDepth = Infinity) {
-  if (!obj) {
+function traverseObject(obj, visitor, remainingDepth = 250, visited = new Set()) {
+  if (!obj || visited.has(obj)) {
     return;
   }
+
   if (visitor.path.length() < 1) {
     visitor.visit('', obj);
+    visited.add(obj);
   }
 
   // This is done just to reset the stack, without changing the current impletion
   if (remainingDepth == 0) {
     visitor.visit(null, null, true);
+    visited.add(obj);
     return;
   }
 
   Object.entries(obj).forEach(([key, value]) => {
     visitor.visit(key, value);
+    visited.add(obj);
     if (value && typeof value === 'object') {
-      traverseObject(value, visitor, remainingDepth - 1);
+      traverseObject(value, visitor, remainingDepth - 1, visited);
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/agent",
-  "version": "4.11.0",
+  "version": "4.12.0",
   "description": "Node.js security instrumentation by Contrast Security",
   "keywords": [
     "security",
@@ -81,12 +81,12 @@
     "@contrast/fn-inspect": "^2.4.4",
     "@contrast/heapdump": "^1.1.0",
     "@contrast/protobuf-api": "^3.2.3",
-    "@contrast/require-hook": "^2.0.8",
+    "@contrast/require-hook": "^2.0.10",
     "@contrast/synchronous-source-maps": "^1.1.0",
     "amqp-connection-manager": "^3.2.2",
     "amqplib": "^0.8.0",
+    "axios": "^0.25.0",
     "big-integer": "^1.6.36",
-    "bluebird": "^3.5.3",
     "builtin-modules": "^3.2.0",
     "cls-hooked": "^4.2.2",
     "commander": "^8.3.0",
@@ -95,6 +95,7 @@
     "crc-32": "^1.0.0",
     "fast-deep-equal": "^3.1.3",
     "find-cache-dir": "^3.3.1",
+    "getmac": "^5.20.0",
     "ipaddr.js": "^1.8.1",
     "json-stable-stringify": "^1.0.1",
     "jspack": "0.0.4",
@@ -102,10 +103,12 @@
     "make-dir": "^3.1.0",
     "multi-stage-sourcemap": "^0.3.1",
     "on-finished": "^2.3.0",
+    "parent-package-json": "^2.0.1",
     "parseurl": "^1.3.3",
     "prom-client": "^12.0.0",
     "recursive-readdir": "^2.2.2",
     "semver": "^7.3.2",
+    "uuid": "^8.3.2",
     "winston": "^3.1.0",
     "winston-daily-rotate-file": "^3.5.1",
     "yaml": "^1.10.0"
@@ -113,19 +116,19 @@
   "devDependencies": {
     "@aws-sdk/client-dynamodb": "^3.39.0",
     "@bmacnaughton/string-generator": "^1.0.0",
-    "@contrast/eslint-config": "^2.2.0",
+    "@contrast/eslint-config": "^3.0.0-beta.4",
     "@contrast/fake-module": "file:test/mock/contrast-fake",
     "@contrast/screener-service": "^1.12.9",
     "@hapi/boom": "file:test/mock/boom",
     "@hapi/hapi": "file:test/mock/hapi",
     "@ls-lint/ls-lint": "^1.8.1",
-    "@typescript-eslint/eslint-plugin": "^5.10.2",
-    "@typescript-eslint/parser": "^5.10.2",
+    "@typescript-eslint/eslint-plugin": "^5.12.0",
+    "@typescript-eslint/parser": "^5.12.0",
     "ajv": "^8.5.0",
     "ast-types": "^0.12.4",
     "aws-sdk": "file:test/mock/aws-sdk",
-    "axios": "^0.21.4",
     "base58": "^2.0.1",
+    "bluebird": "^3.7.2",
     "callsite": "^1.0.0",
     "chai": "^4.2.0",
     "chai-as-promised": "^7.1.1",
@@ -137,7 +140,7 @@
     "dustjs-linkedin": "^3.0.1",
     "ejs": "^3.1.6",
     "escape-html": "^1.0.3",
-    "eslint": "^8.8.0",
+    "eslint": "^8.9.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-mocha": "^10.0.3",
     "eslint-plugin-node": "^11.1.0",
@@ -182,7 +185,6 @@
     "swig": "file:test/mock/swig",
     "triple-beam": "^1.3.0",
     "typeorm": "file:test/mock/typeorm",
-    "uuid": "^8.3.1",
     "validator": "^13.7.0",
     "xpath": "file:test/mock/xpath"
   },