@contrast/config 1.34.0 → 1.35.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: {
@@ -161,11 +161,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 +243,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

@@ -262,35 +262,24 @@ export interface Config {
   };
 
   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

@@ -634,7 +634,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 +642,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.35.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)",