@contrast/config 1.32.0 → 1.34.0

package/lib/common.js

@@ -39,8 +39,18 @@ const {
     UNTRUSTED_DESERIALIZATION,
     XXE,
   },
+  primordials: { StringPrototypeToLowerCase },
+  get,
+  isString,
 } = require('@contrast/common');
 
+function coerceLowerCase(path) {
+  return function(remoteData) {
+    const value = get(remoteData, path);
+    if (value && isString(value)) return StringPrototypeToLowerCase.call(value);
+  };
+}
+
 function protectModeReader(ruleId) {
   return function (msg) {
     const remoteSetting = msg?.protect?.rules?.[ruleId];
@@ -62,20 +72,11 @@ const ConfigSource = {
   USER_CONFIGURATION_FILE: 'USER_CONFIGURATION_FILE',
 };
 
+// these should return `undefined` if there is no remote value corresponding to the effective config name.
 const mappings = {
-  // server features
-  'agent.logger.level': (remoteData) => remoteData.logger?.level?.toLowerCase?.(),
-  'agent.logger.path': (remoteData) => remoteData.logger?.path,
-  'application.session_id': (remoteData) => remoteData?.settings?.assessment?.session_id,
-  'agent.security_logger.syslog.enable': (remoteData) => remoteData.security_logger?.syslog?.enable,
-  'agent.security_logger.syslog.ip': (remoteData) => remoteData.security_logger?.syslog?.ip,
-  'agent.security_logger.syslog.port': (remoteData) => remoteData.security_logger?.syslog?.port,
-  'agent.security_logger.syslog.facility': (remoteData) => remoteData.security_logger?.syslog?.facility,
-  'agent.security_logger.syslog.severity_exploited': (remoteData) => remoteData.security_logger?.syslog?.severity_exploited?.toLowerCase(),
-  'agent.security_logger.syslog.severity_blocked': (remoteData) => remoteData.security_logger?.syslog?.severity_blocked?.toLowerCase(),
-  'agent.security_logger.syslog.severity_probed': (remoteData) => remoteData.security_logger?.syslog?.severity_probed?.toLowerCase(),
+  // application-create
+  'application.session_id': (remoteData) => remoteData.settings?.assessment?.session_id,
   // application settings
-  'assess.enable': (remoteData) => remoteData.assess?.enable,
   'protect.enable': (remoteData) => remoteData.protect?.enable,
   'protect.rules.cmd-injection.mode': protectModeReader(CMD_INJECTION),
   'protect.rules.cmd-injection-command-backdoors.mode': protectModeReader(CMD_INJECTION_COMMAND_BACKDOORS),
@@ -92,6 +93,27 @@ const mappings = {
   'protect.rules.unsafe-file-upload.mode': protectModeReader(UNSAFE_FILE_UPLOAD),
   'protect.rules.untrusted-deserialization.mode': protectModeReader(UNTRUSTED_DESERIALIZATION),
   'protect.rules.xxe.mode': protectModeReader(XXE),
+  // server features
+  'assess.enable': (remoteData) => remoteData.assess?.enable,
+  'assess.probabilistic_sampling.enable': (remoteData) => remoteData.assess?.sampling?.enable,
+  'assess.probabilistic_sampling.base_probability': (remoteData) => {
+    const request_frequency = remoteData.assess?.sampling?.request_frequency;
+    if (request_frequency > 0) {
+      const baseProbability = 1 / request_frequency;
+      if (!isNaN(baseProbability)) return baseProbability;
+    }
+  },
+  'agent.logger.level': coerceLowerCase('logger.level'),
+  'agent.logger.path': (remoteData) => remoteData.logger?.path,
+  'agent.security_logger.syslog.enable': (remoteData) => remoteData.security_logger?.syslog?.enable,
+  'agent.security_logger.syslog.ip': (remoteData) => remoteData.security_logger?.syslog?.ip,
+  'agent.security_logger.syslog.port': (remoteData) => remoteData.security_logger?.syslog?.port,
+  'agent.security_logger.syslog.facility': (remoteData) => remoteData.security_logger?.syslog?.facility,
+  'agent.security_logger.syslog.severity_exploited': coerceLowerCase('security_logger.syslog.severity_exploited'),
+  'agent.security_logger.syslog.severity_blocked': coerceLowerCase('security_logger.syslog.severity_blocked'),
+  'agent.security_logger.syslog.severity_probed': coerceLowerCase('security_logger.syslog.severity_probed'),
+  'server.environment': (remoteData) => remoteData.environment,
+
 };
 
 /*

package/lib/common.test.js

@@ -0,0 +1,183 @@
+'use strict';
+
+const { expect } = require('chai');
+const { ProtectRuleMode } = require('@contrast/common');
+const { mappings } = require('./common');
+
+describe('config effective value mappings', function () {
+  describe('"simple" mappings', function() {
+    const simplyMappedNames = [
+      'assess.enable',
+      'agent.logger.path',
+      'agent.security_logger.syslog.enable',
+      'agent.security_logger.syslog.ip',
+      'agent.security_logger.syslog.port',
+      'agent.security_logger.syslog.facility',
+      'server.environment',
+      'protect.enable',
+    ];
+
+    it('"simple" mappings will return any value for corresponding remote setting (todo: validation for each)', function () {
+      ['', 'foo', null, 0.3, 3, {}, [], true, false].forEach((val) => {
+        const remoteData = {
+          // server
+          assess: {
+            enable: val,
+            sampling: { enable: val }
+          },
+          logger: {
+            path: val,
+          },
+          security_logger: {
+            syslog: {
+              enable: val,
+              ip: val,
+              port: val,
+              facility: val,
+              serverity_exploited: val,
+              serverity_blocked: val,
+              exploited_probed: val,
+            }
+          },
+          environment: val,
+          // app
+          protect: {
+            enable: val,
+          },
+        };
+
+        for (const name of simplyMappedNames) {
+          const result = mappings[name](remoteData);
+          expect(result).to.equal(val);
+        }
+      });
+    });
+
+    it('"simple" mappings will return `undefined` if there is no corresponding remote setting', function () {
+      for (const name of simplyMappedNames) {
+        expect(mappings[name]({})).to.equal(undefined);
+      }
+    });
+  });
+
+  describe('maps \'assess.probabilistic_sampling.base_probability\'', function() {
+    [
+      {
+        desc: 'sets value by inverting request_frequency',
+        remoteData: {
+          assess: { sampling: { request_frequency: 20 } }
+        },
+        expected: 1 / 20,
+      },
+      {
+        desc: 'ignores and returns undefined if request_frequency is 0',
+        remoteData: {
+          assess: { sampling: { request_frequency: 0 } }
+        },
+        expected: undefined,
+      },
+      {
+        desc: 'ignores and returns undefined if calculating probability gives NaN',
+        remoteData: {
+          assess: { sampling: { request_frequency: 'forty five' } }
+        },
+        expected: undefined,
+      },
+      {
+        desc: 'ignores and returns undefined if value is negative',
+        remoteData: {
+          assess: { sampling: { request_frequency: -12 } }
+        },
+        expected: undefined,
+      },
+    ].forEach(({ desc, remoteData, expected }) => {
+      it(desc, function() {
+        expect(mappings['assess.probabilistic_sampling.base_probability'](remoteData)).to.equal(expected);
+      });
+    });
+  });
+
+  describe('maps Protect rule modes', function() {
+    [
+      {
+        tsValue: 'OFF',
+        expected: ProtectRuleMode.OFF,
+      },
+      {
+        tsValue: 'MONITORING',
+        expected: ProtectRuleMode.MONITOR,
+      },
+      {
+        tsValue: 'BLOCKING',
+        expected: ProtectRuleMode.BLOCK,
+      },
+      {
+        tsValue: 'BLOCK_AT_PERIMETER',
+        expected: ProtectRuleMode.BLOCK_AT_PERIMETER,
+      },
+      {
+        tsValue: 'FOO',
+        expected: undefined
+      },
+    ].forEach(({ desc, tsValue, expected }) => {
+      [
+        'protect.rules.cmd-injection.mode',
+        'protect.rules.cmd-injection-command-backdoors.mode',
+        'protect.rules.cmd-injection-semantic-chained-commands.mode',
+        'protect.rules.cmd-injection-semantic-dangerous-paths.mode',
+        'protect.rules.method-tampering.mode',
+        'protect.rules.nosql-injection.mode',
+        'protect.rules.nosql-injection-mongo.mode',
+        'protect.rules.path-traversal.mode',
+        'protect.rules.path-traversal-semantic-file-security-bypass.mode',
+        'protect.rules.reflected-xss.mode',
+        'protect.rules.sql-injection.mode',
+        'protect.rules.ssjs-injection.mode',
+        'protect.rules.unsafe-file-upload.mode',
+        'protect.rules.untrusted-deserialization.mode',
+        'protect.rules.xxe.mode',
+      ].forEach((fullName) => {
+        const ruleName = /rules\.(.*)\.mode/.exec(fullName)[1];
+        it(`sets ${ruleName} to ${expected} when value is ${tsValue}`, function() {
+          expect(mappings[fullName]({
+            protect: {
+              rules: {
+                [ruleName]: { mode: tsValue },
+              }
+            }
+          })).to.equal(expected);
+        });
+      });
+    });
+  });
+
+  describe('maps security logger severity levels (lowercase)', function() {
+    [
+      {
+        tsValue: 'FOO',
+        expected: 'foo',
+      },
+      {
+        tsValue: '',
+        expected: undefined,
+      }
+    ].forEach(({ tsValue, expected }) => {
+      [
+        'agent.security_logger.syslog.severity_exploited',
+        'agent.security_logger.syslog.severity_blocked',
+        'agent.security_logger.syslog.severity_probed',
+      ].forEach((fullName) => {
+        const severity = fullName.substr(fullName.lastIndexOf('.') + 1);
+        it(`maps to ${expected} when tsValue is ${tsValue}`, function() {
+          expect(mappings[fullName]({
+            security_logger: {
+              syslog: {
+                [severity]: tsValue,
+              },
+            }
+          })).to.equal(expected);
+        });
+      });
+    });
+  });
+});

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 } = require('@contrast/common');
+const { Event, get, set, primordials: { ArrayPrototypeJoin, BufferPrototypeToString, StringPrototypeToUpperCase, JSONParse } } = require('@contrast/common');
 const options = require('./options');
 const {
   ConfigSource: {
@@ -38,7 +38,7 @@ const HOME_CONFIG_DIR = path.resolve(os.homedir(), '.config', 'contrast');
 const OS_CONFIG_DIR = os.platform() === 'win32'
   ? path.resolve(process.env.ProgramData || '', 'contrast')
   : '/etc/contrast';
-const REDACTED_KEYS = ['api.api_key', 'api.service_key'];
+const REDACTED_KEYS = ['api.api_key', 'api.service_key', 'api.token'];
 const OVERRIDABLE_SOURCES = [DEFAULT_VALUE, CONTRAST_UI];
 
 module.exports = class Config {
@@ -48,6 +48,7 @@ module.exports = class Config {
     this._errors = [];
     this._effectiveMap = new Map();
     this._status = '';
+    this._logs = [];
 
     // config object
     this.api = {};
@@ -73,7 +74,7 @@ module.exports = class Config {
 
     // report all the errors found during initialization.
     if (this._errors.length) {
-      const errors = this._errors.map((e, ix) => `${ix + 1}) ${e.message}`).join('; ');
+      const errors = ArrayPrototypeJoin.call(this._errors.map((e, ix) => `${ix + 1}) ${e.message}`), '; ');
       throw new Error(`Errors found in configuration ${errors}`);
     }
 
@@ -103,7 +104,7 @@ module.exports = class Config {
       let parsedEnv;
 
       try {
-        parsedEnv = JSON.parse(env.pm2_env);
+        parsedEnv = JSONParse(env.pm2_env);
       } catch (_err) {
         const err = new Error(`Unable to parse pm2 environment variable: '${env.pm2_env}'`);
         err.cause = _err;
@@ -121,7 +122,7 @@ module.exports = class Config {
     }
 
     return Object.entries(env).reduce((acc, [key, val]) => {
-      const name = key.toUpperCase();
+      const name = StringPrototypeToUpperCase.call(key);
       if (name.startsWith('CONTRAST_')) {
         acc[name] = val;
       }
@@ -164,7 +165,7 @@ module.exports = class Config {
       let fileContents;
 
       try {
-        fileContents = fs.readFileSync(_filepath).toString('utf-8');
+        fileContents = BufferPrototypeToString.call(fs.readFileSync(_filepath), 'utf-8');
       } catch (e) {
         const err = new Error(`Unable to read Contrast configuration file: '${_filepath}'`);
         err.cause = e;
@@ -207,7 +208,7 @@ module.exports = class Config {
         source = DEFAULT_VALUE;
       }
 
-      if (opt.fn) value = opt.fn(value);
+      if (opt.fn) value = opt.fn(value, this, source);
       if (opt.enum && !opt.enum.includes(value)) value = opt.default;
 
       set(this, opt.name, value);
@@ -221,7 +222,7 @@ module.exports = class Config {
   }
 
   _redact(name, value) {
-    if (value == null) return value;
+    if (value === null) return value;
     return REDACTED_KEYS.includes(name) ? `contrast-redacted-${name}` : value;
   }
 
@@ -239,12 +240,14 @@ module.exports = class Config {
     const effective_config = [], environment_variable = [], contrast_ui = [];
 
     Array.from(this._effectiveMap.values()).forEach((v) => {
-      let value = redact ? this._redact(v.name, v.value) : v.value;
+      let { value } = v;
+      if (redact) value = this._redact(v.name, v.value);
       if (value === undefined) value = null;
 
-      effective_config.push({ ...v, value: String(value) });
-      if (v.source === ENVIRONMENT_VARIABLE) environment_variable.push(v);
-      if (v.source === CONTRAST_UI) contrast_ui.push(v);
+      const redacted = { ...v, value: String(value) };
+      effective_config.push(redacted);
+      if (v.source === ENVIRONMENT_VARIABLE) environment_variable.push(redacted);
+      if (v.source === CONTRAST_UI) contrast_ui.push(redacted);
     });
 
     return {

package/lib/index.d.ts

@@ -15,13 +15,13 @@
 
 import { ProtectRuleMode, Rule } from '@contrast/common';
 import { LevelWithSilent } from 'pino';
-export { ConfigSource } from './common.js';
+export { ConfigSource } from './common';
 
 export interface EffectiveEntry<T> {
   canonical_name: string;
   name: string;
   value: T;
-  source: ConfigSource;
+  source: string;
 }
 
 export type Level =
@@ -47,7 +47,7 @@ export interface ConfigOption<T> {
   arg: string;
   enum?: T[];
   default?: T;
-  fn?: (arg: any) => T;
+  fn?: (arg: any, cfg: Config, source: string) => T;
   desc: string;
 }
 
@@ -56,6 +56,13 @@ export interface Config {
   _effectiveMap: Map<string, EffectiveEntry<any>>;
   _errors: Error[];
   _status: string,
+  _logs: {
+    level: import('pino').LevelWithSilentOrString;
+    obj?: any;
+    msg: string;
+    args?: any[];
+  }[];
+
 
   api: {
     /** Default: `true` */
@@ -296,10 +303,10 @@ export interface Config {
     /** Default: `true` */
     discover_cloud_resource: boolean;
   };
-  getEffectiveSource(cannonicalName: string): any;
-  getEffectiveValue(cannonicalName: string): any;
+  getEffectiveSource(cannonicalName: string): string;
+  getEffectiveValue<T = any>(cannonicalName: string): T;
   getReport({ redact: boolean }): any;
-  setValue(name: string, value: any, source: ConfigSource): void;
+  setValue<T = any>(name: string, value: T, source: string): void;
 }
 
 declare function init(core: { config?: Config }): Config;

package/lib/index.test.js

@@ -186,6 +186,49 @@ describe('config', function () {
     });
   });
 
