@contrast/config 1.0.0

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright: 2022 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.

package/README.md

@@ -0,0 +1,44 @@
+# `@contrast/config`
+
+<br>
+
+> Note: This package needs help.
+>  * Needlessly dependent on `commander`, `lodash`, and `json-stable-stringify`
+>  * Can be simplified
+>  * Could benefit from schema-based approach for defaults
+
+<br>
+
+## Overview
+
+This is legacy code ported from `node-agent` repo.
+
+To discover and log configuration data, try
+
+```shell
+node -e "console.log(new (require('.').Config)())"
+```
+
+## Usage
+
+An agent should use a single instance of a config. On instantiation, the config will detect both yaml file and environment variable sources and build out full config object. The object will have defaults set for values not having been set by file or env vars.
+
+```typescript
+const { AgentConfig } = require('@contrast/config');
+const config = new AgentConfig();
+
+// do stuff with config
+if (config.protect.enable) {
+
+}
+```
+
+## New V5 Options
+
+ - `agent.stack_trace_filters`
+
+   This allows agent stackframes to be filtered via configuration
+   Default: `agent-,@contrast,node-agent`
+
+
+

package/lib/index.d.ts

@@ -0,0 +1,122 @@
+import { RulesConfig } from '@contrast/common';
+import { Level } from 'pino';
+
+export interface Config {
+  configFile: string;
+
+  api: {
+    enable: boolean;
+    api_key: string;
+    service_key: string;
+
+    /** Default: `'https://app.contrastsecurity.com/Contrast'` */
+    url: string;
+
+    user_name: string;
+    proxy: {
+      enable: boolean;
+      url: string;
+    }
+  };
+
+  agent: {
+    polling: {
+      app_activity_ms: number;
+    },
+    reporters: {
+      /** Path indicating where to report all agent findings. */
+      file?: string | number;
+    };
+
+    logger: {
+      /**
+       * When false, create a new log file on startup instead of appending and
+       * rolling daily. Default: `true`
+       */
+      append: boolean;
+
+      /**
+       * Minimum log level. 'silent' disables logging entirely.
+       * Default: `'error'`
+       */
+      level: Level | 'silent';
+
+      /** Default: `'node-contrast'` */
+      path: string;
+
+      /** Suppress output when `false`. Default: `true` */
+      stdout: boolean;
+    };
+
+    node: {
+      /** Default: `true` */
+      enable_rewrite: boolean;
+
+      /** Default: `true` */
+      enable_source_maps: boolean;
+
+      /** Location to look for the app's package.json. Default: `process.cwd()` */
+      app_root: string;
+    };
+
+    /**
+     * 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[];
+  };
+
+  application: {
+    /** override the reported application name. */
+    name?: string;
+
+    /** override the reported application path. Default: `'/'` */
+    path: string;
+
+    /**
+     * Override the reported application version (if different from 'version'
+     * field in the application's package.json).
+     */
+    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_metadtata: string | null;
+  };
+
+  protect: {
+    enable: boolean;
+
+    /**
+     * List of rule ids to disable.
+     * Default: `[]`
+     */
+    disabled_rules: string[];
+
+    rules: RulesConfig;
+  };
+
+  /** Reported server information overrides */
+  server: {
+    environment?: string;
+    /** Default: `os.hostname()` */
+    name: string;
+    version?: string;
+  };
+}
+
+interface Core {
+  config: Config;
+}
+
+declare function init(core: Core): Config;
+
+export = init;

package/lib/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const configUtil = require('./util');
+
+module.exports = function init(core = {}) {
+  return core.config = configUtil.setup();
+};

package/lib/index.test.js

