Configuration

YAML Properties

Contrast supports YAML-based configuration for the Node agent. This allows you to store configuration on disk that you can override with environment variables or command-line arguments.

Note: While all Contrast agents share the same property formatting in YAML configuration files, each agent must use its specified file.

Load Path

Configuration values use the following order of precedence:

  1. Corporate rule (e.g., expired license overrides assess.enable)
  2. Command line value
  3. Specific environmental variable
  4. Generic environment variable value
  5. User configuration file value
  6. Contrast UI value
  7. Default value

The agent expects that the contrast_security.yaml configuration file exists in the application's root directory (where the package.json file usually resides). If you want to change the location of the file, provide the agent with the new location using one of the following methods:

  • Pass a CLI option --configFile <location>
  • Set the CONTRAST_CONFIG environment variable

Go to the Node YAML Template for fully formatted properties that you can copy and use in your own configuration files.

Configuration Options

Contrast UI properties

Use the properties in this section to connect the Node agent to the Contrast UI. The proxy settings allow the agent to communicate with the Contrast UI over a proxy.

  • contrast:

    • enable: Only set this property if you want to turn off Contrast. Set to true to turn the agent on; set to false to turn the agent off.
    • url: Set the URL for the Contrast UI.
      Example: https://app.contrastsecurity.com/Contrast. Required.
    • api_key: Set the API key needed to communicate with the Contrast UI. Required.
    • service_key: Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header. Required.
    • user_name: Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header. Required.
    • timeout_ms: Set the default request timeout.

    • proxy:

      • enable: Add a property value to determine if the agent should communicate with the Contrast UI over a proxy. If a property value is not present, the presence of a valid proxy host and port determines enabled status. Value options are true or false
      • url: Set this property as an alternate for scheme://host:port. It takes precedence over the other settings, if specified; however, an error will be thrown if both the URL and individual properties are set.
    • certificate

      • enable: Set to false for the agent to ignore the certificate configuration in this section.
      • ca_file: Set the absolute or relative path to a CA for communication with Contrast UI using a self-signed certificate.
      • cert_file: Set the absolute or relative path to the Certificate PEM file for communication with Contrast UI.
      • key_file: Set the absolute or relative path to the Key PEM file for communication with Contrast UI.
      • key_password: Set the password for the Key file, if required.
      • ignore_cert_errors: Set to true for the agent to ignore certificate verification errors when the it communicates with the Contrast UI.

Contrast agent properties

Use the properties in this section to control the way and frequency with which the Node agent communicates to logs and to the Contrast UI. If these values are not set, the agent will use the values set in the Contrast UI.

All properties in this section must be put under the agent node, as shown in the YAML template.

  • agent:

    • auto_update:
      • enable: Set to true for the agent to automatically upgrade to newer versions.
      • path: Set the location to which to save the agent artifact before installation.
        Example: /tmp/contrast/
      • timeout_ms: Set the length of time to wait before aborting the auto-update attempt.

Diagnostic logging

Use the properties in this section to control diagnostic logging. These logs allow us to diagnose any issues you may be having with the agent.

  • logger:
    • path: Enable diagnostic logging by setting a path to a log file. While diagnostic logging hurts performance, it generates useful information for debugging Contrast. The value set here is the location to which the agent saves log output. If no log file exists at this location, the agent creates a file.
      Example: /opt/Contrast/contrast.log creates a log in the /opt/Contrast directory, and rotates it automatically as needed.
    • level: Set the the log output level. Value options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL.
    • append: Set to false for the agent to always create a new log file instead of appending and rolling.
    • stdout: Set to false for the agent to suppress output to STDOUT.

Security logging

Use the properties in this section to control security logging. These logs allow you to watch Protect as it monitors and blocks attacks against your application. They are written to the specified file in the Common Event Format (CEF). The Syslog settings allow you to send security logs to remote servers.

  • security_logger:
    • path: Set the file to which the agent logs security events.
      Example: /.contrast/security.log
    • level: Set the log level for security logging. Value options are OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, and ALL. Set this property to OFF to disable security logging.

