@contrast/config 1.2.0 → 1.3.0

package/lib/index.d.ts

@@ -16,6 +16,15 @@
 import { RulesConfig } from '@contrast/common';
 import { Level } from 'pino';
 
+type SyslogLevel =
+  | 'alert'
+  | 'critical'
+  | 'error'
+  | 'warning'
+  | 'notice'
+  | 'info'
+  | 'debug';
+
 export interface Config {
   configFile: string;
 
@@ -31,13 +40,14 @@ export interface Config {
     proxy: {
       enable: boolean;
       url: string;
-    }
+    };
   };
 
   agent: {
     polling: {
       app_activity_ms: number;
-    },
+    };
+
     reporters: {
       /** Path indicating where to report all agent findings. */
       file?: string | number;
@@ -63,6 +73,44 @@ export interface Config {
       stdout: boolean;
     };
 
+    security_logger: {
+      /** Default: `'debug'` */
+      level: SyslogLevel;
+
+      /** Default: `'security'` */
+      path: string;
+
+      syslog: {
+        enable: boolean;
+
+        ip: string;
+
+        /** Default: UDP `514` */
+        port: number;
+
+        /**
+         * The facility code of the messages the agent sends to Syslog.
+         * Values: 0-23, inclusive. Default: `19`
+         */
+        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 at Perimeter' attacks. Default: `'notice'` */
+        severity_blocked_perimeter: SyslogLevel;
+
+        /** Log level of suspcious but not blocked attacks. Default: `'warning'` */
+        severity_suspicious: SyslogLevel;
+      };
+    };
+
     node: {
       /** Default: `true` */
       enable_rewrite: boolean;
@@ -122,6 +170,7 @@ export interface Config {
   /** Reported server information overrides */
   server: {
     environment?: string;
+    tags?: string;
     /** Default: `os.hostname()` */
     name: string;
     version?: string;

package/lib/options.js

@@ -52,11 +52,11 @@ function castBoolean(value) {
     return;
   }
   value = value.toString().toLowerCase();
-  return (value === 'true' || value === 't')
+  return value === 'true' || value === 't'
     ? true
-    : (value === 'false' || value === 'f')
-        ? false
-        : undefined;
+    : value === 'false' || value === 'f'
+      ? false
+      : undefined;
 }
 
 /**
@@ -96,9 +96,8 @@ const config = [
     // 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'
-  }
+    desc: 'set config file location. defaults to <app_root>/contrast_security.yaml',
+  },
 ];
 
 const api = [
@@ -107,19 +106,19 @@ const api = [
     arg: '[false]',
     fn: castBoolean,
     default: true,
-    desc: 'set false to disable reporting'
+    desc: 'set false to disable reporting',
   },
   {
     name: 'api.api_key',
     env: 'CONTRASTSECURITY_API_KEY',
     arg: '<key>',
-    desc: 'the organization API key'
+    desc: 'the organization API key',
   },
   {
     name: 'api.service_key',
     env: 'CONTRASTSECURITY_SECRET_KEY',
     arg: '<key>',
-    desc: 'account service key'
+    desc: 'account service key',
   },
   {
     name: 'api.url',
@@ -156,13 +155,13 @@ const api = [
       }
       return value;
     },
-    desc: 'url to report on'
+    desc: 'url to report on',
   },
   {
     name: 'api.user_name',
     env: 'CONTRASTSECURITY_UID',
     arg: '<name>',
-    desc: 'account user name'
+    desc: 'account user name',
   },
   {
     name: 'api.proxy.enable',
@@ -181,15 +180,14 @@ const agent = [
   {
     name: 'agent.reporters.file',
     arg: '<path>',
-    desc: 'path indicating where to report all agent findings'
+    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'
+    desc: 'if false, create a new log file on startup instead of appending and rolling daily',
   },
   {
     name: 'agent.logger.level',
@@ -197,57 +195,139 @@ const agent = [
     fn: lowercase,
     enum: ['error', 'warn', 'info', 'debug', 'trace'],
     default: 'error',
-    desc:
-      'logging level (error, warn, info, debug, trace). overrides FeatureSet:logLevel'
+    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'
+    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'
+    desc: 'if false, suppress output to STDOUT',
+  },
+  {
+    name: 'agent.security_logger.level',
+    arg: '<level>',
+    fn: lowercase,
+    // NOTE: syslog actually specifies 8 levels, starting with 0-emergency, but
+    // we do not let the user set emergency for whatever reason
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'debug',
+    desc: 'security logging level (alert, crit, err, warning, notice, info, debug)',
+  },
+  {
+    name: 'agent.security_logger.path',
+    // default: 'security',
+    fn: toAbsolutePath,
+    arg: '<path>',
+    desc: 'where to log security events',
+  },
+  {
+    name: 'agent.security_logger.syslog.enable',
+    fn: castBoolean,
+    desc: 'Set to true to enable Syslog logging',
+  },
+  {
+    name: 'agent.security_logger.syslog.ip',
+    desc: 'Set the IP address of the Syslog server to which the agent should send messages',
+    arg: '<ip>',
+  },
+  {
+    name: 'agent.security_logger.syslog.port',
+    desc: 'Set the port of the Syslog server to which the agent should send messages',
+    default: 514,
+    arg: '<port>',
+    fn: parseNum,
+  },
+  {
+    name: 'agent.security_logger.syslog.facility',
+    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,
+    ],
+    default: 19,
+    arg: '<facility>',
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_blocked',
+    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'],
+    default: 'notice',
+    arg: '<level>',
+    fn: lowercase,
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_exploited',
+    desc: 'Set the log level of Exploited attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'alert',
+    arg: '<level>',
+    fn: lowercase,
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_probed',
+    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'],
+    default: 'warning',
+    arg: '<level>',
+    fn: lowercase,
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_blocked_perimeter',
+    desc: 'Set the log level of Blocked at Perimeter attacks. Value options are ALERT/CRITICAL/ERROR/WARNING/NOTICE/INFO/DEBUG',
+    enum: ['alert', 'critical', 'error', 'warning', 'notice', 'info', 'debug'],
+    default: 'notice',
+    arg: '<level>',
+    fn: lowercase,
+  },
+  {
+    name: 'agent.security_logger.syslog.severity_suspicious',
+    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'],
+    default: 'warning',
+    arg: '<level>',
+    fn: lowercase,
   },
   {
     name: 'agent.node.enable_rewrite',
     arg: '[false]',
     fn: castBoolean,
     default: true,
-    desc: 'if false, disable source rewriting (not recommended)'
+    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'
+    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()
+    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)'
+    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'
+    desc: 'comma-separated list of patterns to ignore within stack traces',
   },
   {
     name: 'agent.polling.app_activity_ms',
@@ -263,32 +343,31 @@ const application = [
     name: 'application.name',
     arg: '<name>',
     env: 'CONTRASTSECURITY_APP_NAME',
-    desc: 'override the reported application name. (default: package.json:name)'
+    desc: 'override the reported application name. (default: package.json:name)',
   },
   {
     name: 'application.path',
     arg: '<path>',
     default: '/',
-    desc: 'override the reported application path'
+    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: "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'
+    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'
-  }
+    desc: 'provide metadata used to create a new session within Contrast UI',
+  },
 ];
 
 const protect = [
@@ -296,14 +375,14 @@ const protect = [
     name: 'protect.enable',
     arg: '[false]',
     fn: castBoolean,
-    desc: 'if false, disable protect for this agent'
+    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: 'comma-separated list of rule ids to disable',
   },
   {
     name: 'protect.probe_analysis.enable',
@@ -316,41 +395,38 @@ 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: `the mode in which to run the ${ruleId} rule`,
+  })),
 ];
 
 const server = [
   {
     name: 'server.environment',
-    arg: '<name>',
+    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)',
+  },
+  {
+    name: 'server.tags',
+    arg: '<tags>',
     desc:
-      'environment the server is running in (QA, PRODUCTION, or DEVELOPMENT)'
+      '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: '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)"
-  }
+    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
-);
+const options = [].concat(config, api, agent, application, protect, server);
 
 module.exports.configOptions = options;
 module.exports.clearBaseCase = clearBaseCase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/config",
-  "version": "1.2.0",
+  "version": "1.3.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.1.2",
+    "@contrast/common": "1.1.3",
     "yaml": "^2.0.1"
   }
 }