@contrast/telemetry 1.1.0

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright: 2023 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/lib/index.js

@@ -0,0 +1,152 @@
+/*
+ * Copyright: 2023 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 { createHash, randomUUID } = require('crypto');
+const os = require('os');
+const process = require('process');
+const { default: axios } = require('axios');
+const { default: getMac } = require('getmac');
+const { Event } = require('@contrast/common');
+
+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'.
+`;
+const TELEMETRY_URL = 'https://telemetry.nodejs.contrastsecurity.com/';
+const TELEMETRY_VERSION = 'v0'; // TODO: set this to v1 when format is established.
+
+/**
+ * @param {{
+ *  agentName: string,
+ *  agentVersion: string,
+ *  config: import('@contrast/config').Config,
+ *  logger: import('@contrast/logger').Logger,
+ *  messages: import('@contrast/common').Messages,
+ * }} core
+ * @returns {import('@contrast/common').Installable}
+ */
+module.exports = function(core) {
+  const {
+    agentName,
+    agentVersion,
+    appInfo,
+    config,
+    logger,
+    messages,
+  } = core;
+
+  const { instanceId, applicationId } = getIds(appInfo);
+
+  const telemetry = core.telemetry = {
+    client: null,
+    instanceId,
+    tags: {
+      applicationId,
+      isCustomerEnv: true,
+      osArch: appInfo.os.architecture,
+      osPlatform: appInfo.os.platform,
+      osRelease: appInfo.os.release,
+      isContainer: !!appInfo.containerId,
+      agent: agentName,
+      agentVersion,
+      isAssess: config.getEffectiveValue('assess.enable'),
+      isProtect: config.getEffectiveValue('protect.enable'),
+      nodeVersion: appInfo.node_version,
+      nodeVersionMajor: appInfo.nodeMajorVersion,
+      telemetryVersion: TELEMETRY_VERSION
+    },
+    isEnabled() {
+      return (
+        process.env.CONTRAST_AGENT_TELEMETRY_OPTOUT !== 'true' &&
+        process.env.CONTRAST_AGENT_TELEMETRY_OPTOUT !== '1'
+      );
+    },
+    install() {
+      if (!telemetry.isEnabled()) {
+        logger.info('Telemetry opt-out in effect. All usage data collection is suppressed.');
+        return;
+      }
+
+      logger.info(DISCLAIMER);
+
+      telemetry.client = axios.create({
+        baseURL: new URL('/api/v1/telemetry/metrics/node', TELEMETRY_URL).href,
+        headers: {
+          'User-Agent': `${agentName}/${agentVersion}`,
+        }
+      });
+
+      telemetry.startup();
+    },
+
+    async startup() {
+      try {
+        const { external, heapTotal, heapUsed, rss } = process.memoryUsage();
+        await telemetry.client.post('/startup', [
+          {
+            timestamp: new Date().toISOString(),
+            instance: telemetry.instanceId,
+            tags: telemetry.tags,
+            fields: {
+              numCpus: os.cpus().length,
+              memTotal: os.totalmem(),
+              memHeapTotal: heapTotal,
+              memHeapUsed: heapUsed,
+              memExternal: external,
+              memRss: rss,
+              uptime: process.uptime()
+            }
+          }
+        ]);
+      } catch (err) {
+        logger.error({ err }, 'error occurred while reporting telemetry: /startup');
+      }
+    },
+  };
+
+  messages.on(Event.SERVER_SETTINGS_UPDATE, () => {
+    telemetry.tags.isAssess = config.getEffectiveValue('assess.enable');
+    telemetry.tags.isProtect = config.getEffectiveValue('protect.enable');
+  });
+
+  return core.telemetry;
+};
+
+module.exports.getIds = getIds;
+
+function getIds (appInfo) {
+  let applicationId, instanceId;
+
+  try {
+    const hash = createHash('sha256').update(getMac());
+    if (appInfo.containerId) hash.update(appInfo.containerId);
+    instanceId = hash.copy().digest('hex');
+    applicationId = hash.update(appInfo.name).digest('hex');
+  } catch {
+    // If getMac fails we fall back to generating a UUID. "Unstable"
+    // identifiers such as these are prefixed with an underscore.
+    let id = randomUUID();
+    if (appInfo.containerId) {
+      id += `_${appInfo.containerId}`;
+    }
+    applicationId = instanceId = `_${id}`;
+  }
+
+  return { applicationId, instanceId };
+}
+
+module.exports.DISCLAIMER = DISCLAIMER;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@contrast/telemetry",
+  "version": "1.1.0",
+  "description": "Telemetry reporting for the Contrast Node.js agent.",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
+  "main": "lib/index.js",
+  "engines": {
+    "npm": ">=6.13.7 <7 || >=8.3.1",
+    "node": ">=14.15.0"
+  },
+  "scripts": {
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {
+    "@contrast/common": "1.16.0",
+    "@contrast/config": "1.22.0",
+    "@contrast/core": "1.27.0",
+    "@contrast/logger": "1.7.0",
+    "axios": "^1.6.0",
+    "getmac": "^6.3.0"
+  }
+}