Agent-specific properties

The following properties apply to any Node.js configurations.

  • node:
    • app_root: Explicitly set the location of the application's package.json file.
    • stack_trace_limit: Set the limit for lengths of stack traces.

Inventory properties

Use the properties in this section to control inventory features in the Node agent.

  • inventory:
    • analyze_libraries: Set to false for the agent to not read or report library data.
    • tags: Apply a list of labels to libraries. Labels must be formatted as a comma-delimited list.
      Example: label1, label2, label3

Contrast Assess properties

Use the properties in this section to control Assess in the Node agent. The sampling settings allow you to control which requests the agent tracks and which it ignores. The rules setting allows you to control which Assess rules are disabled.

Note: If you need a complete list of rules, use the Support widget in OpenDocs to contact Contrast's Customer Support team.

  • assess:

    • enable: 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.
      Example: true
    • tags: Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list. Example: label1, label2, label3

    • samplings:

      • enable: Set to false to disable sampling.
      • baseline: This property indicates how many requests to analyze in each window before sampling begins.
        Example: 5

Contrast Protect properties

Use the properties in this section to control Protect features and rules.

  • protect:

    • samples:
      • blocked: Set the maximum number of Blocked events that the agent reports (per report cycle).
        Example: 25
      • blocked_at_perimeter: Set the maximum number of Blocked-at-Perimeter events that the agent reports (per report cycle).
      • exploited: Set the maximum number of Effective that the agent reports (per report cycle).
      • ineffective: Set the maximum number of Ineffective events that the agent reports (per report cycle).

Application properties

Use the properties in this section to control the application(s) hosting this agent.

  • application:
    • name: Override the reported application name.
    • path: Override the reported application path.
    • group: Add the name of the application group with which this application should be associated in the Contrast UI.
    • version: Override the reported application version.
    • args: Pass arguments to the underlying application.
    • tags: Apply labels to an application. Labels must be formatted as a comma-delimited list.
      Example: label1,label2,label3
    • metadata: Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application. The set must be formatted as a comma-delimited list of key=value pairs.
      Example: "business-unit=accounting, office=Baltimore"

Server properties

Use the properties in this section to set metadata for the server hosting this agent.

  • server:

    • name: Override the reported server name.
      Example: test-server-1
    • path: Override the reported server path.
    • type: Override the reported server type.
    • build: Override the reported server build.
    • version: Override the reported server version.
    • environment: Override the reported server environment.
      Example: development
    • tags: Apply a list of labels to the server. Labels must be formatted as a comma-delimited list.
      Example: label1,label2,label3

General Properties

You may use configuration options to alter Contrast's behavior. They can all be appended to your startup command (e.g., npm run contrast -- --agent.logger.stdout false or node-contrast server.js --agent.logger.stdout false). They can also be set via environment variables of the form SETTING__NAME (e.g., --agent.logger.stdout false becomes AGENT__LOGGER__STDOUT=false). With the exception of --configFile, they can all be added to your contrast_security.yaml file as well.

General Configuration Options