+  describe('api.token handling', function () {
+    it('sets api config vars when they are not present', function () {
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig('token');
+      const cfg = config();
+
+      expect(cfg.api).to.include({
+        url: 'http://localhost:12345/Contrast',
+        api_key: 'secret',
+        service_key: 'secret',
+        user_name: 'tokenuser'
+      });
+    });
+
+    it('does not override api config vars when they are explicitly set in config', function () {
+      // url: 'http://localhost:12345/Contrast',
+      // api_key: 'secret',
+      // service_key: 'secret',
+      // user_name: 'tokenuser'
+      env['CONTRAST__API__TOKEN'] = 'eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjEyMzQ1L0NvbnRyYXN0IiwiYXBpX2tleSI6InNlY3JldCIsInNlcnZpY2Vfa2V5Ijoic2VjcmV0IiwidXNlcl9uYW1lIjoidG9rZW51c2VyIn0=';
+      const cfg = config();
+
+      expect(cfg.api).to.include({
+        url: 'http://localhost:19080/Contrast',
+        api_key: 'demo',
+        service_key: 'demo',
+        user_name: 'contrast_admin'
+      });
+    });
+
+    it('observes the correct precedence', function () {
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig('token');
+      env['CONTRAST__API__API_KEY'] = 'something else';
+      const cfg = config();
+
+      expect(cfg.api).to.include({
+        url: 'http://localhost:12345/Contrast',
+        api_key: 'something else',
+        service_key: 'secret',
+        user_name: 'tokenuser'
+      });
+    });
+  });
+
   describe('multiple errors can be thrown in an exception', function() {
     it('should report multiple errors', function() {
       const options = getDefaultConfig();
@@ -328,11 +371,12 @@ describe('config', function () {
       // there needs to be a valid config file or env var set so config doesn't throw
       // an error.
       process.env.CONTRAST_CONFIG_PATH = path.resolve(__dirname, '../../test/fixtures/protect_contrast_security.yaml');
+      //process.env.CONTRAST__PROTECT__RULES__DISABLED_RULES = 'cmd-injection,sql-injection';
       config = require('.')(core);
 
       config.setValue('contrast_config_path', path.resolve(__dirname, '../../test/fixtures/protect_contrast_security.yaml'), ENVIRONMENT_VARIABLE);
       config.setValue('contrast__agent__stack_trace_limit', 20, ENVIRONMENT_VARIABLE);
-      config.setValue('contrast.protect.rules.disabled_rules', ['cmd-injection', 'sql-injection'], ENVIRONMENT_VARIABLE);
+      config.setValue('protect.rules.disabled_rules', ['cmd-injection', 'sql-injection'], ENVIRONMENT_VARIABLE);
       config.setValue('api.enable', true, ENVIRONMENT_VARIABLE);
       config.setValue('api.api_key', 'ABCDEFGHIJ', ENVIRONMENT_VARIABLE);
       config.setValue('api.service_key', 'KLMNOPQRST', ENVIRONMENT_VARIABLE);
@@ -364,11 +408,12 @@ describe('config', function () {
         const {
           config: {
             effective_config,
+            environment_variable,
           }
         } = result;
 
         expect(result.config).to.have.property('status', 'Success');
-        expect(effective_config).to.deep.include(
+        const expectedResults = [
           {
             canonical_name: 'api.enable',
             name: 'api.enable',
@@ -379,13 +424,13 @@ describe('config', function () {
             canonical_name: 'api.api_key',
             name: 'api.api_key',
             source: 'ENVIRONMENT_VARIABLE',
-            value: 'contrast-redacted-api.api_key',
+            value: 'ABCDEFGHIJ',
           },
           {
             canonical_name: 'api.service_key',
             name: 'api.service_key',
             source: 'ENVIRONMENT_VARIABLE',
-            value: 'contrast-redacted-api.service_key',
+            value: 'KLMNOPQRST',
           },
           {
             canonical_name: 'api.proxy.enable',
@@ -453,7 +498,37 @@ describe('config', function () {
             value: '150',
             source: 'DEFAULT_VALUE'
           }
-        );
+        ];
+
+        const failures = [];
+        let effective;
+        let envs;
+        const envFailures = [];
+
+        for (const expected of expectedResults) {
+          effective = effective_config.filter(i => i.canonical_name === expected.canonical_name);
+          expect(effective).an('array').lengthOf(1); // eslint-disable-line
+          effective = effective[0];
+          try {
+            expect(expected).to.deep.equal(effective);
+          } catch (e) {
+            failures.push({ expected, actual: effective });
+          }
+          if (expected.source !== 'ENVIRONMENT_VARIABLE') continue;
+
+          envs = environment_variable.filter(i => i.canonical_name === expected.canonical_name);
+          expect(envs).an('array')
+            .lengthOf(1, `Expected to find ${expected.name} in environment_variable`);
+          envs = envs[0];
+          try {
+            expect(expected).to.deep.equal(envs);
+          } catch (e) {
+            envFailures.push({ expected, actual: envs });
+          }
+        }
+        // this provides a useful error message
+        expect(failures).eql([]);
+        expect(envFailures).eql([]);
       });
 
       it('stringifies values and redacts api keys when `redact` is set to true', function () {
@@ -461,11 +536,13 @@ describe('config', function () {
         const {
           config: {
             effective_config,
+            environment_variable,
           }
         } = result;
 
         expect(result.config).to.have.property('status', 'Success');
-        expect(effective_config).to.deep.include(
+
+        const expectedResults = [
           {
             canonical_name: 'api.enable',
             name: 'api.enable',
@@ -550,7 +627,37 @@ describe('config', function () {
             value: '150',
             source: 'DEFAULT_VALUE'
           }
-        );
+        ];
+
+        const failures = [];
+        let effective;
+        let envs;
+        const envFailures = [];
+
+        for (const expected of expectedResults) {
+          effective = effective_config.filter(i => i.canonical_name === expected.canonical_name);
+          expect(effective).an('array').lengthOf(1); // eslint-disable-line
+          effective = effective[0];
+          try {
+            expect(expected).to.deep.equal(effective);
+          } catch (e) {
+            failures.push({ expected, actual: effective });
+          }
+          if (expected.source !== 'ENVIRONMENT_VARIABLE') continue;
+
+          envs = environment_variable.filter(i => i.canonical_name === expected.canonical_name);
+          expect(envs).an('array')
+            .lengthOf(1, `Expected to find ${expected.name} in environment_variable`);
+          envs = envs[0];
+          try {
+            expect(expected).to.deep.equal(envs);
+          } catch (e) {
+            envFailures.push({ expected, actual: envs });
+          }
+        }
+        // this provides a useful error message
+        expect(failures).eql([]);
+        expect(envFailures).eql([]);
       });
     });
   });

package/lib/options.js

@@ -20,7 +20,8 @@
 const os = require('os');
 const url = require('url');
 const path = require('path');
-const { Rule } = require('@contrast/common');
+const { Rule, primordials: { BufferFrom, BufferPrototypeToString, StringPrototypeReplace, StringPrototypeReplaceAll, StringPrototypeSplit, StringPrototypeToLowerCase, StringPrototypeToUpperCase, JSONParse } } = require('@contrast/common');
+const { ConfigSource: { DEFAULT_VALUE } } = require('./common');
 
 /**
  * Takes strings "true"|"t" or "false"|"f" (case insensitive) and return the appropriate boolean.
@@ -32,7 +33,7 @@ function castBoolean(value) {
   if (type !== 'string' && type !== 'boolean') {
     return;
   }
-  value = value.toString().toLowerCase();
+  value = StringPrototypeToLowerCase.call(value.toString());
   return value === 'true' || value === 't'
     ? true
     : value === 'false' || value === 'f'
@@ -60,11 +61,11 @@ function clearBaseCase(val) {
 const split = (val) => {
   if (val === '') return [];
   if (val === undefined) return val;
-  return val.split(',');
+  return StringPrototypeSplit.call(val, ',');
 };
 
-const uppercase = (val = '') => clearBaseCase(`${val}`.toUpperCase());
-const lowercase = (val = '') => clearBaseCase(`${val}`.toLowerCase());
+const uppercase = (val = '') => clearBaseCase(`${StringPrototypeToUpperCase.call(val)}`);
+const lowercase = (val = '') => clearBaseCase(`${StringPrototypeToLowerCase.call(val)}`);
 const parseNum = (val) => {
   const float = parseFloat(val);
   return clearBaseCase(Math.ceil(float));
@@ -128,7 +129,7 @@ const options = [
 
       if (uri.pathname) {
         // kill trailling /
-        uri.pathname = uri.pathname.replace(/\/+$/, '');
+        uri.pathname = StringPrototypeReplace.call(uri.pathname, /\/+$/, '');
 
         if (!uri.pathname.endsWith('Contrast')) {
           uri.pathname += 'Contrast';
@@ -155,6 +156,35 @@ const options = [
     arg: '<name>',
     desc: 'Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.',
   },
+  {
+    name: 'api.token',
+    arg: '<token>',
+    desc: 'base64 encoded JSON object containing the `url`, `api_key`, `service_key`, and `user_name` config options, allowing them all to be set in a single variable.',
+    fn(value, cfg, source) {
+      try {
+        // parse the base64 encoded value
+        const parsed = JSONParse(BufferPrototypeToString.call(BufferFrom(value, 'base64'), 'utf8'));
+        // set the top level `api` keys only if they aren't already present.
+        // since this value comes after the others, they should be set first if present in the config file or environment.
+        ['url', 'api_key', 'service_key', 'user_name'].forEach(key => {
+          const canonicalName = `api.${key}`;
+          const existingSource = cfg.getEffectiveSource(canonicalName);
+          if (existingSource !== DEFAULT_VALUE) {
+            cfg._logs.push({
+              level: 'info',
+              msg: 'Using configured value for `%s` (set by %s) instead of `api.token`.',
+              args: [canonicalName, existingSource]
+            });
+          } else {
+            cfg.setValue(canonicalName, parsed[key], source);
+          }
+        });
+        return value;
+      } catch {
+        return null;
+      }
+    }
+  },
   // api.proxy
   {
     name: 'api.proxy.enable',
@@ -409,7 +439,7 @@ Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\`
     name: 'agent.node.cmd_ignore_list',
     arg: '<commands>',
     default: '',
-    fn: (arg) => arg.split(',').filter((v) => v),
+    fn: (arg) => StringPrototypeSplit.call(arg, ',').filter((v) => v),
     desc: 'comma-separated list of commands that will not startup the agent if agent is required; npm* will ignore all npm executables but not your application\'s scripts'
   },
   {
@@ -503,6 +533,29 @@ Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\`
     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: 'assess.probabilistic_sampling.enable',
+    arg: '[true]',
+    default: false,
+    fn: castBoolean,
+    desc: 'Set to true to enable sampling of requests for dataflow and other Assess features',
+  },
+  {
+    name: 'assess.probabilistic_sampling.base_probability',
+    arg: '<probability>',
+    fn: (val) => {
+      const p = parseFloat(val);
+      if (p >= 0 && p <= 1) return p;
+
+      if (val && val != 'undefined') {
+        throw new Error('Invalid option: assess.probabilistic_sampling.base_probability', {
+          cause: `${val} is not not in interval 0 <= p <= 1. value as float: ${p}`
+        });
+      }
+    },
+    default: 0.01,
+    desc: 'A value p within the interval [0, 1]. Each request will share same probability p of being sampled.',
+  },
   {
     name: 'assess.tags',
     arg: '<tags>',
@@ -512,10 +565,10 @@ Example - \`label1, label2, label3\``,
   {
     name: 'assess.stacktraces',
     arg: '<level>',
-    enum: ['ALL', 'SOME', 'NONE'],
+    enum: ['ALL', 'SOME', 'SINK', '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',
+    desc: 'Select the level of collected stacktraces. ALL - for all assess events, SOME - for Source and Sink events, SINK - for Sink events, NONE - no stacktraces collected',
   },
   {
     name: 'assess.max_context_source_events',
@@ -656,10 +709,11 @@ Example - \`label1, label2, label3\``,
     fn: castBoolean,
     desc: 'Set to `false` to disable detection of cloud provider metadata such as resource identifiers.'
   },
-].map((opt) => Object.assign(opt, {
-  env: `CONTRAST__${opt.name.toUpperCase().replaceAll('.', '__')
-    .replaceAll('-', '_')}`
-}));
+].map((opt) => {
+  let env = StringPrototypeReplaceAll.call(StringPrototypeToUpperCase.call(opt.name), '.', '__');
+  env = StringPrototypeReplaceAll.call(env, '-', '_');
+  return Object.assign(opt, { env: `CONTRAST__${env}` });
+});
 
 module.exports = options;
 module.exports.clearBaseCase = clearBaseCase;

package/lib/validators.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright: 2024 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';
+
+// Abusing the `validators` pattern to allow us to log after core has been set up.
+module.exports.config = function config(core) {
+  core.config._logs.forEach(({ level, obj, msg, args = [] }) => {
+    core.logger[level](obj, msg, ...args);
+  });
+};

package/lib/validators.test.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { expect } = require('chai');
+const mocks = require('@contrast/test/mocks');
+const validators = require('./validators');
+
+describe('config validators', function () {
+  let core;
+
+  beforeEach(function () {
+    core = { logger: mocks.logger() };
+  });
+
+  describe('config', function () {
+    it('calls `logger` for each log message provided', function () {
+      core.config = {
+        _logs: [
+          { level: 'info', msg: 'some info level message' },
+          {
+            level: 'debug',
+            obj: { foo: 'bar' },
+            msg: 'some debug level message with %d %s',
+            args: [2, 'args'],
+          },
+        ],
+      };
+
+      validators.config(core);
+
+      expect(core.logger.info).to.have.been.calledWith(
+        undefined,
+        'some info level message'
+      );
+      expect(core.logger.debug).to.have.been.calledWith(
+        { foo: 'bar' },
+        'some debug level message with %d %s',
+        2,
+        'args',
+      );
+    });
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/config",
-  "version": "1.32.0",
+  "version": "1.34.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.25.0",
+    "@contrast/common": "1.26.0",
     "yaml": "^2.2.2"
   }
 }