@contrast/config 1.34.0 → 1.36.0

package/lib/common.js

@@ -74,8 +74,9 @@ const ConfigSource = {
 
 // these should return `undefined` if there is no remote value corresponding to the effective config name.
 const mappings = {
-  // application-create
-  'application.session_id': (remoteData) => remoteData.settings?.assessment?.session_id,
+  // agent startup (v1) or application startup (ng fallback)
+  'application.session_id': (remoteData) =>
+    remoteData.identification?.session_id ?? remoteData.settings?.assessment?.session_id,
   // application settings
   'protect.enable': (remoteData) => remoteData.protect?.enable,
   'protect.rules.cmd-injection.mode': protectModeReader(CMD_INJECTION),

package/lib/config.js

@@ -20,7 +20,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const yaml = require('yaml');
-const { Event, get, set, primordials: { ArrayPrototypeJoin, BufferPrototypeToString, StringPrototypeToUpperCase, JSONParse } } = require('@contrast/common');
+const { Event, get, set, primordials: { ArrayPrototypeJoin, StringPrototypeToUpperCase, JSONParse } } = require('@contrast/common');
 const options = require('./options');
 const {
   ConfigSource: {
@@ -60,7 +60,11 @@ module.exports = class Config {
       node: {},
     };
     this.application = {};
-    this.assess = {};
+    this.assess = {
+      probabilistic_sampling: {
+        route_monitor: {}
+      }
+    };
     this.inventory = {};
     this.protect = {
       rules: {},
@@ -161,11 +165,12 @@ module.exports = class Config {
 
     const { _filepath } = this;
 
-    if (_filepath) {
+    // deliberately ignore /dev/null (linux) and \\.\\nul (windows)
+    if (_filepath && _filepath !== os.devNull) {
       let fileContents;
 
       try {
-        fileContents = BufferPrototypeToString.call(fs.readFileSync(_filepath), 'utf-8');
+        fileContents = fs.readFileSync(_filepath, 'utf-8');
       } catch (e) {
         const err = new Error(`Unable to read Contrast configuration file: '${_filepath}'`);
         err.cause = e;
@@ -242,9 +247,8 @@ module.exports = class Config {
     Array.from(this._effectiveMap.values()).forEach((v) => {
       let { value } = v;
       if (redact) value = this._redact(v.name, v.value);
-      if (value === undefined) value = null;
 
-      const redacted = { ...v, value: String(value) };
+      const redacted = { ...v, value: value !== null ? String(value) : null };
       effective_config.push(redacted);
       if (v.source === ENVIRONMENT_VARIABLE) environment_variable.push(redacted);
       if (v.source === CONTRAST_UI) contrast_ui.push(redacted);

package/lib/index.d.ts

@@ -241,6 +241,16 @@ export interface Config {
 
     /** Defualt: `false` */
     trust_custom_validators: boolean;
+
+    // effective based on local config and 'assess.sampling' TS DTM
+    probabilistic_sampling: {
+      /** Defualt: `false` */
+      enable: boolean,
+      route_monitor: {
+        /** Defualt: `3600000` */
+        ttl_ms: number,
+      }
+    }
   };
 
   protect: {
@@ -256,41 +266,30 @@ export interface Config {
       /**
        * List of rule ids to disable.
        * Default: `[]`
-      */
+       */
       disabled_rules: string[];
     } & Record<Omit<Rule, Rule.BOT_BLOCKER | Rule.IP_DENYLIST | Rule.VIRTUAL_PATCH>, { mode: ProtectRuleMode }>;
   };
 
   application: {
-    /** override the reported application name. */
+    /** Override the reported application name. */
     name?: string;
-    /** override the reported application path. Default: `'/'` */
+    /** Override the reported application path. Default: `'/'` */
     path: string;
-    /** override the reported application version */
+    /** Add the name of the application group with which this application should be associated in the Contrast UI. */
+    group?: string;
+    /** Add the application code this application should use in the Contrast UI. */
+    code?: string;
+    /** Override the reported application version. */
     version?: string;
-
-    /**
-     * Provide the ID of a session existing within Contrast UI.
-     * Default: `null`
-     */
-    session_id: string | null;
-
-    /**
-     * How to report the application's group for auto-grouping
-     */
-    group: string | null;
-
-    /**
-     * Comma-separated list of key=value pairs that are applied to each application reported by the agent.
-     */
-    metadata: string | null;
-
-    /**
-     * Provide metadata used to create a new session within Contrast UI.
-     * Default: `null`
-     */
-    session_metadata: string | null;
-
+    /** Apply labels to an application. Labels must be formatted as a comma-delimited list. Example - `label1,label2,label3` */
+    tags?: string;
+    /** Comma-separated list of key=value pairs that are applied to each application reported by the agent. */
+    metadata?: string;
+    /** Provide the ID of a session existing within Contrast UI. Exclusive with `session_metadata` */
+    session_id?: string;
+    /** Provide metadata used to create a new session within Contrast UI. Exclusive with `session_id` */
+    session_metadata?: string;
   };
 
   /** Reported server information overrides */

package/lib/options.js

@@ -541,6 +541,7 @@ Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\`
     desc: 'Set to true to enable sampling of requests for dataflow and other Assess features',
   },
   {
+    // effective based on local config and 'assess.sampling' TeamServer DTM
     name: 'assess.probabilistic_sampling.base_probability',
     arg: '<probability>',
     fn: (val) => {
@@ -553,8 +554,22 @@ Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\`
         });
       }
     },
-    default: 0.01,
-    desc: 'A value p within the interval [0, 1]. Each request will share same probability p of being sampled.',
+    default: 0.10,
+    desc: 'A value p within the range [0, 1]. Each request will share same probability p of being sampled.',
+  },
+  {
+    name: 'assess.probabilistic_sampling.route_monitor.enable',
+    arg: '[true]',
+    default: true,
+    fn: castBoolean,
+    desc: 'The agent will keep track of which routes have been analyzed and skip analysis if the route was recently sampled.',
+  },
+  {
+    name: 'assess.probabilistic_sampling.route_monitor.ttl_ms',
+    arg: '<number>',
+    default: 1_800_000,
+    fn: parseNum,
+    desc: 'Limits individual route analysis to once per this value. Defaults to 1_800_000ms (30 minutes).',
   },
   {
     name: 'assess.tags',
@@ -634,7 +649,7 @@ Example - \`label1, label2, label3\``,
   {
     name: 'application.name',
     arg: '<name>',
-    desc: "Override the reported application name. Defaults to the `name` field from an application's `package.json`",
+    desc: 'Override the reported application name.',
   },
   {
     name: 'application.path',
@@ -642,33 +657,41 @@ Example - \`label1, label2, label3\``,
     default: '/',
     desc: 'Override the reported application path.',
   },
+  {
+    name: 'application.group',
+    arg: '<group>',
+    desc: 'Add the name of the application group with which this application should be associated in the Contrast UI.',
+  },
+  {
+    name: 'application.code',
+    arg: '<code>',
+    desc: 'Add the application code this application should use in the Contrast UI.'
+  },
   {
     name: 'application.version',
     arg: '<version>',
-    desc: "Override the reported application version. Defaults to the `version` field from an application's `package.json`",
+    desc: 'Override the reported application version.',
+  },
+  {
+    name: 'application.tags',
+    arg: '<tags>',
+    desc: 'Apply labels to an application. Labels must be formatted as a comma-delimited list. Example - `label1,label2,label3`'
+  },
+  {
+    name: 'application.metadata',
+    arg: '<metadata>',
+    desc: 'Define a set of `key=value` pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application. The set must be formatted as a comma-delimited list of `key=value` pairs. Example - `business-unit=accounting, office=Baltimore`',
   },
   {
     name: 'application.session_id',
     arg: '<session_id>',
-    default: null,
     desc: 'Provide the ID of a session which already exists in the Contrast UI. Vulnerabilities discovered by the agent are associated with this session. If an invalid ID is supplied, the agent will be disabled. This option and `application.session_metadata` are mutually exclusive; if both are set, the agent will be disabled.',
   },
   {
     name: 'application.session_metadata',
     arg: '<session_metadata>',
-    default: null,
     desc: 'Provide metadata which is used to create a new session ID in the Contrast UI. Vulnerabilities discovered by the agent are associated with this new session. This value should be formatted as `key=value` pairs (conforming to RFC 2253). Available key names for this configuration are branchName, buildNumber, commitHash, committer, gitTag, repository, testRun, and version. This option and `application.session_id` are mutually exclusive; if both are set the agent will be disabled.',
   },
-  {
-    name: 'application.group',
-    arg: '<tags>',
-    desc: "how to report the application's group for auto-grouping",
-  },
-  {
-    name: 'application.metadata',
-    arg: '<metadata>',
-    desc: 'comma-separated list of key=value pairs that are applied to each application reported by the agent.',
-  },
   // server
   {
     name: 'server.name',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/config",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "An API for discovering Contrast agent configuration data",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",