Parameter Environment Variable Description
-c, --configFile CONTRAST_CONFIG Set config file location. Defaults to /contrast_security.yaml.
--contrast.enable [false] CONTRAST__ENABLE Set false to disable reporting. Default is true.
--contrast.api_key CONTRAST__API_KEY The organization API key.
--contrast.service_key CONTRAST__SERVICE_KEY Account service key.
--contrast.url CONTRAST__URL URL on which to report. Default is https://app.contrastsecurity.com/.
--contrast.user_name CONTRAST__USER_NAME Account user name.
--contrast.proxy.enable [true] CONTRAST__PROXY__ENABLE If false, no proxy is being used for communication of data.
--contrast.proxy.url CONTRAST__PROXY__URL URL of proxy for communicating agent data.
--contrast.timeout_ms CONTRAST__TIMEOUT_MS Http timeout value (in ms). Default is 10000.
--contrast.certificate.enable [false] CONTRAST__CERTIFICATE__ENABLE If set to false, the certificate configuration in this section will be ignored. (default: false)
--contrast.certificate.ca_file CONTRAST__CERTIFICATE__CA_FILE When running an Enterprise-on-Premises (EOP) Contrast instance using a self-signed certificate, use this option to provide the relative or absolute path to your CA file.
--contrast.certificate.cert_file CONTRAST__CERTIFICATE__CERT_FILE Set the absolute or relative path to the Certificate PEM file for communication with Contrast UI.
--contrast.certificate.key_file CONTRAST__CERTIFICATE__KEY_FILE Set the absolute or relative path to the Key PEM file for communication with Contrast UI.
--contrast.certificate.key_password CONTRAST__CERTIFICATE__KEY_PASSWORD If the Key file requires a password, set it here.
--contrast.certificate.ignore_cert_errors [true] CONTRAST__CERTIFICATE__IGNORE_CERT_ERRORS Allows the agent to communicate data, even if Contrast's cert can't be verified against supplied list of CAs.
--agent.auto_update [false] AGENT__AUTO_UPDATE If false, don't attempt to auto-update the agent. Default is true.
--agent.auto_update_path AGENT__AUTO_UPDATE_PATH Directory where the updated agent artifact should be saved before installation. Default is /var/folders/ck/4cpmx4m569j29z7n05dnfb4h0000gp/T.
--agent.auto_update_timeout_ms AGENT__AUTO_UPDATE_TIMEOUT_MS Time to wait before aborting auto-update attempt. Default is 60000.
--agent.logger.append [false] AGENT__LOGGER__APPEND If false, create a new log file on startup instead of appending and rolling daily. Default is true.
--agent.logger.level AGENT__LOGGER__LEVEL Logging level: fatal, error, warn, info, debug or trace. Overrides FeatureSet:logLevel. Default is error.
--agent.logger.path AGENT__LOGGER__PATH Where Contrast will put its debug log. Default is node-contrast.log.
--agent.logger.stdout [false] AGENT__LOGGER__STDOUT If false, suppress output to STDOUT. Default is true.
--agent.node.enable_rewrite [false] AGENT__NODE__ENABLE_REWRITE If false, disable source rewriting. Default is true. (Not recommended.)
--agent.node.enable_rewrite_log [true] AGENT__NODE__ENABLE_REWRITE_LOG Log contents of modules that have been rewritten for debugging purposes.
--agent.node.app_root AGENT__NODE__APP_ROOT Set location to look for the application's package.json.
--agent.node.stack_trace_limit AGENT__NODE__STACK_TRACE_LIMIT Set limit for stack trace size. Default is 10.
--agent.node.skip_nested_taint [true] AGENT__NODE__SKIP_NESTED_TAINT Don't traverse nested properties to look for taint during propagation. (Not recommended.)
--agent.node.stacktrace_logging.enabled [true] AGENT__NODE__STACKTRACELOGGING\_ENABLED Log all application errors to agent's /dumps file for aggressive debugging. (Not recommended.)
--agent.polling.app_activity_ms AGENT__POLLING__APP_ACTIVITY_MS How often (in ms), application activity messages are sent. Default is 30000.
--agent.polling.app_update_ms AGENT__POLLING__APP_UPDATE_MS How often (in ms), application update messages (libraries, technologies, etc.) are sent. Default is 60000.
--application.args APPLICATION__ARGS String containing args to pass verbatim to the application. (E.g., --application.args "-A -S -D -F foo bar".)
--application.group APPLICATION__GROUP How to report the application's group for auto-grouping.
--application.name APPLICATION__NAME Override the reported application name. Default is package.json:name.
--application.path APPLICATION__PATH Override the reported application path. Default is /.
--application.tags APPLICATION__TAGS Comma-separated list of tags to apply to each application reported by the agent.
--application.version APPLICATION__VERSION Override the reported application version, if different from 'version' field in the application's package.json.
--application.vulnerability.tags APPLICATION__VULNERABILITY__TAGS Comma-separated list of tags to apply to each application vulnerability reported by the agent.
--assess.enable [false] ASSESS__ENABLE If false, disable assess mode. Default is true.
--assess.enable_preflight [false] ASSESS__ENABLE_PREFLIGHT If false, disable preflight spooling of traces. Default is true. (Not recommended.)
--assess.enable_propagators [false] ASSESS__ENABLE_PROPAGATORS If false, disable dataflow propagation. Default is true. (Not recommended.)
--assess.sampling.enable [false] ASSESS__SAMPLING__ENABLE If false, disable sampling. Default is true.
--assess.sampling.baseline ASSESS__SAMPLING__BASELINE Maximum number of times to report the same rule for a single. Default is 5.
--inventory.analyze_libraries [false] INVENTORY__ANALYZE_LIBRARIES If false, don't read or report library data. Default is true.
--inventory.tags INVENTORY__TAGS Comma-separated list of tags to apply to each application library reported by the agent.
--protect.enable [false] PROTECT__ENABLE If false, disable protect mode. Default is true.
--protect.auth.mode PROTECT__AUTH__MODE Whether to report authentication framework login attempts. Options are OFF or MONITOR. Default is OFF.
--protect.samples.blocked PROTECT__SAMPLES__BLOCKED Limit the reporting of "blocked" Protect events to this number (per report cycle). Default is 25.
--protect.samples.blocked_at_perimeter PROTECT__SAMPLES__BLOCKED_AT_PERIMETER Limit the reporting of "blocked-at-perim" Protect events to this number (per report cycle). Default is 25.
--protect.samples.exploited PROTECT__SAMPLES__EXPLOITED Limit the reporting of "effective" Protect events to this number (per report cycle). Default is 100.
--protect.samples.ineffective PROTECT__SAMPLES__INEFFECTIVE Limit the reporting of "ineffective" Protect events to this number (per report cycle). Default is 50.
--server.build SERVER__BUILD Set reported server build option.
--server.environment SERVER__ENVIRONMENT Environment in which the server is running - QA, PRODUCTION or DEVELOPMENT (case insenstive); does not affect servers that already exist in Contrast.
--server.name SERVER__NAME Override the reported server name. Default is ip-192-168-1-50.ec2.internal.
--server.path SERVER__PATH Override the reported server path. Default is /.
--server.tags SERVER__TAGS Comma-separated list of tags to apply to each server reported by the agent.
--server.type SERVER__TYPE Override the reported server type. Default is node.js v8.9.4.
--server.version SERVER__VERSION Override the reported server version, if different from 'version' field in the application's package.json.
-h, --help Output usage information.

