@contrast/core 1.51.0 → 1.53.0

package/lib/system-info/index.js

@@ -17,28 +17,36 @@
 
 const fs = require('fs/promises');
 const os = require('os');
+const v8 = require('v8');
+const {
+  primordials: { StringPrototypeMatch, StringPrototypeTrim },
+} = require('@contrast/common');
 const { getCloudProviderMetadata } = require('./cloud-provider-metadata');
-const { primordials: { StringPrototypeConcat, StringPrototypeMatch } } = require('@contrast/common');
 const getLinuxOsInfo = require('./linux-os-info');
+const { humanReadableBytes } = require('./utils');
 
 const MOUNTINFO_REGEX = /\/docker\/containers\/(.*?)\//;
 const CGROUP_REGEX = /:\/docker\/([^/]+)$/;
-
-function isUsingPM2(pkg) {
-  const result = { used: !!process.env.pmx, version: null };
-
-  if (pkg?.dependences?.['pm2']) {
-    result.version = pkg.dependencies['pm2'];
-  }
-
-  return result;
-}
-
+const MAX_CGROUP_MEMORY_LIMIT = 2 ** 63 - 1; // Common "unlimited" value for cgroup limits
+
+/**
+ * Asynchronously determines if the current environment is running inside a
+ * Docker container.
+ *
+ * The function checks for Docker-specific indicators in the following order:
+ * 1. Parses `/proc/self/mountinfo` for Docker mount information.
+ * 2. Parses `/proc/self/cgroup` for Docker cgroup information.
+ * 3. Checks for the existence of the `/.dockerenv` file.
+ *
+ * @returns {Promise<{ isDocker: boolean, containerId: string|null }>}
+ *  An object indicating whether the environment is Docker and the container ID
+ *  if available.
+ */
 async function getDockerInfo() {
   try {
     const result = await fs.readFile('/proc/self/mountinfo', 'utf8');
     const matches = StringPrototypeMatch.call(result, MOUNTINFO_REGEX);
-    if (matches) return { isDocker: true, containerID: matches[1] };
+    if (matches) return { isDocker: true, containerId: matches[1] };
   } catch (err) {
     // else check /proc/self/cgroup
   }
@@ -46,32 +54,94 @@ async function getDockerInfo() {
   try {
     const result = await fs.readFile('/proc/self/cgroup', 'utf8');
     const matches = StringPrototypeMatch.call(result, CGROUP_REGEX);
-    if (matches) return { isDocker: true, containerID: matches[1] };
+    if (matches) return { isDocker: true, containerId: matches[1] };
   } catch (err) {
     // else check /.dockerenv
   }
 
   try {
     const result = await fs.stat('/.dockerenv');
-    if (result) return { isDocker: true, containerID: null };
+    if (result) return { isDocker: true, containerId: null };
   } catch (err) {
     // if there's not such file we can conclude it's not docker env
   }
 
-  return { isDocker: false, containerID: null };
+  return { isDocker: false, containerId: null };
 }
 
+/**
+ * Retrieves information about whether the current environment is running inside
+ * Kubernetes.
+ *
+ * @returns {{ isKubernetes: boolean }} An object indicating if the environment
+ *  is Kubernetes.
+ */
 function getKubernetesInfo() {
   return { isKubernetes: !!process.env.KUBERNETES_SERVICE_HOST };
 }
 
-module.exports = function(core) {
-  const {
-    agentName,
-    agentVersion,
-    config,
-    appInfo,
-  } = core;
+/**
+ * Determines if the application is using PM2 and retrieves the PM2 version from
+ * the package dependencies.
+ *
+ * @param {Object} pkg - The package.json object.
+ * @param {Object} [pkg.dependencies] - The dependencies listed in package.json.
+ * @returns {{ used: boolean, version: string|null }} An object indicating if PM2
+ *  used and its version (if available).
+ */
+function isUsingPM2(pkg) {
+  const result = { used: !!process.env.pmx, version: null };
+
+  if (pkg?.dependencies?.['pm2']) {
+    result.version = pkg.dependencies['pm2'];
+  }
+
+  return result;
+}
+
+/**
+ * Asynchronously retrieves the Docker container's memory limit in bytes, if
+ * running inside a cgroup-limited environment.
+ *
+ * Reads the memory limit from the cgroup file system. If the limit is less than
+ * the maximum allowed by cgroups, it returns the value in bytes. If no
+ * limit is detected or an error occurs, returns `undefined`.
+ *
+ * @returns {Promise<number|undefined>} The memory limit in bytes or `undefined`
+ *  if the limit is not determined.
+ */
+async function getDockerMemoryLimit() {
+  let limitInBytes = NaN;
+
+  // cgroup v2
+  try {
+    const result = await fs.readFile('/sys/fs/cgroup/memory.max', 'utf8');
+    limitInBytes = parseInt(StringPrototypeTrim.call(result), 10);
+  } catch {
+    // try v1...
+  }
+
+  // cgroup v1
+  try {
+    const result = await fs.readFile('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'utf8');
+    limitInBytes = parseInt(StringPrototypeTrim.call(result), 10);
+  } catch {
+    // no cgroup detected...
+  }
+
+  if (!isNaN(limitInBytes) && limitInBytes < MAX_CGROUP_MEMORY_LIMIT) {
+    return limitInBytes;
+  }
+}
+
+/**
+ * @param {import('..').Core & {
+ *  _systemInfo: import('@contrast/common').SystemInfo | undefined;
+ *  config: import('@contrast/config').Config;
+ * }} core
+ */
+module.exports = function (core) {
+  const { agentName, agentVersion, config, appInfo } = core;
 
   // have values default to null so all required keys get serialized
   core.getSystemInfo = async function getSystemInfo() {
@@ -79,78 +149,77 @@ module.exports = function(core) {
     if (core._systemInfo) return core._systemInfo;
 
     const cpus = os.cpus();
-    const totalmem = os.totalmem();
-    const freemem = os.freemem();
-
-    let linuxOsInfo = undefined;
-    const osInfo = await getLinuxOsInfo();
-    if (osInfo && osInfo.file) {
-      linuxOsInfo = {
-        Id: osInfo.id,
-        VersionId: osInfo.version_id,
-      };
-    }
+    const heapStats = v8.getHeapStatistics();
+    const dockerMemoryLimit = await getDockerMemoryLimit();
 
+    const osMemoryInfo = {
+      total: humanReadableBytes(os.totalmem()),
+    };
+    const linuxOsInfo = await getLinuxOsInfo();
 
     /** @type {import('@contrast/common').SystemInfo} */
-    const info = {
-      ReportDate: new Date().toISOString(),
-      MachineName: os.hostname(),
-      Contrast: {
-        Url: config.api.url || null,
-        Proxy: {
+    const systemInfo = {
+      reportDate: new Date().toISOString(),
+      hostname: os.hostname(),
+      contrast: {
+        url: config.api.url ?? null,
+        proxy: {
           enable: !!config.api.proxy.enable,
-          url: config.api.proxy.url || null,
+          url: config.api.proxy.url ?? null,
         },
-        Server: {
-          Name: config.server.name,
+        server: {
+          name: config.server.name,
         },
-        Agent: {
-          Name: agentName,
-          Version: agentVersion,
+        agent: {
+          name: agentName,
+          version: agentVersion,
         },
       },
-      Node: {
-        Path: process.execPath,
-        Version: process.version,
+      node: {
+        path: process.execPath,
+        version: process.version,
+        memory: {
+          total: humanReadableBytes(heapStats.heap_size_limit),
+          used: humanReadableBytes(heapStats.used_heap_size),
+          free: humanReadableBytes(heapStats.heap_size_limit - heapStats.used_heap_size),
+        },
       },
-      OperatingSystem: {
-        Architecture: os.arch(),
-        Name: os.type(),
-        Version: os.release(),
-        KernelVersion: os.version(),
-        CPU: {
-          Type: cpus[0].model,
-          Count: cpus.length,
+      os: {
+        architecture: os.arch(),
+        name: os.type(),
+        version: os.release(),
+        kernelVersion: os.version(),
+        cpu: {
+          type: cpus[0].model,
+          count: cpus.length,
         },
-        // Id, VersionId if linux, else null
-        ...linuxOsInfo,
+        memory: osMemoryInfo,
+        id: linuxOsInfo?.file ? linuxOsInfo.id : undefined,
+        versionId: linuxOsInfo?.file ? linuxOsInfo.version_id : undefined,
       },
-      Host: {
-        Docker: await getDockerInfo(),
-        Kubernetes: getKubernetesInfo(),
-        PM2: isUsingPM2(appInfo.pkg),
-        Memory: {
-          Total: StringPrototypeConcat.call((totalmem / 1e6).toFixed(0), ' MB'),
-          Free: StringPrototypeConcat.call((freemem / 1e6).toFixed(0), ' MB'),
-          Used: StringPrototypeConcat.call(((totalmem - freemem) / 1e6).toFixed(0), ' MB'),
+      host: {
+        docker: await getDockerInfo(),
+        kubernetes: getKubernetesInfo(),
+        pm2: isUsingPM2(appInfo.pkg),
+        memory: {
+          total: dockerMemoryLimit ? humanReadableBytes(dockerMemoryLimit) : osMemoryInfo.total,
         },
       },
-      Application: appInfo.pkg,
-      Cloud: {
-        Provider: null,
-        ResourceID: null,
-      }
+      application: appInfo.pkg,
+      cloud: {
+        provider: null,
+        resourceId: null,
+      },
     };
 
     if (config.server.discover_cloud_resource) {
       const metadata = await getCloudProviderMetadata(config.inventory.gather_metadata_via);
       if (metadata) {
-        info.Cloud.Provider = metadata.provider;
-        info.Cloud.ResourceID = metadata.id;
+        systemInfo.cloud.provider = metadata.provider;
+        systemInfo.cloud.resourceId = metadata.id;
       }
     }
 
-    return core._systemInfo = info;
+    return (core._systemInfo = systemInfo);
   };
 };

package/lib/system-info/linux-os-info.js

@@ -67,7 +67,10 @@ const defaultList = [
  * Get OS release info with information from '/etc/os-release', '/usr/lib/os-release',
  * or '/etc/alpine-release'. The information in that file is distribution-dependent.
  *
- * @returns Promise<Object> - where object is null if not Linux, or an object with
+ * @returns {Promise<{
+ *  file?: string;
+ *  [key: string]: string;
+ * }>} - where object is null if not Linux, or an object with
  * the a file property and the key-value pairs from the file. Any quotes around the
  * values are removed.
  *

package/lib/system-info/utils.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright: 2025 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.
+ */
+// @ts-check
+'use strict';
+
+const { primordials: { StringPrototypeConcat } } = require('@contrast/common');
+const DEPTH_TO_PREFIX = ['', 'k', 'M', 'G', 'T']; // I don't think we're going past terabytes of memory...
+
+/**
+ * Converts a byte value into a human-readable string with appropriate units (kB, MB, GB, TB).
+ *
+ * @param {number} bytes - The number of bytes to convert.
+ * @param {number} [depth=0] - The current depth of conversion, used internally for recursion.
+ * @returns {string} The human-readable string representation of the byte value.
+ */
+module.exports.humanReadableBytes = function humanReadableBytes(bytes, depth = 0) {
+  if (bytes >= 1024 && depth < 4) {
+    return humanReadableBytes(bytes / 1024, depth + 1);
+  }
+
+  return StringPrototypeConcat.call(bytes.toFixed(depth > 0 ? 2 : 0), ' ', DEPTH_TO_PREFIX[depth], 'B');
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/core",
-  "version": "1.51.0",
+  "version": "1.53.0",
   "description": "Preconfigured Contrast agent core services and models",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -16,15 +16,15 @@
     "node": ">= 16.9.1"
   },
   "scripts": {
-    "test": "../scripts/test.sh"
+    "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.32.0",
-    "@contrast/config": "1.46.0",
+    "@contrast/common": "1.33.0",
+    "@contrast/config": "1.48.0",
     "@contrast/find-package-json": "^1.1.0",
     "@contrast/fn-inspect": "^4.3.0",
-    "@contrast/logger": "1.24.0",
-    "@contrast/patcher": "1.23.0",
+    "@contrast/logger": "1.26.0",
+    "@contrast/patcher": "1.25.0",
     "@contrast/perf": "1.3.1",
     "@tsxper/crc32": "^2.1.3",
     "axios": "^1.7.4",