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. Go to the Node YAML Template for fully formatted properties that you can copy and use in your own configuration files.

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

Order of Precedence

Configuration values use the following order of precedence (where 1 is the highest):

  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

Load Path

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

Configuration Options

Enable the agent

  • 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.

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.

  • api:
    • 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.

Certificate

Use the following properties for communication with the Contrast UI using certificates.

  • certificate
    • enable: Set to false for the agent to ignore the certificate configuration in this section.
    • ignore_cert_errors: Allows the agent to communicate data, even if Contrast's cert can't be verified against supplied list of CAs.
    • 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.

Proxy

Use the following properties for communication with the Contrast UI over a proxy.

  • 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.

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.

Contrast Service

The following properties are used by the Contrast Service.

  • service:
    • enable: Set to false to disallow the service to be started, and effectively disable the agent, if read by the service. If the agent reads this property, it disallows service auto-start. Required.
    • socket: If this property is defined, the service is listening on a Unix socket at the defined path.
      Example: /tmp/service.sock
    • host: Set the the hostname or IP address of the Contrast service to which the Contrast agent should report. Required.
      Example: localhost
    • port: Set the the port of the Contrast service to which the Contrast agent should report. Required.
      Example: 30555
Logger

The following properties are used by the logger in the Contrast service. If the properties are not defined, the service uses the logging values from the Contrast UI.

  • logger:
    • path: Set the location to which the Contrast service saves log output. If no log file exists at this location, the service creates one.
      Example: /opt/Contrast/contrast_service.log will create a log in the /opt/Contrast directory.
    • level: Set the the log output level. Value options are ERROR, WARN, INFO, and DEBUG.

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 the path starts with /dev/, it doesn't create a rotated file. 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 ERROR, WARN, INFO, DEBUG, and TRACE.
    • 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. Valid options are ERROR, WARN, INFO, DEBUG, and TRACE.

Syslog

Define the following properties to set Syslog values. If the properties aren't defined, the agent uses the Syslog values from the Contrast UI. Syslog properties must be nested under security_logger.

  • syslog:
    • enable: Set to true to enable Syslog logging
    • ip: Set the IP address of the Syslog server to which the agent should send messages.
    • port: Set the port of the Syslog server to which the agent should send messages.
    • facility: Set the facility code of the messages the agent sends to Syslog.
    • severity_blocked: Set the log level of Blocked attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.
    • severity_exploited: Set the log level of Exploited attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.
    • severity_probed: Set the log level of Probed attacks. Value options are ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, and DEBUG.

Heap dumps

The following properties are used to trigger heap dumps from within the agent to snapshot the behavior of instrumented applications.

  • enable: Set to true for the agent to automatically take heap dumps of the instrumented application.

  • path: Set the location to which to save the heap dump files. If relative, the path is determined based on the process' working directory.
    Example: contrast_heap_dumps

  • delay_ms: Set the amount of time to wait, in milliseconds, after agent startup to begin taking heap dumps.
    Example: 10_000

  • window_ms: Set the amount of time to wait, in milliseconds, between each heap dump.
    Example: 10_000

  • count: Set the number of heap dumps to take before disabling this feature.
    Example: 5

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 the number of 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:
    • code: Add the application code this application should use in the Contrast UI.
    • name: Override the reported application name.
      Note: On Java systems where multiple, distinct applications may be served by a single process, this configuration causes the agent to report all discovered applications as one application with the given 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"
    • session_id: Provide the ID of a session which already exists in the Contrast UI. Vulnerabilities discovered by the agent are associated with this session. If an invalid ID is supplied, the agent will be disabled. This option and application.session_metadata are mutually exclusive; if both are set, the agent will be disabled.
    • session_metadata: Provide metadata which is used to create a new session ID in the Contrast UI. Vulnerabilities discovered by the agent are associated with this new session. This value should be formatted as key=value pairs (conforming to RFC 2253). Available key names for this configuration are branchName, buildNumber, commitHash, committer, gitTag, repository, testRun, and version. This option and application.session_id are mutually exclusive; if both are set the agent will be disabled.

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.
    • 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

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.
# ==============================================================================