Logging

To prevent crowding stdout, INFO-level statements aren't logged to the console unless the environment variable DEBUG is set to include the Contrast namespace: DEBUG=contrast:*.

The namespace can also be manipulated to show and hide certain paths.

Examples:
If you want to only see statements within the namespaces contrast:hooks and contrast:http, you can set the environment variable as DEBUG=contrast:hooks,contrast:http.
If you want to hide certain namespaces, prepend a -, as in DEBUG=contrast:*,-contrast:hooks.

By default, the agent logs to /node-contrast.log. For performance reasons, verbose logging options are disabled. The following configuration options allow you to modify how the agent handles file logging.

Parameter Description
--agent.logger.append [false] If false, create a new log file on startup instead of appending and rolling daily. Default is true.
--agent.logger.level Logging level: fatal, error, warn, info, debug or trace. Overrides FeatureSet:logLevel. Default is error.
--agent.logger.path Where Contrast will put its debug log. Default is node-contrast.log.
--agent.logger.stdout [false] If false, suppress output to STDOUT. Default is true.

Application Arguments

To pass configuration options to the application being run with Contrast, use the --application.args flag, or append -- to the run command, followed by the arguments for the application.

Example: npm run contrast -- --agent.logger.level debug -- --appArg0 foo --appArg1 bar will pass appArg0 foo and appArg1 bar directly to the application.