@@ -0,0 +1,331 @@
+'use strict';
+
+const sinon = require('sinon');
+const mockfs = require('mock-fs');
+const { expect } = require('chai');
+const config = require('.');
+const configOptions = require('./options');
+const mocks = require('../../test/mocks');
+const AppInfo = require('../../core/lib/app-info');
+
+const {
+  getGoodConfig,
+  getBadConfig,
+  getAbsolutePath,
+  getDefaultConfig,
+  getProperties,
+  containsAllProps,
+} = require('../test/helpers');
+
+describe('config', function () {
+  beforeEach(function () {
+
+    // removing as some agent engineers have this env var set
+    delete process.env['CONTRAST_CONFIG_PATH'];
+    sinon.stub(console, 'error');
+  });
+
+  afterEach(function () {
+    mockfs.restore();
+  });
+
+  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 () {
+      process.env['CONTRAST_CONFIG_PATH'] = 'fake config';
+      config();
+      expect(console.error).to.have.been.calledWith(
+        'Unable to read config file at %s: %s',
+        'fake config',
+        sinon.match('ENOENT'),
+      );
+      delete process.env['CONTRAST_CONFIG_PATH'];
+    });
+
+    it('logs an error when the config cannot be parsed', function () {
+      mockfs({
+        'contrast_security.yaml': mockfs.load(getBadConfig()),
+      });
+      config();
+      expect(console.error).to.have.been.calledWith(
+        'YAML validator found an error in %s: %s',
+        sinon.match(/contrast_security.yaml$/),
+        sinon.match(/^Tabs are not allowed as indentation/),
+      );
+    });
+
+    it('accepts overrides from env', function () {
+      process.env['CONTRAST__API__API_KEY'] = 'demo';
+      const cfg = config();
+      expect(cfg.api.api_key).to.be.equal('demo');
+      delete process.env['CONTRAST__API__API_KEY'];
+    });
+
+    it('loads and sets properties from a valid config', function () {
+      mockfs({
+        'contrast_security.yaml': mockfs.load(getGoodConfig()),
+      });
+      const cfg = config();
+      expect(console.error).to.not.have.been.called;
+      expect(cfg.api.enable).to.be.true;
+      expect(cfg.api.url).to.be.equal('http://localhost:19080/Contrast');
+      expect(cfg.api.api_key).to.be.equal('demo');
+      expect(cfg.api.service_key).to.be.equal('demo');
+      expect(cfg.api.user_name).to.be.equal('contrast_admin');
+    });
+  });
+
+  describe('config file path precedence', function () {
+    it('should set config from environment variable even with one in cwd', function () {
+      mockfs({
+        'contrast_security.yaml': mockfs.load(getGoodConfig()),
+        '/otherDir/config/contrast_security.yaml': mockfs.load(
+          getGoodConfig('2')
+        ),
+      });
+      process.env['CONTRAST_CONFIG_PATH'] =
+        '/otherDir/config/contrast_security.yaml';
+      const cfg = config();
+      expect(cfg.api.url).to.be.equal('https://localhost:9999/Contrast');
+      expect(cfg.api.api_key).to.be.equal('QWERTYUIOP');
+      expect(cfg.api.service_key).to.be.equal('ASDFGHJKL');
+      expect(cfg.api.user_name).to.be.equal('contrast_user');
+      delete process.env['CONTRAST_CONFIG_PATH'];
+    });
+
+    it('should set config from etc/contrast if envVar not set and no config in cwd', function () {
+      mockfs({
+        '/etc/contrast/contrast_security.yaml': mockfs.load(getGoodConfig()),
+      });
+      const cfg = config();
+      expect(cfg.api.url).to.be.equal('http://localhost:19080/Contrast');
+      expect(cfg.api.api_key).to.be.equal('demo');
+      expect(cfg.api.service_key).to.be.equal('demo');
+      expect(cfg.api.user_name).to.be.equal('contrast_admin');
+    });
+
+    it('should set config from cwd even when present in etc/contrast', function () {
+      mockfs({
+        '/etc/contrast/contrast_security.yaml': mockfs.load(getGoodConfig()),
+        'contrast_security.yaml': mockfs.load(getGoodConfig('2')),
+      });
+      const cfg = config();
+      expect(cfg.api.url).to.be.equal('https://localhost:9999/Contrast');
+      expect(cfg.api.api_key).to.be.equal('QWERTYUIOP');
+      expect(cfg.api.service_key).to.be.equal('ASDFGHJKL');
+      expect(cfg.api.user_name).to.be.equal('contrast_user');
+    });
+
+    it('should set from env variable even when present in cwd and etc/contrast', function () {
+      mockfs({
+        '/etc/contrast/contrast_security.yaml': mockfs.load(getGoodConfig()),
+        'contrast_security.yaml': mockfs.load(getGoodConfig('2')),
+        '/otherDir/config/contrast_security.yaml': mockfs.load(
+          getGoodConfig('3')
+        ),
+      });
+      process.env['CONTRAST_CONFIG_PATH'] =
+        '/otherDir/config/contrast_security.yaml';
+      const cfg = config();
+      expect(cfg.api.url).to.be.equal('https://localhost:8080/Contrast');
+      expect(cfg.api.api_key).to.be.equal('QAZWSX');
+      expect(cfg.api.service_key).to.be.equal('EDCRFV');
+      expect(cfg.api.user_name).to.be.equal('super_admin');
+      delete process.env['CONTRAST_CONFIG_PATH'];
+    });
+  });
+
+  describe('config value precedence', function () {
+    let options;
+
+    beforeEach(function () {
+      options = getDefaultConfig();
+      delete process.env.CONTRAST__API__API_KEY;
+    });
+
+    it('should use env var before config file value', function () {
+      process.env.CONTRAST__API__API_KEY = 'NOPE';
+      const cfg = config(options);
+      expect(cfg.api.api_key).to.be.equal('NOPE');
+    });
+  });
+
+  describe('environment variables', function () {
+    it('should support CONTRAST__ options', function () {
+      const options = getDefaultConfig();
+      process.env['CONTRAST__AGENT__NODE__ENABLE_REWRITE'] = 'f';
+      const cfg = config(options);
+
+      expect(cfg.agent.node.enable_rewrite).to.be.equal(false);
+      delete process.env['CONTRAST__AGENT__NODE__ENABLE_REWRITE'];
+    });
+    it('Should support CONTRAST__API__ options', function () {
+      const options = getDefaultConfig();
+      process.env['CONTRAST__API__API_KEY'] = 'abcdefg';
+      const cfg = config(options);
+
+      expect(cfg.api.api_key).to.equal('abcdefg');
+      delete process.env['CONTRAST__API__API_KEY'];
+    });
+  });
+
+  describe('config options functions', function () {
+    describe('clearBaseCase', function () {
+      it('should return string if defined', function () {
+        const string = 'asdf';
+        expect(configOptions.clearBaseCase(string)).to.equal(string);
+      });
+
+      it('should return undefined if string is empty', function () {
+        const string = '';
+        expect(configOptions.clearBaseCase(string)).to.be.undefined;
+      });
+
+      it('should return int if and number and defined', function () {
+        const num = 1;
+        expect(configOptions.clearBaseCase(num)).to.equal(num);
+      });
+
+      it('should return undefined if value is NaN', function () {
+        const num = NaN;
+        expect(configOptions.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(configOptions.castBoolean(val)).to.equal(true);
+        });
+      });
+
+      [false, 'false', 'FALSE', 'f', 'F'].forEach(val => {
+        it(`should return false if string value is ${val}`, function () {
+          expect(configOptions.castBoolean(val)).to.equal(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(configOptions.castBoolean(val)).to.equal(undefined);
+        });
+      });
+    });
+  });
+
+  describe('enum', function () {
+    let logger_level;
+
+    beforeEach(function () {
+      logger_level = 'CONTRAST__AGENT__LOGGER__LEVEL';
+    });
+
+    afterEach(function () {
+      delete process.env[logger_level];
+    });
+
+    it('should use value from enum if there is a match', function () {
+      process.env[logger_level] = 'info';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.be.equal('info');
+    });
+
+    it('should use default when there is no match within enum', function () {
+      process.env[logger_level] = 'doggo';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.be.equal('error');
+    });
+  });
+
+  describe('uppercase, lowercase, parsenum transformations', function () {
+    it('should uppercase server.environment', function () {
+      process.env['CONTRAST__SERVER__ENVIRONMENT'] = 'qa';
+      const cfg = config();
+      expect(cfg.server.environment).to.equal('QA');
+      delete process.env['CONTRAST__SERVER__ENVIRONMENT'];
+    });
+
+    it('should lowercase logger level', function () {
+      process.env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'DEBUG';
+      const cfg = config();
+      expect(cfg.agent.logger.level).to.equal('debug');
+      delete process.env['CONTRAST__AGENT__LOGGER__LEVEL'];
+    });
+
+    it('should parse stack_trace_limit into a number', function () {
+      process.env['CONTRAST__AGENT__STACK_TRACE_LIMIT'] = '25';
+      const cfg = config();
+      expect(cfg.agent.stack_trace_limit).to.equal(25);
+      delete process.env['CONTRAST__AGENT__STACK_TRACE_LIMIT'];
+    });
+
+    it('agent.stack_trace_limit (Infinity string --> number)', function () {
+      process.env['CONTRAST__AGENT__STACK_TRACE_LIMIT'] = 'Infinity';
+      const cfg = config();
+      expect(cfg.agent.stack_trace_limit).to.be.equal(Infinity);
+      delete process.env['CONTRAST__AGENT__STACK_TRACE_LIMIT'];
+    });
+  });
+
+  describe('application', function () {
+    describe('validation', function () {
+      afterEach(function () {
+        delete process.env['CONTRAST__APPLICATION__SESSION_ID'];
+        delete process.env['CONTRAST__APPLICATION__SESSION_METADATA'];
+      });
+      it('allows one to be set without error', function () {
+        process.env['CONTRAST__APPLICATION__SESSION_ID'] = 'abcd-1234';
+        expect(() => {
+          config();
+        }).to.not.throw(/Configuration Error:/);
+      });
+      it('session options are mutually exclusive', function () {
+        process.env['CONTRAST__APPLICATION__SESSION_ID'] = 'abcd-1234';
+        process.env['CONTRAST__APPLICATION__SESSION_METADATA'] = 'a=1,b=2';
+        expect(() => {
+          config();
+        }).to.throw(/Configuration Error:/);
+      });
+    });
+  });
+
+  describe('server', function () {
+    describe('environment', function () {
+      it('set from env var', function () {
+        const env = Date.now();
+        const options = getDefaultConfig();
+        process.env.SERVER__ENVIRONMENT = env;
+
+        const cfg = config(options);
+        const ai = new AppInfo({ appInfo: 'asdf', config: cfg, logger: mocks.logger() });
+        expect(ai.serverEnvironment).to.be.equal(String(env));
+      });
+    });
+  });
+
+  describe('mapping', function () {
+    describe('logger', function () {
+      it('casts logger path to absolute path', function () {
+        process.env['CONTRAST__AGENT__LOGGER__PATH'] = 'loggy.log';
+        const cfg = config();
+        expect(cfg.agent.logger.path).to.be.equal(getAbsolutePath('loggy.log'));
+        delete process.env['CONTRAST__AGENT__LOGGER__PATH'];
+      });
+
+      it('--debug does not overwrite explicitly set log level', function () {
+        process.env['DEBUG'] = 'true';
+        process.env['CONTRAST__AGENT__LOGGER__LEVEL'] = 'info';
+
+        const cfg = config();
+        expect(cfg.agent.logger.level).to.be.equal('info');
+        delete process.env['DEBUG'];
+        delete process.env['CONTRAST__AGENT__LOGGER__LEVEL'];
+      });
+    });
+  });
+});

