@contrast/config 1.15.0 → 1.16.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright: 2022 Contrast Security, Inc
+Copyright: 2023 Contrast Security, Inc
 Contact: support@contrastsecurity.com
 License: Commercial
 

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2023 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -32,33 +32,67 @@ export type SyslogLevel =
   | 'info'
   | 'debug';
 
+export interface ConfigOption<T> {
+  name: string;
+  abbrev?: string;
+  env?: string;
+  arg: string;
+  enum?: T[];
+  default?: T;
+  fn?: (arg: any) => T;
+  desc: string;
+}
+
 export interface Config {
   configFile: string;
-
   _default: Record<string, any>;
   _flat: Record<string, any>;
   _sources: Record<string, 'DEFAULT_VALUE' | 'ENVIRONMENT_VARIABLE' | 'USER_CONFIGURATION_FILE' | 'CONTRAST_UI'>;
+
   api: {
+    /** Default: `true` */
     enable: boolean;
-    api_key: string;
-    service_key: string;
-
     /** Default: `'https://app.contrastsecurity.com/Contrast'` */
     url: string;
-
+    /** No default value but required when `api.enable` is `true` */
+    api_key: string;
+    /** No default value but required when `api.enable` is `true` */
+    service_key: string;
+    /** No default value but required when `api.enable` is `true` */
     user_name: string;
+
     proxy: {
+      /** Default: `false` */
       enable: boolean;
+      /** No default value but required when `api.proxy.enable` is `true` */
       url: string;
     };
   };
 
   agent: {
-    polling: {
-      app_activity_ms: number;
-      app_settings_ms: number;
-      app_update_ms: number;
-      server_settings_ms: number;
+    /**
+     * Limit for stack trace size (larger limits will improve accuracy but
+     * increase memory usage). Default: `10`
+     */
+    stack_trace_limit: number;
+
+    /**
+     * List of patterns to ignore within stack traces.
+     * Default: `['agent-', '@contrast', 'node-agent']
+     */
+    stack_trace_filters: string[];
+
+    diagnostics: {
+      /** Default: `true` */
+      enable: boolean;
+      /** Default: `false` */
+      quiet: boolean
+      report_path?: string;
+    };
+
+    route_coverage: {
+      /** Default: `true` */
+      enable: boolean;
     };
 
     reporters: {
@@ -66,43 +100,56 @@ export interface Config {
       file?: string | number;
     };
 
+    effective_config: {
+      reporting: {
+        /** Default: `true` */
+        enable: boolean;
+      };
+    };
+
+    polling: {
+      /** Default: `30000` */
+      app_activity_ms: number;
+      /** Default: `30000` */
+      app_settings_ms: number;
+      /** Default: `30000` */
+      app_update_ms: number;
+      /** Default: `30000` */
+      server_settings_ms: number;
+    };
+
     logger: {
-      /**
-       * When false, create a new log file on startup instead of appending and
-       * rolling daily. Default: `true`
-       */
-      append: boolean;
+      /** Default: `'./contrast.log'` */
+      path: string;
 
       /**
        * Minimum log level. 'silent' disables logging entirely.
-       * Default: `'error'`
+       * Default: `'info'`
        */
       level: LevelWithSilent;
 
-      /** Default: `'node-contrast'` */
-      path: string;
+      /**
+       * When false, create a new log file on startup instead of appending and
+       * rolling daily. Default: `true`
+       */
+      append: boolean;
 
       /** Suppress output when `false`. Default: `true` */
       stdout: boolean;
     };
 
     security_logger: {
+      /** Default: `'./security.log'` */
+      path: string;
       /** Default: `'error'` */
       level: Level;
-
-      /** Default: `'security'` */
-      path: string;
-
       /** Default: `false` */
       stdout: boolean;
-
       syslog: {
         /** Default: `false` */
         enable: boolean;
-
         /** Default: `'127.0.0.1'` */
         ip: string;
-
         /** Default: `514` */
         port: number;
 
@@ -113,90 +160,107 @@ export interface Config {
          */
         facility: number;
 
-        /** Log level of 'Blocked' attacks. Default: `'notice'` */
-        severity_blocked: SyslogLevel;
-
         /** Log level of 'Exploited' attacks. Default: `'alert'` */
         severity_exploited: SyslogLevel;
-
-        /** Log level of 'Probed' attacks. Default: `'warning'` */
-        severity_probed: SyslogLevel;
-
+        /** Log level of 'Blocked' attacks. Default: `'notice'` */
+        severity_blocked: SyslogLevel;
         /** Log level of 'Blocked at Perimeter' attacks. Default: `'notice'` */
         severity_blocked_perimeter: SyslogLevel;
-
+        /** Log level of 'Probed' attacks. Default: `'warning'` */
+        severity_probed: SyslogLevel;
         /** Log level of suspcious but not blocked attacks. Default: `'warning'` */
         severity_suspicious: SyslogLevel;
       };
-
     };
 
     node: {
+      /** Location to look for the app's package.json. Default: `process.cwd()` */
+      app_root: string;
       /** Default: `true` */
       enable_rewrite: boolean;
-
       /** Default: `true` */
       enable_source_maps: boolean;
+      library_usage: {
+        reporting: {
+          /** Default: `true` */
+          enable: boolean;
+          /** Default: `1` */
+          interval_ms: number;
+        };
+      };
+    };
+  };
 
-      /** Location to look for the app's package.json. Default: `process.cwd()` */
-      app_root: string;
+  inventory: {
+    /** Default: `true` */
+    analyze_libraries: boolean;
+  };
+
+  assess: {
+    /** Default: `false` */
+    enable: boolean;
+    tags?: string;
+    /** Default: `'ALL'` */
+    stacktraces: string;
+    /** Default: `150` */
+    max_context_source_events: number;
+    /** Default: `500` */
+    max_propagation_events: number;
+
+    safe_positives: {
+      /** Default: `false` */
+      enable: boolean;
     };
 
-    /**
-     * Limit for stack trace size (larger limits will improve accuracy but
-     * increase memory usage). Default: `10`
-     */
-    stack_trace_limit: number;
+    /** Defualt: `false` */
+    trust_custom_validators: boolean;
+  };
 
-    /**
-     * List of patterns to ignore within stack traces.
-     * Default: `['agent', '@contrast', 'node-agent']
-     */
-    stack_trace_filters: string[];
+  protect: {
+    /** Default: `false` */
+    enable: boolean;
+
+    probe_analysis: {
+      /** Default: `true` */
+      enable: boolean;
+    }
+
+    rules: {
+      /**
+       * 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. */
     name?: string;
-
     /** override the reported application path. Default: `'/'` */
     path: string;
+    /** override the reported application version */
+    version?: string;
 
     /**
-     * Override the reported application version (if different from 'version'
-     * field in the application's package.json).
+     * Provide the ID of a session existing within Contrast UI.
+     * Default: `null`
      */
-    version?: string;
-
-    /** Provide the ID of a session existing within Contrast UI. */
     session_id: string | null;
 
-    /** Provide metadata used to create a new session within Contrast UI/ */
-    session_metadata: string | null;
-  };
-
-  assess: {
-    tags: string;
-  };
-
-  protect: {
-    enable: boolean;
-
     /**
-     * List of rule ids to disable.
-     * Default: `[]`
+     * Provide metadata used to create a new session within Contrast UI.
+     * Default: `null`
      */
-    disabled_rules: string[];
-
-    rules: Record<Rule, { mode: ProtectRuleMode }>;
+    session_metadata: string | null;
   };
 
   /** Reported server information overrides */
   server: {
-    environment?: string;
-    tags?: string;
     /** Default: `os.hostname()` */
     name: string;
+    environment?: string;
+    tags?: string;
     version?: string;
   };
 }

package/lib/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2023 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 

package/lib/options.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2023 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -13,24 +13,7 @@
  * way not consistent with the End User License Agreement.
  */
 
-/**
- * Sets up the agent config. All options include a name and a description.
- * Where the setting is not a boolean, they include args as well.
- *
- * The module currently houses all new common config settings.
- *
- * 	Other settings include:
- * 	  feature: a property in the TS feature set to tie the config option to
- * 		env: environment variable to check for value in
- * 		fn: a function to run on the original value (eg type coercion or sanitizing).
- * 			returns undefined if it can't do anything with the value it is given.
- * 		enum: validation of whether type matches enumerated value
- *
- * NOTE: I'm not sure if validation should also be specified and handled here.
- *
- * TODO: add defaults to all new options
- * TODO: add mapping for TeamServer FeatureSet analogues where they differ
- */
+// @ts-check
 
 'use strict';
 
@@ -41,10 +24,8 @@ const { Rule } = require('@contrast/common');
 
 /**
  * Takes strings "true"|"t" or "false"|"f" (case insensitive) and return the appropriate boolean.
- * If we can't match one of the two words, return true;
- *
- * @param {boolean|string} value passed arg; never undefined or the function isn't called
- * @return {boolean}
+ * @param {boolean | string} value passed arg; never undefined or the function isn't called
+ * @return {boolean | undefined}
  */
 function castBoolean(value) {
   const type = typeof value;
@@ -63,7 +44,7 @@ function castBoolean(value) {
  * Takes string path and resolves absolute path based on current working dir
  *
  * @param {string} value passed arg; never undefined or the function isn't called
- * @return {string} absolute path resolve from process.cwd()
+ * @return {string | undefined} absolute path resolve from process.cwd()
  */
 function toAbsolutePath(value) {
   return value ? path.resolve(process.cwd(), String(value)) : undefined;
@@ -89,7 +70,27 @@ const parseNum = (val) => {
   return clearBaseCase(Math.ceil(float));
 };
 
-const config = [
+/**
+ * Sets up the agent config. All options include a name and a description.
+ * Where the setting is not a boolean, they include args as well.
+ *
+ * The module currently houses all new common config settings.
+ *
+ * Other settings include:
+ * - env: environment variable to check for value in
+ * - fn: a function to run on the original value (eg type coercion or sanitizing). returns undefined if it can't do anything with the value it is given.
+ * - enum: validation of whether type matches enumerated value
+ *
+ * NOTE: I'm not sure if validation should also be specified and handled here.
+ *
+ * TODO: add defaults to all new options
+ *
+ * TODO: add mapping for TeamServer FeatureSet analogues where they differ
+ *
+ * @type {import('.').ConfigOption[]}
+ */
+const options = [
+  // config
   {
     name: 'configFile',
     abbrev: 'c',
@@ -98,27 +99,13 @@ const config = [
     arg: '<path>',
     desc: 'set config file location. defaults to <app_root>/contrast_security.yaml',
   },
-];
-
-const api = [
+  // api
   {
     name: 'api.enable',
     arg: '[false]',
-    fn: castBoolean,
     default: true,
-    desc: 'set false to disable reporting',
-  },
-  {
-    name: 'api.api_key',
-    env: 'CONTRASTSECURITY_API_KEY',
-    arg: '<key>',
-    desc: 'the organization API key',
-  },
-  {
-    name: 'api.service_key',
-    env: 'CONTRASTSECURITY_SECRET_KEY',
-    arg: '<key>',
-    desc: 'account service key',
+    fn: castBoolean,
+    desc: 'Set to `false` to disable Contrast UI communication.',
   },
   {
     name: 'api.url',
@@ -155,295 +142,361 @@ const api = [
       }
       return value;
     },
-    desc: 'url to report on',
+    desc: 'Set the URL for the Contrast UI.',
+  },
+  {
+    name: 'api.api_key',
+    env: 'CONTRASTSECURITY_API_KEY',
+    arg: '<key>',
+    desc: 'Set the API key needed to communicate with the Contrast UI.',
+  },
+  {
+    name: 'api.service_key',
+    env: 'CONTRASTSECURITY_SECRET_KEY',
+    arg: '<key>',
+    desc: 'Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header.',
   },
   {
     name: 'api.user_name',
     env: 'CONTRASTSECURITY_UID',
     arg: '<name>',
-    desc: 'account user name',
+    desc: 'Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.',
   },
+  // api.proxy
   {
     name: 'api.proxy.enable',
     arg: '[true]',
     default: false,
-    desc: 'if false, no proxy is being used for communication of data',
+    desc: "Set value to `true` for the agent to communicate with the Contrast web interface over a proxy. Set value to `false` if you don't want to use the proxy.",
   },
   {
     name: 'api.proxy.url',
     arg: '<url>',
-    desc: 'url of proxy for communicating agent data',
-  }
-];
-
-const agent = [
+    desc: 'Set the URL for your Proxy Server. The URL form is `scheme://host:port`.',
+  },
+  // agent
+  {
+    name: 'agent.stack_trace_limit',
+    arg: '<limit>',
+    default: 10,
+    fn: parseNum,
+    desc: 'Set to limit the length of Error stack traces to a specified number. Larger limits will improve accuracy but increase memory usage.',
+  },
+  {
+    // NOTE: not in common config.
+    name: 'agent.stack_trace_filters',
+    arg: '<list,of,filters>',
+    default: 'agent-,@contrast,node-agent',
+    fn: split,
+    desc: 'comma-separated list of patterns to ignore within stack traces',
+  },
+  // agent.diagnostics
   {
     name: 'agent.diagnostics.enable',
     arg: '[false]',
     default: true,
     fn: castBoolean,
-    desc: 'If true the agent will try to create both diagnostic files at startup',
-  },
-  {
-    name: 'agent.diagnostics.quiet',
-    arg: '[true]',
-    default: false,
-    fn: castBoolean,
-    desc: 'If true the agent will print all diagnostic results to stdout as well',
+    desc: 'Set to `false` to disable agent diagnostics.',
   },
   {
     name: 'agent.diagnostics.report_path',
     arg: '<path>',
-    desc: 'path indicating where to report all diagnostics results',
+    default: '.',
+    fn: toAbsolutePath,
+    desc: "Set the directory in which to write diagnostic files. Defaults to the application's current working directory.",
+  },
+  // agent.route_coverage
+  {
+    name: 'agent.route_coverage.enable',
+    arg: '[false]',
+    default: true,
+    fn: castBoolean,
+    desc: 'Set to `false` for the agent to not send route-based coverage data to the Contrast UI.',
   },
+  // agent.reporters
+  // NOTE: Java has a `reporting` node--use that?
   {
     name: 'agent.reporters.file',
     arg: '<path>',
     desc: 'path indicating where to report all agent findings',
   },
+  // agent.effective_config
   {
-    name: 'agent.logger.append',
+    name: 'agent.effective_config.reporting.enable',
     arg: '[false]',
-    fn: castBoolean,
     default: true,
-    desc: 'if false, create a new log file on startup instead of appending and rolling daily',
+    fn: castBoolean,
+    desc: 'Defaults to `true`. Controls whether configuration setting reports are sent to the Contrast web interface.',
   },
+  // agent.polling
   {
-    name: 'agent.logger.level',
-    arg: '<level>',
-    fn: lowercase,
-    enum: ['error', 'warn', 'info', 'debug', 'trace'],
-    desc: 'logging level (error, warn, info, debug, trace). overrides FeatureSet:logLevel',
+    name: 'agent.polling.app_activity_ms',
+    arg: '<ms>',
+    default: 30000,
+    fn: parseNum,
+    desc: 'Set the frequency with which the agent sends application activity to the Contrast UI.',
   },
+  {
+    name: 'agent.polling.app_settings_ms',
+    arg: '<ms>',
+    default: 30000,
+    fn: parseNum,
+    desc: 'Set the frequency with which the agent sends application settings polls to the Contrast UI.',
+  },
+  {
+    name: 'agent.polling.app_update_ms',
+    arg: '<ms>',
+    default: 30000,
+    fn: parseNum,
+    desc: 'Set the the frequency with which the agent sends application updates to the Contrast UI.',
+  },
+  {
+    name: 'agent.polling.server_settings_ms',
+    arg: '<ms>',
+    default: 30000,
+    fn: parseNum,
+    desc: 'Set the frequency with which the agent sends server settings polls to the Contrast UI.',
+  },
+  // agent.logger
   {
     name: 'agent.logger.path',
+    arg: '<path>',
     default: 'contrast.log',
     fn: toAbsolutePath,
-    arg: '<path>',
-    desc: 'where contrast will put its debug log',
+    desc: `Enable diagnostic logging by setting a path to a log file. While diagnostic logging hurts performance, it generates useful information for debugging Contrast. The value set here is the location to which the agent saves log output. If no log file exists at this location, the agent creates a file.
+Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\` directory, and rotates it automatically as needed.`,
   },
   {
-    name: 'agent.logger.stdout',
+    name: 'agent.logger.level',
+    arg: '<level>',
+    enum: ['error', 'warn', 'info', 'debug', 'trace'],
+    // default: 'info', this has no default at the config level but is instead handled by `logger-factory`.
+    fn: lowercase,
+    desc: 'Set the the log output level. Valid options are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.',
+  },
+  {
+    name: 'agent.logger.append',
     arg: '[false]',
-    fn: castBoolean,
     default: true,
-    desc: 'if false, suppress output to STDOUT',
+    fn: castBoolean,
+    desc: 'Set to `false` for the agent to always create a new log file instead of appending and rolling.',
   },
   {
-    name: 'agent.security_logger.level',
-    default: 'error',
-    arg: '<level>',
-    fn: lowercase,
-    enum: ['error', 'warn', 'info', 'debug', 'trace'],
-    desc: 'security logging level (error, warn, info, debug, trace)',
+    name: 'agent.logger.stdout',
+    arg: '[false]',
+    default: true,
+    fn: castBoolean,
+    desc: 'Set to `false` to suppress log output to `stdout`.',
   },
+  // agent.security_logger
   {
     name: 'agent.security_logger.path',
+    arg: '<path>',
     default: 'security.log',
     fn: toAbsolutePath,
-    arg: '<path>',
-    desc: 'where to log security events',
+    desc: 'Set the file to which the agent logs security events.',
+  },
+  {
+    name: 'agent.security_logger.level',
+    arg: '<level>',
+    enum: ['error', 'warn', 'info', 'debug', 'trace'],
+    default: 'error',
+    fn: lowercase,
+    desc: 'Set the log level for security logging. Valid options are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.',
   },
   {
     name: 'agent.security_logger.stdout',
     arg: '[false]',
     default: false,
     fn: castBoolean,
-    desc: 'if true will output the security_logger loggs to stdout too',
+    desc: 'Set to `true` to log output to `stdout` as well as the configured file.',
   },
+  // agent.security_logger.syslog
   {
     name: 'agent.security_logger.syslog.enable',
+    arg: '[true]',
     default: false,
     fn: castBoolean,
-    desc: 'Set to true to enable Syslog logging',
+    desc: 'Set to `true` to enable Syslog logging.',
   },
   {
     name: 'agent.security_logger.syslog.ip',
-    default: '127.0.0.1',
-    desc: 'Set the IP address of the Syslog server to which the agent should send messages',
     arg: '<ip>',
+    default: '127.0.0.1',
+    desc: 'Set the IP address of the Syslog server to which the agent should send messages.',
   },
   {
     name: 'agent.security_logger.syslog.port',
-    default: '514',
-    desc: 'Set the port of the Syslog server to which the agent should send messages',
     arg: '<port>',
+    default: 514,
     fn: parseNum,
+    desc: 'Set the port of the Syslog server to which the agent should send messages.',
   },
   {
     name: 'agent.security_logger.syslog.facility',
-    default: '19',
-    desc: 'Set the facility code of the messages the agent sends to Syslog',
-    enum: [
-      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
-      21, 22, 23,
-    ],
     arg: '<facility>',
+    enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23],
+    default: 19,
     fn: parseNum,
+    desc: 'Set the facility code of the messages the agent sends to Syslog.',
   },
   {
-    name: 'agent.security_logger.syslog.severity_blocked',
-    default: 'notice',
-    desc: 'Set the log level of Blocked attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
-    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    name: 'agent.security_logger.syslog.severity_exploited',
     arg: '<level>',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'alert',
     fn: lowercase,
+    desc: 'Set the log level of Exploited attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.',
   },
   {
-    name: 'agent.security_logger.syslog.severity_exploited',
-    default: 'alert',
-    desc: 'Set the log level of Exploited attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
+    name: 'agent.security_logger.syslog.severity_blocked',
+    arg: '<level>',
     enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'notice',
+    fn: lowercase,
+    desc: 'Set the log level of Blocked attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.',
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_blocked_perimiter',
     arg: '<level>',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'notice',
     fn: lowercase,
+    desc: 'Set the log level of Blocked At Perimeter attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.',
   },
   {
     name: 'agent.security_logger.syslog.severity_probed',
-    default: 'warning',
-    desc: 'Set the log level of Probed attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
-    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
     arg: '<level>',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'warning',
     fn: lowercase,
+    desc: 'Set the log level of Probed attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.',
   },
   {
     name: 'agent.security_logger.syslog.severity_suspicious',
-    default: 'warning',
-    desc: 'Set the log level of suspicious but not blocked attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
-    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
     arg: '<level>',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'warning',
     fn: lowercase,
+    desc: 'Set the log level of Suspicious attacks. Value options are `ALERT`, `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.',
   },
+  // agent.node
   {
+    name: 'agent.node.app_root',
+    arg: '<path>',
+    default: process.cwd(),
+    desc: "Set the directory containing the application's `package.json` file.",
+  },
+  {
+    // NOTE: not in common config.
     name: 'agent.node.enable_rewrite',
     arg: '[false]',
-    fn: castBoolean,
     default: true,
-    desc: 'if false, disable source rewriting (not recommended)',
+    fn: castBoolean,
+    desc: 'Set to `false` to disable source code rewriting. Not recommended.',
   },
   {
+    // NOTE: not in common config.
     name: 'agent.node.enable_source_maps',
     arg: '[false]',
-    fn: castBoolean,
     default: true,
-    desc: 'enable source map support in reporting',
+    fn: castBoolean,
+    desc: 'Set to `true` to enable source map support in reporting.',
   },
+  // agent.node.library_usage.reporting
   {
-    name: 'agent.node.app_root',
-    arg: '<path>',
-    desc: "set location to look for the app's package.json",
-    default: process.cwd(),
+    name: 'agent.node.library_usage.reporting.enable',
+    arg: '[false]',
+    default: true,
+    fn: castBoolean,
+    desc: 'Set to `false` to disable enhanced library usage features, i.e. scanning for composition of dependencies, reporting library usage.',
   },
   {
-    name: 'agent.node.library_usage.reporting.interval',
+    name: 'agent.node.library_usage.reporting.interval_ms',
     arg: '<num>',
-    fn: parseNum,
     default: 1,
-    desc: 'frequency of collecting code events for library usage in milliseconds, defaults to 1 ms',
+    desc: 'Set the interval (in milliseconds) for collecting code events for library usage.',
   },
+  // inventory
   {
-    name: 'agent.node.library_usage.reporting.enable',
+    name: 'inventory.analyze_libraries',
     arg: '[false]',
-    // setting this falsee for now, until feature is complete
     default: true,
     fn: castBoolean,
-    desc: 'add enhanced library usage features (i.e. scanning for composition of dependencies, reporting usage)',
+    desc: 'Set to `false` to disable library analysis.',
   },
+  // assess
   {
-    name: 'agent.stack_trace_limit',
-    arg: '<limit>',
-    default: 10,
-    fn: parseNum,
-    desc: 'set limit for stack trace size (larger limits will improve accuracy but increase memory usage)',
-  },
-  {
-    name: 'agent.stack_trace_filters',
-    arg: '<list,of,filters>',
-    default: 'agent-,@contrast,node-agent',
-    fn: split,
-    desc: 'comma-separated list of patterns to ignore within stack traces',
+    name: 'assess.enable',
+    arg: '[true]',
+    default: false,
+    fn: castBoolean,
+    desc: 'Include this property to determine if the Assess feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.',
   },
   {
-    name: 'agent.polling.app_activity_ms',
-    arg: '<ms>',
-    default: 30000,
-    fn: parseNum,
-    desc: 'how often (in ms) application activity messages are sent to the UI',
+    name: 'assess.tags',
+    arg: '<tags>',
+    desc: `Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list.
+Example - \`label1, label2, label3\``,
   },
   {
-    name: 'agent.polling.app_update_ms',
-    arg: '<ms>',
-    default: 30000,
-    fn: parseNum,
-    desc: 'how often (in ms) application updates are sent to the UI'
+    name: 'assess.stacktraces',
+    arg: '<level>',
+    enum: ['ALL', 'SOME', 'NONE'],
+    default: 'ALL',
+    fn: uppercase,
+    desc: 'Select the level of collected stacktraces. ALL - for all assess events, SOME - for Source and Sink events, NONE - no stacktraces collected',
   },
   {
-    name: 'agent.polling.app_settings_ms',
-    arg: '<ms>',
-    default: 30000,
+    name: 'assess.max_context_source_events',
+    arg: '<limit>',
+    default: 150,
     fn: parseNum,
-    desc: 'how often (in ms) application settings polls are sent to the UI',
+    desc: 'Set the maximum number of untrusted data flows to observe per request.',
   },
   {
-    name: 'agent.polling.server_settings_ms',
-    arg: '<ms>',
-    default: 30000,
+    name: 'assess.max_propagation_events',
+    arg: '<limit>',
+    default: 500,
     fn: parseNum,
-    desc: 'how often (in ms) server settings polls are sent to the UI',
-  }
-];
-
-const application = [
-  {
-    name: 'application.name',
-    arg: '<name>',
-    env: 'CONTRASTSECURITY_APP_NAME',
-    desc: 'override the reported application name. (default: package.json:name)',
-  },
-  {
-    name: 'application.path',
-    arg: '<path>',
-    default: '/',
-    desc: 'override the reported application path',
-  },
-  {
-    name: 'application.version',
-    arg: '<version>',
-    desc: "override the reported application version (if different from 'version' field in the application's package.json)",
+    desc: 'Set the maximum number of untrusted data flow propagations to observe per request.',
   },
   {
-    name: 'application.session_id',
-    arg: '<session_id>',
-    default: null,
-    desc: 'provide the ID of a session existing within Contrast UI',
+    name: 'assess.safe_positives.enable',
+    arg: '[false]',
+    default: false,
+    fn: castBoolean,
+    desc: 'enable detection and reporting of findings regarding safe security practices, aka safe positives. ' +
+      'these results will be written to the location described by the `agent.reporters.file` option.',
   },
   {
-    name: 'application.session_metadata',
-    arg: '<session_metadata>',
-    default: null,
-    desc: 'provide metadata used to create a new session within Contrast UI',
+    name: 'assess.trust_custom_validators',
+    arg: '<trust-custom-validators>',
+    default: false,
+    fn: castBoolean,
+    desc: 'Set to `true` to trust incoming strings when they pass custom validators (Mongoose, Joi, validator, fastify-static).',
   },
-];
-
-const protect = [
+  // protect
   {
     name: 'protect.enable',
-    arg: '[false]',
+    arg: '[true]',
+    default: false,
     fn: castBoolean,
-    desc: 'if false, disable protect for this agent',
-  },
-  {
-    name: 'protect.disabled_rules',
-    arg: '<list,of,rules>',
-    fn: split,
-    default: '',
-    desc: 'comma-separated list of rule ids to disable',
+    desc: 'Include this property to determine if the Protect feature should be enabled. If this property is not present, the decision is delegated to the Contrast UI.',
   },
   {
     name: 'protect.probe_analysis.enable',
     arg: '[false]',
     default: true,
     fn: castBoolean,
-    desc: 'turns on probe analysis and report them to Contrast UI'
+    desc: 'Set to `false` to disable probe analysis.',
+  },
+  {
+    name: 'protect.rules.disabled_rules',
+    arg: '<list,of,rules>',
+    default: '',
+    fn: split,
+    desc: 'Define a list of Protect rules to disable in the agent. The rules must be formatted as a comma-delimited list.',
   },
   ...Object.values(Rule)
     .filter((ruleId) => ![Rule.BOT_BLOCKER, Rule.IP_DENYLIST, Rule.VIRTUAL_PATCH].includes(ruleId))
@@ -451,93 +504,67 @@ const protect = [
       name: `protect.rules.${ruleId}.mode`,
       arg: '<mode>',
       enum: ['monitor', 'block', 'block_at_perimeter', 'off'],
-      desc: `the mode in which to run the ${ruleId} rule`,
+      desc: 'Set the mode of the rule. Value options are `monitor`, `block`, `block_at_perimeter`, or `off`.',
     })),
-];
-
-const assess = [
+  // application
   {
-    name: 'assess.enable',
-    arg: '[false]',
-    fn: castBoolean,
-    desc: 'if false, disable assess for this agent'
+    name: 'application.name',
+    env: 'CONTRASTSECURITY_APP_NAME',
+    arg: '<name>',
+    desc: "Override the reported application name. Defaults to the `name` field from an application's `package.json`",
   },
   {
-    name: 'assess.trust_custom_validators',
-    arg: '<trust-custom-validators>',
-    fn: castBoolean,
-    default: false,
-    desc: 'trust incoming strings when they pass custom validators (Mongoose, Joi)',
+    name: 'application.path',
+    arg: '<path>',
+    default: '/',
+    desc: 'Override the reported application path.',
   },
   {
-    name: 'assess.stacktraces',
-    arg: '<level>',
-    default: 'ALL',
-    fn: uppercase,
-    enum: ['ALL', 'SOME', 'NONE'],
-    desc: 'Select the level of collected stacktraces. ALL - for all asses events, SOME - for Source and Sink events, NONE - no stacktraces collected'
+    name: 'application.version',
+    arg: '<version>',
+    desc: "Override the reported application version. Defaults to the `version` field from an application's `package.json`",
   },
   {
-    name: 'assess.max_propagation_events',
-    arg: '<limit>',
-    default: 500,
-    fn: parseNum,
-    desc: 'set limit for maximum number of propagation events created per request',
+    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: 'assess.max_context_source_events',
-    arg: '<limit>',
-    default: 150,
-    fn: parseNum,
-    desc: 'set limit for maximum number of source events (tracked strings) created per request',
+    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.',
   },
+  // server
   {
-    name: 'assess.safe_positives.enable',
-    arg: '[false]',
-    default: false,
-    fn: castBoolean,
-    desc: 'enable detection and reporting of findings regarding safe security practices, aka safe positives. ' +
-      'these results will be written to the location described by the `agent.reporters.file` option.',
+    name: 'server.name',
+    arg: '<name>',
+    default: os.hostname(),
+    desc: 'Override the reported server name. Defauls to the operating system hostname.',
   },
-];
-
-const server = [
   {
     name: 'server.environment',
     arg: '<environment>',
-    fn: uppercase,
     // enum: ['QA', 'PRODUCTION', 'DEVELOPMENT'], none of the other agents validate this
-    desc: 'environment the server is running in (QA, PRODUCTION, or DEVELOPMENT)',
+    fn: uppercase,
+    desc: `Set the environment directly to override the default set by the Contrast UI. This allows the user to configure the environment dynamically at startup rather than manually updating the Server in the Contrast UI themselves afterwards.
+Valid values include \`QA\`, \`PRODUCTION\` and \`DEVELOPMENT\`. For example, \`PRODUCTION\` registers this Server as running in a \`PRODUCTION\` environment, regardless of the organization's default environment in the Contrast UI.`,
   },
   {
     name: 'server.tags',
     arg: '<tags>',
-    desc:
-      'server tags provided by the user to the agent that instrumented this server.',
-  },
-  {
-    name: 'server.name',
-    arg: '<name>',
-    default: os.hostname(),
-    desc: 'override the reported server name',
+    desc: `Apply a list of labels to the server. Labels must be formatted as a comma-delimited list.
+Example - \`label1, label2, label3\``,
   },
   {
+    // NOTE: not in common config, and the desc here doesn't really make sense.
     name: 'server.version',
     arg: '<version>',
     desc: "override the reported server version (if different from 'version' field in the application's package.json)",
   },
 ];
 
-const options = [].concat(
-  config,
-  api,
-  agent,
-  application,
-  protect,
-  assess,
-  server
-);
-
 module.exports.configOptions = options;
 module.exports.clearBaseCase = clearBaseCase;
 module.exports.castBoolean = castBoolean;

package/lib/util.js

@@ -1,5 +1,5 @@
 /*
- * Copyright: 2022 Contrast Security, Inc
+ * Copyright: 2023 Contrast Security, Inc
  * Contact: support@contrastsecurity.com
  * License: Commercial
 
@@ -52,18 +52,21 @@ class Config {
       _default: {},
       _flat: {},
       _sources: {},
+      api: {},
       agent: {
+        diagnostics: {},
         reporters: {},
+        security_logger: {},
         logger: {},
         node: {},
       },
-      application: {},
+      inventory: {},
+      assess: {},
       protect: {
         rules: {},
       },
-      assess: {},
+      application: {},
       server: {},
-      api: {},
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/config",
-  "version": "1.15.0",
+  "version": "1.16.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)",
@@ -17,7 +17,7 @@
     "test": "../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.13.0",
+    "@contrast/common": "1.14.0",
     "yaml": "^2.2.2"
   }
 }