CLI Arguments

From the Node.js documentation, you can see scripts are executed in the following way:

node [options] [V8 options] [script.js] [--] [arguments];

The Contrast agent is a Node.js wrapper (runner) that invokes node to start the application. The agent doesn't pass any flags to the underlying Node.js executable, or provide the ability to do so with agent configuration options. To pass CLI flags to Node.js, you must invoke node explicitly with the agent as the script argument, followed by the name of the application's entry point file and any configuration flags, as outlined above.

When the agent is installed, a symlink is created, <app-dir>/node_modules/.bin/node-contrast, which points to the file <app-dir>/node_modules/node_contrast/cli.js. You can use either of these as the script argument when starting the application this way.

Example:
Without the Contrast agent, you start your application using the following command:

 node --title=MyWebsite --stack-trace-limit=25 ./index.js --env development

To run the application with the same Node.js flags and the Contrast agent, you could use either of the following commands:

node --title=MyWebsite --stack-trace-limit=25 ./node_modules/.bin/node-contrast ./index.js -- --env development
node --title=MyWebsite --stack-trace-limit=25 ./node_modules/node_contrast/cli.js ./index.js -- --env development

YAML Template

Go to the Node YAML Properties article for more information about this template.

#================================================================================================================================================================================
#  
#  Use the properties in this YAML file to configure a Contrast agent. Go to https://docs.contrastsecurity.com/ to determine the order of precedence for configuration values. 
#  
#================================================================================================================================================================================


#================================================================================
# Contrast
# Use the properties in this section to connect the agent to the Contrast UI.
#================================================================================
contrast:

  # Only set this property if you want to turn off Contrast. Set to `true` to turn the agent on; set to `false` to turn the agent off.
  # enable: true

  # ********************** REQUIRED **********************
  # Set the URL for the Contrast UI.
  url: https://app.contrastsecurity.com/Contrast

  # ********************** REQUIRED **********************
  # Set the API key needed to communicate with the Contrast UI.
  api_key: NEEDS_TO_BE_SET

  # ********************** REQUIRED **********************
  # Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header.
  service_key: NEEDS_TO_BE_SET

  # ********************** REQUIRED **********************
  # Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.
  user_name: NEEDS_TO_BE_SET

  # Set the absolute or relative path to a CA for communication with Contrast UI using a self-signed certificate.
  # ca_file: path/to/ca

  # Set the default request timeout.
  # timeout_ms: NEEDS_TO_BE_SET

  #======================================================================================
  # Proxy
  # Use the following properties for communication with the Contrast UI over a proxy.
  #======================================================================================
  # proxy:

    # Add a property value to determine if the agent should communicate with the Contrast UI over a proxy. If a property value is not present, the presence of a valid proxy host and port determines enabled status.
    # enable: NEEDS_TO_BE_SET

    # Set this property as an alternate for `scheme://host:port`. It takes precedence over the other settings, if specified; however, an error will be thrown if both the URL and individual properties are set.
    # url: NEEDS_TO_BE_SET

