@contrast/config 1.28.3 → 1.30.0

package/lib/index.d.ts

@@ -17,10 +17,10 @@ import { ProtectRuleMode, Rule } from '@contrast/common';
 import { LevelWithSilent } from 'pino';
 export { ConfigSource } from './common.js';
 
-export interface EffectiveEntry {
+export interface EffectiveEntry<T> {
   canonical_name: string;
   name: string;
-  value: any;
+  value: T;
   source: ConfigSource;
 }
 
@@ -53,7 +53,7 @@ export interface ConfigOption<T> {
 
 export interface Config {
   _filepath: string;
-  _effectiveMap: Map<EffectiveEntry>;
+  _effectiveMap: Map<string, EffectiveEntry<any>>;
   _errors: Error[];
   _status: string,
 
@@ -213,6 +213,7 @@ export interface Config {
   inventory: {
     /** Default: `true` */
     analyze_libraries: boolean;
+    gather_metadata_via: 'AWS' | 'Azure' | 'GCP' | undefined;
   };
 
   assess: {
@@ -292,6 +293,8 @@ export interface Config {
     environment?: string;
     tags?: string;
     version?: string;
+    /** Default: `true` */
+    discover_cloud_resource: boolean;
   };
   getEffectiveSource(cannonicalName: string): any;
   getEffectiveValue(cannonicalName: string): any;

package/lib/index.test.js

@@ -0,0 +1,557 @@
+'use strict';
+
+const EventEmitter = require('events');
+const path = require('path');
+const proxyquire = require('proxyquire');
+const sinon = require('sinon');
+const { expect } = require('chai');
+const { Event } = require('@contrast/common');
+const options = require('./options');
+const {
+  ConfigSource: { ENVIRONMENT_VARIABLE }
+} = require('./common');
+const {
+  getGoodConfig,
+  getBadConfig,
+  getAbsolutePath,
+  getDefaultConfig,
+  getProperties,
+  containsAllProps,
+} = require('../test/helpers');
+
+describe('config', function () {
+  let env, Config, config;
+
+  beforeEach(function () {
+    env = {
+      ProgramData: 'C:\\ProgramData',
+      CONTRAST_CONFIG_PATH: getGoodConfig(),
+    };
+    Config = proxyquire('./config', {
+      process: { env },
+    });
+    config = proxyquire('.', {
+      process: { env },
+      './config': Config,
+    });
+
+    sinon.stub(console, 'error');
+  });
+
+  describe('default config behavior', function () {
+    it('sets all default properties in the config', function () {
+      const defaultConfigProps = getProperties(getDefaultConfig());
+      const loadConfigProps = getProperties(config());
+      expect(containsAllProps(loadConfigProps, defaultConfigProps)).to.be.true;
+    });
+
+    it('logs an error a config file path is given and no config is found', function () {
+      env['CONTRAST_CONFIG_PATH'] = 'fake config';
+      const fn = () => config();
+      expect(fn).to.throw('1) Unable to read Contrast configuration file: \'fake config\'');
+    });
+
+    it('logs an error when the config cannot be parsed', function () {
+      env['CONTRAST_CONFIG_PATH'] = getBadConfig();
+      const fn = () => config();
+      expect(fn).to.throw(`Contrast configuration file is malformed: '${getBadConfig()}'`);
+    });
+
+    it('accepts overrides from env', function () {
+      env['CONTRAST__API__API_KEY'] = 'demo';
+      const cfg = config();
+      expect(cfg.api.api_key).to.equal('demo');
+    });
+
+    it('loads and sets properties from a valid config', function () {
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig();
+      const cfg = config();
+      expect(console.error).not.to.have.been.called;
+      expect(cfg.api.enable).to.be.true;
+      expect(cfg.api.url).to.equal('http://localhost:19080/Contrast');
+      expect(cfg.api.api_key).to.equal('demo');
+      expect(cfg.api.service_key).to.equal('demo');
+      expect(cfg.api.user_name).to.equal('contrast_admin');
+    });
+  });
+
+  describe('config file path precedence', function () {
+    it('should set config from environment variable even when default is present', function () {
+      sinon.stub(Config.prototype, '_configDirs').returns([
+        path.dirname(getGoodConfig())
+      ]);
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig('two');
+      const cfg = config();
+      expect(cfg).to.have.property('_filepath', getGoodConfig('two'));
+      expect(cfg.api.url).to.equal('https://localhost:9999/Contrast');
+      expect(cfg.api.api_key).to.equal('QWERTYUIOP');
+      expect(cfg.api.service_key).to.equal('ASDFGHJKL');
+      expect(cfg.api.user_name).to.equal('contrast_user');
+    });
+
+    it('should set config from default location when no env var is set', function () {
+      sinon.stub(Config.prototype, '_configDirs').returns([
+        path.dirname(getGoodConfig())
+      ]);
+      delete env['CONTRAST_CONFIG_PATH'];
+      const cfg = config();
+      expect(cfg).to.have.property('_filepath', getGoodConfig());
+      expect(cfg.api.url).to.equal('http://localhost:19080/Contrast');
+      expect(cfg.api.api_key).to.equal('demo');
+      expect(cfg.api.service_key).to.equal('demo');
+      expect(cfg.api.user_name).to.equal('contrast_admin');
+    });
+
+    it('should set config from top valid default location', function () {
+      sinon.stub(Config.prototype, '_configDirs').returns([
+        path.dirname(getGoodConfig('two')),
+        path.dirname(getGoodConfig()),
+      ]);
+      delete env['CONTRAST_CONFIG_PATH'];
+      const cfg = config();
+      expect(cfg).to.have.property('_filepath', getGoodConfig('two'));
+      expect(cfg.api.url).to.equal('https://localhost:9999/Contrast');
+      expect(cfg.api.api_key).to.equal('QWERTYUIOP');
+      expect(cfg.api.service_key).to.equal('ASDFGHJKL');
+      expect(cfg.api.user_name).to.equal('contrast_user');
+    });
+
+    it('should set from env variable even when present in multiple defaults', function () {
+      sinon.stub(Config.prototype, '_configDirs').returns([
+        path.dirname(getGoodConfig('two')),
+        path.dirname(getGoodConfig()),
+      ]);
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig('three');
+      const cfg = config();
+      expect(cfg).to.have.property('_filepath', getGoodConfig('three'));
+      expect(cfg.api.url).to.equal('https://localhost:8080/Contrast');
+      expect(cfg.api.api_key).to.equal('QAZWSX');
+      expect(cfg.api.service_key).to.equal('EDCRFV');
+      expect(cfg.api.user_name).to.equal('super_admin');
+    });
+  });
+
+  describe('config value precedence', function () {
+    let options;
+
+    beforeEach(function () {
+      options = getDefaultConfig();
+    });
+
+    it('should use env var before config file value', function () {
+      env['CONTRAST__API__API_KEY'] = 'NOPE';
+      const cfg = config(options);
+      expect(cfg.api.api_key).to.equal('NOPE');
+    });
+  });
+
+  describe('environment variables', function () {
+    it('should support CONTRAST__ options', function () {
+      const options = getDefaultConfig();
+      env['CONTRAST__AGENT__NODE__REWRITE__ENABLE'] = 'f';
+      const cfg = config(options);
+
+      expect(cfg.agent.node.rewrite.enable).to.be.false;
+    });
+
+    it('Should support CONTRAST__API__ options', function () {
+      const options = getDefaultConfig();
+      env['CONTRAST__API__API_KEY'] = 'abcdefg';
+      const cfg = config(options);
+
+      expect(cfg.api.api_key).to.equal('abcdefg');
+    });
+
+    it('should merge pm2 env variables', function () {
+      const options = getDefaultConfig();
+      const variables = {
+        CONTRAST_CONFIG_PATH: '/path/to/config',
+        CONTRAST__API__API_KEY: 'abcdefg',
+        env: {
+          CONTRAST_CONFIG_PATH: '/other/path/to/config'
+        }
+      };
+      delete env['CONTRAST_CONFIG_PATH'];
+      env['pm2_env'] = JSON.stringify(variables);
+
+      const fn = () => config(options);
+      expect(fn).throws('1) Unable to read Contrast configuration file: \'/other/path/to/config\'');
+    });
+
+    it('should throw an error if pm2_env is invalid', function () {
+      env['pm2_env'] = '{CONTRAST_';
+
+      const fn = () => config(options);
+      expect(fn).to.throw('1) Unable to parse pm2 environment variable: \'{CONTRAST_\'');
+    });
+  });
+
+  describe('multiple errors can be thrown in an exception', function() {
+    it('should report multiple errors', function() {
+      const options = getDefaultConfig();
+      env['pm2_env'] = '{CONTRAST_';
+      env['CONTRAST__APPLICATION__SESSION_ID'] = 'abcd-1234';
+      env['CONTRAST__APPLICATION__SESSION_METADATA'] = 'a=1,b=2';
+      env['CONTRAST_CONFIG_PATH'] = getGoodConfig('three');
+
+      const fn = () => config(options);
+      expect(fn).throws(/1\) Unable to parse pm2 .+ 2\) Cannot set both/);
+    });
+  });
+
+  describe('config options functions', function () {
+    describe('clearBaseCase', function () {
+      it('should return string if defined', function () {
+        const string = 'asdf';
+        expect(options.clearBaseCase(string)).to.equal(string);
+      });
+
+      it('should return undefined if string is empty', function () {
+        const string = '';
+        expect(options.clearBaseCase(string)).to.be.undefined;
+      });
+
+      it('should return int if and number and defined', function () {
+        const num = 1;
+        expect(options.clearBaseCase(num)).to.equal(num);
+      });
+
+      it('should return undefined if value is NaN', function () {
+        const num = NaN;
+        expect(options.clearBaseCase(num)).to.be.undefined;
+      });
+    });
+
+    describe('castBoolean', function () {
+      [true, 'true', 'TRUE', 't', 'T'].forEach(val => {
+        it(`should return true if string value is ${val}`, function () {
+          expect(options.castBoolean(val)).to.be.true;
+        });
+      });
+
+      [false, 'false', 'FALSE', 'f', 'F'].forEach(val => {
+        it(`should return false if string value is ${val}`, function () {
+          expect(options.castBoolean(val)).to.be.false;
+        });
+      });
+
+      ['rando', [1, 2, 3], {}, 100, null, undefined].forEach(val => {
+        it(`should return undefined if ${val} not a boolean or string or not true/t/false/f`, function () {
+          expect(options.castBoolean(val)).to.be.undefined;
+        });
+      });
+    });
+  });
+
+  describe('enum', function () {
+    it('should use value from enum if there is a match', function () {
+      env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'INFO';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.equal('info');
+    });
+
+    it('should fall back to the default when provided option value is invalid', function () {
+      env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'doggo';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.equal('info');
+    });
+  });
+
+  describe('uppercase, lowercase, parsenum transformations', function () {
+    it('should uppercase server.environment', function () {
+      env['CONTRAST__SERVER__ENVIRONMENT'] = 'qa';
+      const cfg = config();
+      expect(cfg.server.environment).to.equal('QA');
+    });
+
+    it('should lowercase logger level', function () {
+      env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'DEBUG';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.equal('debug');
+    });
+
+    it('should parse stack_trace_limit into a number', function () {
+      env['CONTRAST__AGENT__STACK_TRACE_LIMIT'] = '25';
+      const cfg = config();
+      expect(cfg.agent.stack_trace_limit).to.equal(25);
+    });
+
+    it('agent.stack_trace_limit (Infinity string --> number)', function () {
+      env['CONTRAST__AGENT__STACK_TRACE_LIMIT'] = 'Infinity';
+      const cfg = config();
+      expect(cfg.agent.stack_trace_limit).to.equal(Infinity);
+    });
+  });
+
+  describe('application', function () {
+    describe('validation', function () {
+      afterEach(function () {
+      });
+      it('allows one to be set without error', function () {
+        env['CONTRAST__APPLICATION__SESSION_ID'] = 'abcd-1234';
+        expect(() => {
+          config();
+        }).not.to.throw(/Configuration Error:/);
+      });
+      it('session options are mutually exclusive', function () {
+        env['CONTRAST__APPLICATION__SESSION_ID'] = 'abcd-1234';
+        env['CONTRAST__APPLICATION__SESSION_METADATA'] = 'a=1,b=2';
+        const fn = () => config();
+        expect(fn).throws('1) Cannot set both `application.session_id` and `application.session_metadata`');
+      });
+    });
+  });
+
+  describe('mapping', function () {
+    describe('logger', function () {
+      it('casts logger path to absolute path', function () {
+        env['CONTRAST__AGENT__LOGGER__PATH'] = 'loggy.log';
+        const cfg = config();
+        expect(cfg.agent.logger.path).to.equal(getAbsolutePath('loggy.log'));
+      });
+
+      it('--debug does not overwrite explicitly set log level', function () {
+        env['DEBUG'] = 'true';
+        env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'info';
+        const cfg = config();
+        expect(cfg.agent.logger.level).to.equal('info');
+      });
+    });
+  });
+
+  describe('effective configuration', function () {
+    let core;
+    let config;
+
+    beforeEach(function () {
+      core = { messages: new EventEmitter() };
+      // 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');
+      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('api.enable', true, ENVIRONMENT_VARIABLE);
+      config.setValue('api.api_key', 'ABCDEFGHIJ', ENVIRONMENT_VARIABLE);
+      config.setValue('api.service_key', 'KLMNOPQRST', ENVIRONMENT_VARIABLE);
+
+      core.messages.emit(Event.SERVER_SETTINGS_UPDATE, {
+        logger: {
+          // this will not take effect b/c value is set in config file
+          level: 'ERROR'
+        },
+        security_logger: {
+          syslog: {
+            enable: true,
+            ip: '127.0.0.1'
+          }
+        }
+      });
+    });
+
+    describe('.getEffectiveValue()', function () {
+      it('returns the resolved value based on precedence: env > file > UI > default', function () {
+        expect(config.getEffectiveValue('agent.security_logger.syslog.enable')).to.equal(true);
+      });
+    });
+
+    describe('.getReport', function () {
+      it('merges all the settings correctly and returns properly formatted config object', function () {
+
+        const result = config.getReport({ redact: false });
+        const {
+          config: {
+            effective_config,
+          }
+        } = result;
+
+        expect(result.config).to.have.property('status', 'Success');
+        expect(effective_config).to.deep.include(
+          {
+            canonical_name: 'api.enable',
+            name: 'api.enable',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'true',
+          },
+          {
+            canonical_name: 'api.api_key',
+            name: 'api.api_key',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'contrast-redacted-api.api_key',
+          },
+          {
+            canonical_name: 'api.service_key',
+            name: 'api.service_key',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'contrast-redacted-api.service_key',
+          },
+          {
+            canonical_name: 'api.proxy.enable',
+            name: 'api.proxy.enable',
+            source: 'USER_CONFIGURATION_FILE',
+            value: 'false',
+          },
+          {
+            canonical_name: 'agent.diagnostics.enable',
+            name: 'agent.diagnostics.enable',
+            source: 'USER_CONFIGURATION_FILE',
+            value: 'false',
+          },
+          {
+            canonical_name: 'protect.enable',
+            name: 'protect.enable',
+            value: 'true',
+            source: 'USER_CONFIGURATION_FILE'
+          },
+          {
+            canonical_name: 'assess.enable',
+            name: 'assess.enable',
+            value: 'false',
+            source: 'USER_CONFIGURATION_FILE'
+          },
+          {
+            canonical_name: 'agent.security_logger.syslog.enable',
+            name: 'agent.security_logger.syslog.enable',
+            value: 'true',
+            source: 'CONTRAST_UI'
+          },
+          {
+            canonical_name: 'agent.polling.app_activity_ms',
+            name: 'agent.polling.app_activity_ms',
+            value: '30000',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'protect.rules.disabled_rules',
+            name: 'protect.rules.disabled_rules',
+            value: 'cmd-injection,sql-injection',
+            source: 'ENVIRONMENT_VARIABLE',
+          },
+          {
+            canonical_name: 'protect.probe_analysis.enable',
+            name: 'protect.probe_analysis.enable',
+            value: 'true',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.trust_custom_validators',
+            name: 'assess.trust_custom_validators',
+            value: 'false',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.max_propagation_events',
+            name: 'assess.max_propagation_events',
+            value: '500',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.max_context_source_events',
+            name: 'assess.max_context_source_events',
+            value: '150',
+            source: 'DEFAULT_VALUE'
+          }
+        );
+      });
+
+      it('stringifies values and redacts api keys when `redact` is set to true', function () {
+        const result = config.getReport({ redact: true });
+        const {
+          config: {
+            effective_config,
+          }
+        } = result;
+
+        expect(result.config).to.have.property('status', 'Success');
+        expect(effective_config).to.deep.include(
+          {
+            canonical_name: 'api.enable',
+            name: 'api.enable',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'true',
+          },
+          {
+            canonical_name: 'api.api_key',
+            name: 'api.api_key',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'contrast-redacted-api.api_key',
+          },
+          {
+            canonical_name: 'api.service_key',
+            name: 'api.service_key',
+            source: 'ENVIRONMENT_VARIABLE',
+            value: 'contrast-redacted-api.service_key',
+          },
+          {
+            canonical_name: 'api.proxy.enable',
+            name: 'api.proxy.enable',
+            source: 'USER_CONFIGURATION_FILE',
+            value: 'false',
+          },
+          {
+            canonical_name: 'agent.diagnostics.enable',
+            name: 'agent.diagnostics.enable',
+            source: 'USER_CONFIGURATION_FILE',
+            value: 'false',
+          },
+          {
+            canonical_name: 'protect.enable',
+            name: 'protect.enable',
+            value: 'true',
+            source: 'USER_CONFIGURATION_FILE'
+          },
+          {
+            canonical_name: 'assess.enable',
+            name: 'assess.enable',
+            value: 'false',
+            source: 'USER_CONFIGURATION_FILE'
+          },
+          {
+            canonical_name: 'agent.security_logger.syslog.enable',
+            name: 'agent.security_logger.syslog.enable',
+            value: 'true',
+            source: 'CONTRAST_UI'
+          },
+          {
+            canonical_name: 'agent.polling.app_activity_ms',
+            name: 'agent.polling.app_activity_ms',
+            value: '30000',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'protect.rules.disabled_rules',
+            name: 'protect.rules.disabled_rules',
+            value: 'cmd-injection,sql-injection',
+            source: 'ENVIRONMENT_VARIABLE',
+          },
+          {
+            canonical_name: 'protect.probe_analysis.enable',
+            name: 'protect.probe_analysis.enable',
+            value: 'true',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.trust_custom_validators',
+            name: 'assess.trust_custom_validators',
+            value: 'false',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.max_propagation_events',
+            name: 'assess.max_propagation_events',
+            value: '500',
+            source: 'DEFAULT_VALUE'
+          },
+          {
+            canonical_name: 'assess.max_context_source_events',
+            name: 'assess.max_context_source_events',
+            value: '150',
+            source: 'DEFAULT_VALUE'
+          }
+        );
+      });
+    });
+  });
+});

package/lib/options.js

@@ -495,6 +495,12 @@ Example - \`/opt/Contrast/contrast.log\` creates a log in the \`/opt/Contrast\`
     fn: castBoolean,
     desc: 'Set to `false` to disable library analysis.',
   },
+  {
+    name: 'inventory.gather_metadata_via',
+    arg: '<provider>',
+    enum: ['AWS', 'Azure', 'GCP'],
+    desc: 'Specifies the cloud provider from which the agent should gather metadata (such as resource identifiers). Options are `AWS`, `Azure`, or `GCP`'
+  },
   // assess
   {
     name: 'assess.enable',
@@ -613,7 +619,7 @@ Example - \`label1, label2, label3\``,
   },
   {
     name: 'application.metadata',
-    args: '<metadata>',
+    arg: '<metadata>',
     desc: 'comma-separated list of key=value pairs that are applied to each application reported by the agent.',
   },
   // server
@@ -649,6 +655,13 @@ Example - \`label1, label2, label3\``,
     arg: '<version>',
     desc: "override the reported server version (if different from 'version' field in the application's package.json)",
   },
+  {
+    name: 'server.discover_cloud_resource',
+    arg: '[false]',
+    default: true,
+    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('-', '_')}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/config",
-  "version": "1.28.3",
+  "version": "1.30.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.21.3",
+    "@contrast/common": "1.23.0",
     "yaml": "^2.2.2"
   }
 }