# 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

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

  # ********************** 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 default request timeout.
  # timeout_ms: NEEDS_TO_BE_SET

  # ============================================================================
  # api.certificate
  # Use the following properties for communication
  # with the Contrast UI using certificates.
  # ============================================================================
  # certificate:

    # If set to `false`, the agent will ignore the
    # certificate configuration in this section.
    # enable: true

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

    # Set the absolute or relative path to the Certificate
    # PEM file for communication with the Contrast UI.
    # cert_file: NEEDS_TO_BE_SET

    # Set the absolute or relative path to the Key PEM
    # file for communication with the Contrast UI.
    # key_file: NEEDS_TO_BE_SET

    # If the Key file requires a password, it can be set here or in
    # the matching ENV value (`CONTRAST__CERTIFICATE__KEY_PASSWORD`).
    # key_password: NEEDS_TO_BE_SET

  # ============================================================================
  # api.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

  # ============================================================================
  # agent.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

  # ============================================================================
  # agent.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 redirect all logs to
    # `stdout` instead of the file system.
    # stdout: false

  # ============================================================================
  # agent.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. Valid options
    # are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `TRACE`.
    # level: ERROR

    # ==========================================================================
    # agent.security_logger.syslog
    # Define the following properties to set Syslog values. If the properties
    # are not defined, the agent uses the Syslog values from the Contrast UI.
    # ==========================================================================
    # syslog:

      # Set to `true` to enable Syslog logging.
      # enable: NEEDS_TO_BE_SET

      # Set the IP address of the Syslog server
      # to which the agent should send messages.
      # ip: NEEDS_TO_BE_SET

      # Set the port of the Syslog server to
      # which the agent should send messages.
      # port: NEEDS_TO_BE_SET

      # Set the facility code of the messages the agent sends to Syslog.
      # facility: NEEDS_TO_BE_SET

      # Set the log level of Exploited attacks. Value options are `ALERT`,
      # `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_exploited: NEEDS_TO_BE_SET

      # Set the log level of Blocked attacks. Value options are `ALERT`,
      # `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_blocked: NEEDS_TO_BE_SET

      # Set the log level of Probed attacks. Value options are `ALERT`,
      # `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
      # severity_probed: NEEDS_TO_BE_SET

  # ============================================================================
  # agent.service
  # The following properties are used by the Contrast Service.
  # ============================================================================
  # service:

    # Set to `false` to disallow the service to be started, and
    # effectively disable the agent, if read by the service. If the
    # agent reads this property, it disallows service auto-start.
    # enable: true

    # If this property is defined, the service is
    # listening on a Unix socket at the defined path.
    # socket: /tmp/service.sock

    # ********************** REQUIRED **********************
    # Set the the hostname or IP address of the Contrast
    # service to which the Contrast agent should report.
    host: localhost

    # ********************** REQUIRED **********************
    # Set the the port of the Contrast service
    # to which the Contrast agent should report.
    port: 30555

    # ==========================================================================
    # agent.service.logger
    # The following properties are used by the logger in the
    # Contrast service. If the properties are not defined, the
    # service uses the logging values from the Contrast UI.
    # ==========================================================================
    # logger:

      # Set the location to which the Contrast service saves log output.
      # If no log file exists at this location, the service creates one.
      #  
      # Example - */opt/Contrast/contrast_service.log* will
      # create a log in the */opt/Contrast* directory.
      # path: ./contrast_service.log

      # Set the the log output level. Options are `OFF`, `FATAL`,
      # `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, and `ALL`.
      # level: ERROR

  # ============================================================================
  # agent.heap_dump
  # The following properties are used to trigger heap dumps from within
  # the agent to snapshot the behavior of instrumented applications.
  # ============================================================================
  # heap_dump:

    # Set to `true` for the agent to automatically
    # take heap dumps of the instrumented application.
    # enable: false

    # Set the location to which to save the heap dump files. If relative,
    # the path is determined based on the process' working directory.
    # path: contrast_heap_dumps

    # Set the amount of time to wait, in milliseconds,
    # after agent startup to begin taking heap dumps.
    # delay_ms: 10_000

    # Set the amount of time to wait, in milliseconds, between each heap dump.
    # window_ms: 10_000

    # Set the number of heap dumps to take before disabling this feature.
    # count: 5

  # ============================================================================
  # agent.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

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

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

    # This property indicates the number of 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.
  #  
  # Note - On Java systems where multiple, distinct applications may be
  # served by a single process, this configuration causes the agent to report
  # all discovered applications as one application with the given 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

  # Add the application code this application should use in the Contrast UI.
  # code: 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

  # Provide the ID of a session which already exists in the Contrast
  # UI. Vulnerabilities discovered by the agent are associated with
  # this session. If an invalid ID is supplied, the agent will be
  # disabled. This option and `application.session_metadata` are
  # mutually exclusive; if both are set, the agent will be disabled.
  # session_id: NEEDS_TO_BE_SET

  # Provide metadata which is used to create a new session ID in the
  # Contrast UI. Vulnerabilities discovered by the agent are associated
  # with this new session. This value should be formatted as key=value pairs
  # (conforming to RFC 2253). Available key names for this configuration
  # are branchName, buildNumber, commitHash, committer, gitTag, repository,
  # testRun, and version. This option and `application.session_id` are
  # mutually exclusive; if both are set the agent will be disabled.
  # session_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 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

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_PATH Set config file location. Defaults to /contrast_security.yaml.
--enable [false] ENABLE Set false to disable reporting. Default is true.
--api.api_key API__API_KEY The organization API key.
--api.service_key API__SERVICE_KEY Account service key.
--api.url API__URL URL on which to report. Default is https://app.contrastsecurity.com/.
--api.user_name API__USER_NAME Account user name.
--api.proxy.enable [true] API__PROXY__ENABLE If false, no proxy is being used for communication of data.
--api.proxy.url API__PROXY__URL URL of proxy for communicating agent data.
--api.timeout_ms API__TIMEOUT_MS Http timeout value (in ms). Default is 10000.
--api.certificate.enable [false] API__CERTIFICATE__ENABLE If set to false, the certificate configuration in this section will be ignored. (default: false)
--api.certificate.ca_file API__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.
--api.certificate.cert_file API__CERTIFICATE__CERT_FILE Set the absolute or relative path to the Certificate PEM file for communication with Contrast UI.
--api.certificate.key_file API__CERTIFICATE__KEY_FILE Set the absolute or relative path to the Key PEM file for communication with Contrast UI.
--api.certificate.key_password API__CERTIFICATE__KEY_PASSWORD If the Key file requires a password, set it here.
--api.certificate.ignore_cert_errors [true] API__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.enable [false] AGENT__AUTO_UPDATE__ENABLE 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__STACKTRACE_LOGGING__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.
--agent.route_coverage.enable [true] AGENT__ROUTE_COVERAGE__ENABLE If false, do not send route-base coverage data to the Contrast UI. Default is true.
--agent.security_logger.level AGENT__SECURITY_LOGGER__LEVEL Set the log level for security logging. Valid options are alert, crit, err, warning, notice, info and debug.
--agent.security_logger.path AGENT__SECURITY_LOGGER__PATH Set the file to which the agent logs security events.
--agent.service.enable AGENT__SERVICE_ENABLE Set to false to disallow the service to be started, and effectively disable the agent, if read by the service. If the agent reads this property, it disallows service auto-start.
--agent.service.socket AGENT__SERVICE_SOCKET If this property is defined, the service is listening on a Unix socket at the defined path. Example: /tmp/service.sock
--agent.service.host AGENT__SERVICE_HOST Set the the hostname or IP address of the Contrast service to which the Contrast agent should report.
--agent.service.port AGENT__SERVICE_PORT Set the the port of the Contrast service to which the Contrast agent should report. Example: 30555
--agent.service.logger.path AGENT__SERVICE__LOGGER_PATH Set the location to which the Contrast service saves log output. If no log file exists at this location, the service creates one. Example: /opt/Contrast/contrast_service.log will create a log in the /opt/Contrast directory.
--agent.service.logger.level AGENT__SERVICE__LOGGER_LEVEL Set the the log output level. Value options are ERROR, WARN, INFO, and DEBUG.
--application.args APPLICATION__ARGS String containing args to pass verbatim to the application. (E.g., --application.args "-A -S -D -F foo bar".)
--application.code APPLICATION__CODE Add the application code this application should use in the Contrast UI.
--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.metadata APPLICATION__METADATA Comma-separated list of key=value pairs that are applied 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.
--assess.enable [false] ASSESS__ENABLE If false, disable assess mode. Default is true.
--assess.tags ASSESS__TAGS Comma-separated list of tags to apply to each application vulnerability reported by the agent.
--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.environment SERVER__ENVIRONMENT Environment in which the server is running - QA, PRODUCTION or DEVELOPMENT (case insenstive); does not affect servers that already exist in api.
--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.
-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