#=======================================================================================================================================
# Agent
# Use the properties in this section to control the way and frequency with which the agent communicates to logs and the Contrast UI.
#=======================================================================================================================================
# agent:

  # Set to limit the length of Error stack traces to a specified number.
  # stack_trace_limit: 10

  #=========
  # Auto_update
  # TODO
  #=========
  # auto_update:

    # Set to `true` for the agent to automatically upgrade to newer versions.
    # enable: true

    # Set the location to which to save the agent artifact before installation.
    # path: /tmp/contrast/

    # Set the length of time to wait before aborting the auto-update attempt.
    # timeout_ms: NEEDS_TO_BE_SET

  #================================================================================================================================================================
  # Logger
  # Define the following properties to set logging values. If the following properties are not defined, the agent uses the logging values from the Contrast UI.
  #================================================================================================================================================================
  # logger:

    # Enable diagnostic logging by setting a path to a log file. While diagnostic logging hurts performance, it generates useful information for debugging Contrast. The value set here is the location to which the agent saves log output. If no log file exists at this location, the agent creates a file. 
    #  Example - */opt/Contrast/contrast.log* creates a log in the */opt/Contrast* directory, and rotates it automatically as needed.
    # path: ./contrast_agent.log

    # Set the the log output level. Valid options are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.
    # level: ERROR

    # Set to `false` for the agent to always create a new log file instead of appending and rolling.
    # append: true

    # Set to `true` to log to STDOUT. Set to `false` for the agent to suppress output to STDOUT.
    # stdout: NEEDS_TO_BE_SET

  #===========================================================================================================================================================
  # Security_logger
  # Define the following properties to set security logging values. If not defined, the agent uses the security logging (CEF) values from the Contrast UI.
  #===========================================================================================================================================================
  # security_logger:

    # Set the file to which the agent logs security events.
    # path: /.contrast/security.log

    # Set the log level for security logging. Value options are `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, and `ALL`. Set this property to `OFF` to disable security logging.
    # level: NEEDS_TO_BE_SET

  #===============================================================
  # Node
  # The following properties apply to any Node configurations.
  #===============================================================
  # node:

    # Set the location of the application's *package.json* file.
    # app_root: NEEDS_TO_BE_SET

#===========================================================================
# Inventory
# Use the properties in this section to override the inventory features.
#===========================================================================
# inventory:

  # Apply a list of labels to libraries. Labels must be foratted as a comma-delimited list. \n Example - label1, label2, label3
  # tags: NEEDS_TO_BE_SET

#==========================================================
# Assess
# Use the properties in this section to control Assess.
#==========================================================
# assess:

  # 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.
  # enable: true

  # Apply a list of labels to vulnerabilities and preflight messages. Labels must be formatted as a comma-delimited list. \n Example - label1, label2, label3
  # tags: NEEDS_TO_BE_SET

  #===================================================================
  # Sampling
  # Use the following properties to control sampling in the agent.
  #===================================================================
  # sampling:

    # Set to `false` to disable sampling.
    # enable: true

    # This property indicates how many requests to analyze in each window before sampling begins.
    # baseline: 5

#=====================================================================
# Protect
# Use the properties in this section to override Protect features.
#=====================================================================
# protect: {}

#==================================================================================
# Application
# Use the properties in this section for the application(s) hosting this agent.
#==================================================================================
# application:

  # Override the reported application name.
  # name: NEEDS_TO_BE_SET

  # Override the reported application path.
  # path: NEEDS_TO_BE_SET

  # Add the name of the application group with which this application should be associated in the Contrast UI.
  # group: NEEDS_TO_BE_SET

  # Override the reported application version.
  # version: NEEDS_TO_BE_SET

  # Pass arguments to the underlying application.
  # args: NEEDS_TO_BE_SET

  # Apply labels to an application. Labels must be formatted as a comma-delimited list. 
  #  Example - label1,label2,label3
  # tags: NEEDS_TO_BE_SET

  # Define a set of key=value pairs (which conforms to RFC 2253) for specifying user-defined metadata associated with the application. The set must be formatted as a comma-delimited list of `key=value` pairs.
  #  Example - "business-unit=accounting, office=Baltimore"
  # metadata: NEEDS_TO_BE_SET

#==========================================================================================
# Server
# Use the properties in this section to set metadata For the server hosting this agent.
#==========================================================================================
# server:

  # Override the reported server name.
  # name: test-server-1

  # Override the reported server path.
  # path: NEEDS_TO_BE_SET

  # Override the reported server type.
  # type: NEEDS_TO_BE_SET

  # Override the reported server build.
  # build: NEEDS_TO_BE_SET

  # Override the reported server version.
  # version: NEEDS_TO_BE_SET

  # Override the reported server environment.
  # environment: development

  # Apply a list of labels to the server. Labels must be formatted as a comma-delimited list. 
  #  Example - label1,label2,label3 
  # tags: NEEDS_TO_BE_SET