package/lib/options.js

@@ -0,0 +1,335 @@
+/**
+ * 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
+ */
+
+'use strict';
+
+const os = require('os');
+const url = require('url');
+const path = require('path');
+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}
+ */
+function castBoolean(value) {
+  const type = typeof value;
+  if (type !== 'string' && type !== 'boolean') {
+    return;
+  }
+  value = value.toString().toLowerCase();
+  return (value === 'true' || value === 't')
+    ? true
+    : (value === 'false' || value === 'f')
+        ? false
+        : undefined;
+}
+
+/**
+ * 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()
+ */
+function toAbsolutePath(value) {
+  return value ? path.resolve(process.cwd(), String(value)) : undefined;
+}
+
+function clearBaseCase(val) {
+  const type = typeof val;
+  return (type === 'string' && val === '') || (type === 'number' && isNaN(val))
+    ? undefined
+    : val;
+}
+
+const split = (val) => {
+  if (val === '') return [];
+  if (val === undefined) return val;
+  return val.split(',');
+};
+
+const uppercase = (val = '') => clearBaseCase(`${val}`.toUpperCase());
+const lowercase = (val = '') => clearBaseCase(`${val}`.toLowerCase());
+const parseNum = (val) => {
+  const float = parseFloat(val);
+  return clearBaseCase(Math.ceil(float));
+};
+
+const config = [
+  {
+    name: 'configFile',
+    abbrev: 'c',
+    // special case this guy because it should be settable via ENV
+    env: 'CONTRAST_CONFIG_PATH',
+    arg: '<path>',
+    desc:
+      'set config file location. defaults to <app_root>/contrast_security.yaml'
+  }
+];
+
+const 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'
+  },
+  {
+    name: 'api.url',
+    env: 'CONTRASTSECURITY_URL',
+    arg: '<url>',
+    default: 'https://app.contrastsecurity.com/Contrast',
+    // The old json spec used to expect that the url would not end in /Contrast
+    // Common config expects this to be there. So, we need to do a bit of massaging
+    // to make sure our reporter gets a consistent URL one way or the other.
+    fn: (value) => {
+      if (value === undefined) {
+        return;
+      }
+
+      value = String(value);
+      let uri;
+      try {
+        uri = new url.URL(value);
+      } catch (e) {
+        // the url customer provided is invalid, return null and this will eventually
+        // fail when trying to talk to TS
+        return null;
+      }
+
+      if (uri.pathname) {
+        // kill trailling /
+        uri.pathname = uri.pathname.replace(/\/+$/, '');
+
+        if (!uri.pathname.endsWith('Contrast')) {
+          uri.pathname += 'Contrast';
+        }
+
+        return url.format(uri);
+      }
+      return value;
+    },
+    desc: 'url to report on'
+  },
+  {
+    name: 'api.user_name',
+    env: 'CONTRASTSECURITY_UID',
+    arg: '<name>',
+    desc: 'account user name'
+  },
+  {
+    name: 'api.proxy.enable',
+    arg: '[true]',
+    default: false,
+    desc: 'if false, no proxy is being used for communication of data',
+  },
+  {
+    name: 'api.proxy.url',
+    arg: '<url>',
+    desc: 'url of proxy for communicating agent data',
+  },
+];
+
+const agent = [
+  {
+    name: 'agent.reporters.file',
+    arg: '<path>',
+    desc: 'path indicating where to report all agent findings'
+  },
+  {
+    name: 'agent.logger.append',
+    arg: '[false]',
+    fn: castBoolean,
+    default: true,
+    desc:
+      'if false, create a new log file on startup instead of appending and rolling daily'
+  },
+  {
+    name: 'agent.logger.level',
+    arg: '<level>',
+    fn: lowercase,
+    enum: ['error', 'warn', 'info', 'debug', 'trace'],
+    default: 'error',
+    desc:
+      'logging level (error, warn, info, debug, trace). overrides FeatureSet:logLevel'
+  },
+  {
+    name: 'agent.logger.path',
+    default: 'contrast.log',
+    fn: toAbsolutePath,
+    arg: '<path>',
+    desc: 'where contrast will put its debug log'
+  },
+  {
+    name: 'agent.logger.stdout',
+    arg: '[false]',
+    fn: castBoolean,
+    default: true,
+    desc: 'if false, suppress output to STDOUT'
+  },
+  {
+    name: 'agent.node.enable_rewrite',
+    arg: '[false]',
+    fn: castBoolean,
+    default: true,
+    desc: 'if false, disable source rewriting (not recommended)'
+  },
+  {
+    name: 'agent.node.enable_source_maps',
+    arg: '[false]',
+    fn: castBoolean,
+    default: true,
+    desc: 'enable source map support in reporting'
+  },
+  {
+    name: 'agent.node.app_root',
+    arg: '<path>',
+    desc: "set location to look for the app's package.json",
+    default: process.cwd()
+  },
+  {
+    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: 'agent.polling.app_activity_ms',
+    arg: '<ms>',
+    default: 30000,
+    fn: parseNum,
+    desc: 'how often (in ms), application activity messages are sent',
+  },
+];
+
+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)"
+  },
+  {
+    name: 'application.session_id',
+    arg: '<session_id>',
+    default: null,
+    desc: 'provide the ID of a session existing within Contrast UI'
+  },
+  {
+    name: 'application.session_metadata',
+    arg: '<session_metadata>',
+    default: null,
+    desc: 'provide metadata used to create a new session within Contrast UI'
+  }
+];
+
+const protect = [
+  {
+    name: 'protect.enable',
+    arg: '[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'
+  },
+  ...Object.values(Rule).map((ruleId) => ({
+    name: `protect.rules.${ruleId}.mode`,
+    arg: '<mode>',
+    enum: ['monitor', 'block', 'block_at_perimeter', 'off'],
+    desc: `the mode in which to run the ${ruleId} rule`
+  }))
+];
+
+const server = [
+  {
+    name: 'server.environment',
+    arg: '<name>',
+    fn: uppercase,
+    // enum: ['QA', 'PRODUCTION', 'DEVELOPMENT'], none of the other agents validate this
+    desc:
+      'environment the server is running in (QA, PRODUCTION, or DEVELOPMENT)'
+  },
+  {
+    name: 'server.name',
+    arg: '<name>',
+    default: os.hostname(),
+    desc: 'override the reported server name'
+  },
+  {
+    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,
+  server
+);
+
+module.exports.configOptions = options;
+module.exports.clearBaseCase = clearBaseCase;
+module.exports.castBoolean = castBoolean;

package/lib/util.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const process = require('process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const yaml = require('yaml');
+
+const { configOptions } = require('./options');
+const util = module.exports;
+
+function set(obj, name, value) {
+  const props = name.split('.');
+  const lastProp = props.pop();
+  for (const p of props) {
+    if (!obj[p]) obj[p] = {};
+    obj = obj[p];
+  }
+  obj[lastProp] = value;
+}
+
+/**
+ * Sets initial config values to the config.
+ *
+ * @param {Config} conf the config. mutates.
+ * @param {string} name name of the option, eg 'agent.logger.stdout'
+ * @param {*} value
+ * @param {boolean} def set from default or not
+ */
+function setConfig(conf, name, value, def) {
+  set(conf, name, value);
+  conf._default[name] = def;
+}
+
+class ConfigurationError extends Error {
+  constructor(message) {
+    super(`Configuration Error: ${message}`);
+  }
+}
+
+class Config {
+  constructor() {
+    Object.assign(this, {
+      _default: {},
+      api: {},
+      agent: {
+        reporters: {},
+        logger: {},
+        node: {},
+      },
+      application: {},
+      protect: {
+        rules: {},
+      },
+      server: {},
+    });
+  }
+
+  /**
+   * Override the setting, if set from its default.
+   *
+   * @param {string} name name of the option, eg 'agent.logger.stdout'
+   * @param {*} value
+   */
+  override(name, value) {
+    if (this._default[name]) {
+      setConfig(this, name, value, true);
+    }
+  }
+
+  get(name) {
+    return name.split('.').reduce((obj, prop) => obj?.[prop], this);
+  }
+
+  /**
+   * Custom validation logic.
+   * @throws {Error}
+   */
+  validate() {
+    // Mutually exclusive options:
+    if (
+      this.get('application.session_id') &&
+      this.get('application.session_metadata')
+    ) {
+      throw new ConfigurationError(
+        'Cannot set both `application.session_id` and `application.session_metadata`'
+      );
+    }
+  }
+}
+
+/**
+ * Find location of config given options and name of config file
+ * @return {string|void} path, if valid
+ */
+function checkConfigPath() {
+  const configDir =
+    os.platform() === 'win32'
+      ? `${process.env['ProgramData']}\\contrast`
+      : '/etc/contrast';
+
+  for (const dir of [process.cwd(), configDir]) {
+    const checkPath = path.resolve(dir, 'contrast_security.yaml');
+    if (fs.existsSync(checkPath)) {
+      return checkPath;
+    }
+  }
+  return;
+}
+
+/**
+ * Read config into object
+ * @return {Object} configuration
+ */
+function readConfig() {
+  let config = {};
+  let fileContents;
+  const configPath = process.env['CONTRAST_CONFIG_PATH'] || checkConfigPath();
+
+  if (configPath) {
+    try {
+      fileContents = fs.readFileSync(configPath, 'utf-8');
+    } catch (e) {
+      console.error(
+        'Unable to read config file at %s: %s',
+        configPath,
+        e.message
+      );
+    }
+  }
+
+  if (fileContents) {
+    try {
+      config = yaml.parse(fileContents, {
+        prettyErrors: true,
+      });
+    } catch (e) {
+      console.error(
+        'YAML validator found an error in %s: %s',
+        configPath,
+        e.message
+      );
+    }
+  }
+
+  return config;
+}
+
+/**
+ * We want to "un-flatten" the config, in the
+ * event that there are any dot-delimited keys remaining.
+ * FIXME: when we get rid of JSON, don't do this anymore
+ * @return {Object} "un-flattened" file options
+ */
+function getFileOptions() {
+  const config = readConfig();
+  return Object.values(config).reduce((memo, value, idx) => {
+    const key = Object.keys(config)[idx];
+    // Merge if necessary,
+    if (memo[key]) {
+      Object.assign(memo[key], value);
+    } else {
+      // but otherwise set the config path.
+      set(memo, key, value);
+    }
+
+    return memo;
+  }, {});
+}
+
+/**
+ * only set autoEnv if it's a common config option
+ * @param {string} name
+ */
+function getAutoEnv(name) {
+  const envName = name.toUpperCase().replace(/\./g, '__');
+  return name === 'configFile'
+    ? undefined
+    : process.env[`CONTRAST__${envName}`] || process.env[envName];
+}
+
+/**
+ * @return {Config} merged options
+ */
+function mergeOptions() {
+  const fileOptions = getFileOptions();
+
+  return configOptions.reduce((options, option) => {
+    const {
+      default: optDefault,
+      enum: optEnum,
+      fn = (arg) => arg,
+      name,
+    } = option;
+
+    const env = process.env[option.env];
+    const autoEnv = getAutoEnv(name);
+    const fileFlag = name
+      .split('.')
+      .reduce((obj, prop) => obj?.[prop], fileOptions);
+
+    // For some values, we want to know if we assigned by falling back to default
+    let isFromDefault;
+
+    // env > file > default
+    let value = [env, autoEnv, fileFlag]
+      .map((v) => fn(v))
+      .find((flag) => flag !== undefined);
+
+    // if it's an enum, find it in the enum or set the value to default
+    // ineffective if optDefault wasn't in the enum;
+    // optDefault won't get passed through fn, so it needs to be valid.
+    if (optEnum && optEnum.indexOf(value) === -1) {
+      value = fn(optDefault);
+      isFromDefault = true;
+    }
+
+    // set default last and separately, so that we can mark that the option was
+    // set from default
+    if (value === undefined) {
+      value = fn(optDefault);
+      isFromDefault = true;
+    }
+
+    setConfig(options, name, value, isFromDefault);
+    return options;
+  }, new Config());
+}
+
+util.Config = Config;
+util.setup = function setup() {
+  const mergedOptions = mergeOptions();
+  mergedOptions.validate();
+  return mergedOptions;
+};
+// We want to use the set method used here for creating a correct mock object for tests
+util.setValue = set;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@contrast/config",
+  "version": "1.0.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)",
+  "files": [
+    "lib/"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "npm": ">= 8.4.0",
+    "node": ">= 14.15.0"
+  },
+  "scripts": {
+    "test": "../scripts/test.sh"
+  },
+  "dependencies": {
+    "@contrast/common": "1.0.0",
+    "yaml": "^2.0.1"
+  }
+}