Java YAML configuration template
Use this template to configure the Java agent using a YAML configuration file. (Learn more about YAML configuration.)
Place your YAML file in the default location:
Unix:
/etc/contrast/java/contrast_security.yamlWindows:
C:/ProgramData/contrast/java/contrast_security.yaml
# ==============================================================================
# Use the properties in this YAML file to configure a Contrast agent.
# Go to https://docs.contrastsecurity.com/en/order-of-precedence.html
# to determine the order of precedence for configuration values.
# ==============================================================================
# Use this setting if you want to temporarily disable a Contrast agent.
# Set to `true` to enable the agent; set to `false` to disable the agent.
# 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
# base64 encoded JSON object containing the `url`,
# `api_key`, `service_key`, and `user_name` config options,
# allowing them all to be set in a single variable.
# token: NEEDS_TO_BE_SET
# Set the timeout for communicating with TeamServer. This property will be
# respected over the deprecated legacy configuration *contrast.timeout*.
# timeout_ms: NEEDS_TO_BE_SET
# ============================================================================
# api.proxy
# Use the following properties for communication
# with the Contrast UI over a proxy.
# ============================================================================
# proxy:
# Set value to `true` for the agent to communicate with
# the Contrast web interface over a proxy. Set value to
# `false` if you don't want to use the proxy. If no value is
# indicated, the presence of a valid **contrast.proxy.host**
# and **contrast.proxy.port** will enable the proxy.
# enable: NEEDS_TO_BE_SET
# Set the proxy host. It must be set with port and scheme.
# host: localhost
# Set the proxy port. It must be set with host and scheme.
# port: 1234
# Set the proxy scheme (e.g., `http` or
# `https`). It must be set with host and port.
# scheme: http
# 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
# Set the proxy user.
# user: NEEDS_TO_BE_SET
# Set the proxy password.
# pass: NEEDS_TO_BE_SET
# Set the proxy authentication type. Value
# options are `NTLM`, `Digest`, and `Basic`.
# auth_type: 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:
# ============================================================================
# agent.diagnostics
# Use the properties in this section to specify the information the agent
# should collect and report in order to diagnose problems in the agent.
#
# ============================================================================
# diagnostics:
# Creates config and system info files
# at startup if true. True by default.
#
# The same thing can be achieved by setting the
# CONTRAST__AGENT__DIAGNOSTICS__ENABLE=[true/false] env variable.
#
# enable: true
# ============================================================================
# agent.route_coverage
# Use the following properties for the route-based coverage feature.
# ============================================================================
# route_coverage: {}
# ============================================================================
# agent.reporting
# Use the following settings to configure reporting to the Contrast UI.
# ============================================================================
# reporting:
# Set the grace period (in milliseconds) after
# agent shutdown to allow draining pending reports.
# shutdown_grace_period_ms: 120000
# ============================================================================
# agent.effective_config
# None
# ============================================================================
# effective_config:
# ==========================================================================
# agent.effective_config.reporting
# None
# ==========================================================================
# reporting:
# Defaults to `true`. Controls whether configuration
# setting reports are sent to the Contrast web interface.
# enable: true
# ============================================================================
# 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: INFO
# Set to `true` to redirect all logs to
# `stdout` instead of the file system.
# stdout: false
# Set to `true` to redirect all logs to `stderr` instead of
# the file system. May be combined with the corresponding
# `stdout` configuration to write to both streams.
# stderr: false
# Change the Contrast logger from a file-sized based rolling scheme
# to a date-based rolling scheme. At midnight server time, the
# previous day log is renamed to *file_name.yyyy-MM-dd*. Note -
# this scheme does not have a size limit; manual log pruning is
# required. You must set this flag to use the backups and size flags.
# roll_daily: false
# Set the roll size for log files in megabytes. The agent will
# attempt to prevent the log file from being larger than this size.
# roll_size: 100
# Set the number of backup files to keep. Set to `0` to disable.
# backups: 10
# ============================================================================
# agent.security_logger
# Define the following properties to set security logging
# values associated with Protect. 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
# Change the Contrast security logger from a file-sized based rolling
# scheme to a date-based rolling scheme. At midnight server time,
# the log from the previous day is renamed to *file_name.yyyy-MM-dd*.
# Note - this scheme does not have a size limit; manual log
# pruning will be required. This flag must be set to use the
# backups and size flags. Value options are `true` or `false`.
# roll_daily: NEEDS_TO_BE_SET
# Specify the file size cap (in MB) of each log file.
# roll_size: NEEDS_TO_BE_SET
# Specify the number of backup logs that the agent will create before
# Contrast cleans up the oldest file. A value of `0` means that no backups
# are created, and the log is truncated when it reaches its size cap.
#
# Note - this property must be used with
# `agent.security_logger.roll_daily=false`; otherwise,
# Contrast continues to log daily and disregard this limit.
#
# backups: NEEDS_TO_BE_SET
# ==========================================================================
# 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: 19
# Set the log level of Exploited attacks. Value options are `ALERT`,
# `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
# severity_exploited: ALERT
# Set the log level of Blocked attacks. Value options are `ALERT`,
# `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
# severity_blocked: NOTICE
# Set the log level of Blocked At Perimeter
# attacks. Value options are `ALERT`, `CRITICAL`,
# `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
# severity_blocked_perimeter: NOTICE
# Set the log level of Probed attacks. Value options are `ALERT`,
# `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
# severity_probed: WARNING
# Set the log level of Suspicious attacks. Value options are `ALERT`,
# `CRITICAL`, `ERROR`, `WARNING`, `NOTICE`, `INFO`, and `DEBUG`.
# severity_suspicious: WARNING
# ========================================================================
# agent.security_logger.syslog.heartbeat
# Define the following properties to
# set the Syslog heartbeat properties.
# ========================================================================
# heartbeat:
# Set to `true` to enable the Syslog heartbeat.
# The heartbeat will issue a Syslog message at
# the INFO level after every interval passes.
# enable: false
# Set the interval for sending heartbeat messages
# to the Syslog server (in milliseconds).
# interval_ms: 60000
# ============================================================================
# agent.java
# The following properties apply to any Java agent-wide configurations.
# ============================================================================
# java:
# Configure the Java agent to skip its application discovery
# algorithm, and instead associate all libraries, vulnerabilities,
# and web traffic to a single application with the name specified
# by this property. This configuration is preferred when deploying
# Java SE applications with embedded web servers (e.g., applications
# built with Spring Boot, Dropwizard, and embedded Jetty). When used
# with an application server, this configuration associates all
# web traffic with the single, standalone application, including
# web traffic handled by application server-hosted endpoints that
# would not be associated with a discovered application otherwise.
#
# Note - This settings takes preferences
# over the `application.name` setting.
#
# standalone_app_name: NEEDS_TO_BE_SET
# By default, the Java agent visits all classes at startup to look
# for vulnerabilities, which the agent may detect by scanning a
# class (e.g., hardcoded passwords). Set this property to `false`
# to disable the default behavior. If disabled, the agent will
# only visit classes which are likely to require sensors; this
# can improve application startup time, but may produce fewer
# findings (most likely findings that require static analysis).
#
# scan_all_classes: true
# By default, the Java agent deeply inspects all JAR and WAR files loaded
# by the JVM to build a comprehensive understanding of the type hierarchy.
# This understanding allows Contrast to instrument sensors into types
# that it might have overlooked. In most cases, this produces a slight
# increase in accuracy at the cost of increased application startup
# time. Set this property to `false` to disable this level of inspection.
#
# scan_all_code_sources: true
# ==============================================================================
# inventory
# Use the properties in this section to override the inventory features.
# ==============================================================================
# inventory:
# Set to `false` to disable inventory features in the agent.
# enable: true
# Define a list of directories where libraries are stored.
# Directories must be formatted as a semicolon-delimited
# list for Windows or a colon-delimited list for Linux.
#
# Define a list of directories where libraries are stored.
# Directories must be formatted as a semicolon-delimited list.
# Example - `path1;path2;path3`(Windows) or `path1:path2:path3`(Linux)
# Example - `path1;path2;path3`
#
# library_dirs: NEEDS_TO_BE_SET
# Set the maximum archive unpacking depth when analyzing libraries.
# library_depth: 10
# Set the boolean to more aggressively limit the
# manifest information reported for libraries. If true,
# the limit is 1,000 characters, otherwise it's 3,000.
# prune_package_details: true
# Apply a list of labels to libraries. Labels
# must be formatted as a comma-delimited list.
# 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: false
# Control the values captured by Assess vulnerability events. `Full`
# captures most values by calling ToString on objects, which can
# provide more info but causes increased memory usage. `Minimal`
# has better performance as it only captures String type objects
# as strings and uses type name for other object type values.
# event_detail: minimal
# Apply a list of labels to vulnerabilities and preflight
# messages. Labels must be formatted as a comma-delimited list.
# Example - `label1, label2, label3`
#
# tags: NEEDS_TO_BE_SET
# ============================================================================
# assess.sampling
# Use the following properties to control sampling in the agent.
# ============================================================================
# sampling:
# Set to `true` to enable sampling.
# enable: false
# This property indicates the number of requests
# to analyze in each window before sampling begins.
# baseline: 5
# This property indicates that every *nth*
# request after the baseline is analyzed.
# request_frequency: 10
# This property indicates the duration for which a sample set is valid.
# window_ms: 180_000
# ============================================================================
# assess.rules
# Use the following properties to control simple rule configurations.
# ============================================================================
# rules:
# Define a list of Assess rules to disable in the agent. To view a
# list of rule names, in Contrast go to user menu > Policy Management >
# Assess rules. The rules must be formatted as a comma-delimited list.
#
# Example - Set `reflected-xss,sql-injection` to disable
# the reflected-xss rule and the sql-injection rule.
#
# disabled_rules: NEEDS_TO_BE_SET
# ==============================================================================
# profile
# Set configuration values under a profile name to enable
# multi-tenant application configuration on web servers. See
# https://support.contrastsecurity.com/hc/en-us/articles/360052187171-Multi-Application-configuration-with-Contrast-Profiles
# for more details.
# ==============================================================================
# profile: {}
# ==============================================================================
# protect
# Use the properties in this section to override Protect features.
# ==============================================================================
# protect:
# Include this property to determine if the Protect
# feature should be enabled. If this property is not
# present, the decision is delegated to the Contrast UI.
# enable: false
# ============================================================================
# protect.rules
# Use the following properties to set simple rule configurations.
# ============================================================================
# rules:
# Define a list of Protect rules to disable in the agent. To view a
# list of rule names, in Contrast go to user menu > Policy Management >
# Protect rules. The rules must be formatted as a comma-delimited list.
# disabled_rules: NEEDS_TO_BE_SET
# ==========================================================================
# protect.rules.bot-blocker
# Use the following selection to configure if the
# agent blocks bots. Set to `true` to enable blocking.
# ==========================================================================
# bot-blocker:
# Set to `true` for the agent to block known bots.
# enable: false
# ==========================================================================
# protect.rules.sql-injection
# Use the following settings to configure the sql-injection rule.
# ==========================================================================
# sql-injection:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or off.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# Tell the agent to detect when semantic analysis of the query
# reveals tautologies used in exfiltration attacks (e.g., "or
# 1=1" or "or 2<>3"). The agent blocks if blocking is enabled.
# detect_tautologies: false
# Tell the agent to detect when semantic analysis of the query
# reveals the invocation of dangerous functions typically used in
# weaponized exploits. The agent blocks if blocking is enabled.
# detect_dangerous_functions: false
# Tell the agent to detect when semantic analysis of the query
# reveals chained queries, which is uncommon in normal usage but
# common in exploit. The agent blocks if blocking is enabled.
# detect_chained_queries: false
# Tell the agent to detect when semantic analysis of the query
# reveals database queries are being made for system tables and
# sensitive information. The agent blocks if blocking is enabled.
# detect_suspicious_unions: false
# Tell the agent to be more aggressive in detecting user
# inputs as SQL comments. This enables the agent to better
# detect SQL Injection input vectors that use comments to
# terminate queries. The agent blocks if blocking is enabled.
# aggressive_comment: false
# ==========================================================================
# protect.rules.cmd-injection
# Use the following properties to configure
# how the command injection rule works.
# ==========================================================================
# cmd-injection:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or `off`.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# Detect when the agent sees user parameters being executed as
# system commands. The agent blocks if blocking is enabled.
# detect_parameter_command_backdoors: true
# Detect when a system command is issued which contains
# chained commands. The agent blocks if blocking is enabled.
# detect_chained_commands: true
# Detect when a system command is issued with an argument matching a
# known dangerous file path. The agent blocks if blocking is enabled.
# detect_dangerous_path_args: true
# Tell the agent to detect when commands come directly
# from input. The agent blocks if blocking is enabled.
# detect_phased_commands: true
# ==========================================================================
# protect.rules.cmd-injection-process-hardening
# Use the following settings to configure whether
# the agent blocks all attempts to start an external
# process. To enable blocking, set to 'true'.
# ==========================================================================
# cmd-injection-process-hardening:
# Set to `true` to enable the agent to block
# all attempts to start external processes.
# enable: false
# ==========================================================================
# protect.rules.path-traversal
# Use the following properties to configure
# how the path traversal rule works.
# ==========================================================================
# path-traversal:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or `off`.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# Detect when custom code attempts to access sensitive
# system files. The agent blocks if blocking is enabled.
# detect_custom_code_accessing_system_files: true
# Detect when users attempt to bypass filters by
# using "::$DATA" channels or null bytes in file
# names. The agent blocks if blocking is enabled.
# detect_common_file_exploits: true
# ==========================================================================
# protect.rules.method-tampering
# Use the following properties to configure
# how the method tampering rule works.
# ==========================================================================
# method-tampering:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or `off`.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# ==========================================================================
# protect.rules.reflected-xss
# Use the following properties to configure how
# the reflected cross-site scripting rule works.
# ==========================================================================
# reflected-xss:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or `off`.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# ==========================================================================
# protect.rules.xxe
# Use the following properties to configure
# how the XML external entity works.
# ==========================================================================
# xxe:
# Set the mode of the rule. Value options are
# `monitor`, `block`, `block_at_perimeter`, or `off`.
#
# Note - If a setting says, "if blocking is enabled",
# the setting can be `block` or `block_at_perimeter`.
#
# mode: off
# ==========================================================================
# protect.rules.padding-oracle
# Use the following properties to configure
# how the padding-oracle rule works.
# ==========================================================================
# padding-oracle: {}
# ==============================================================================
# application
# Use the properties in this section for
# the application(s) hosting this agent.
# ==============================================================================
# application:
# Override the reported application name.
#
# Note - On 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.
#
# 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
# 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 settings in this section to set metadata for the server
# hosting this agent. Contrast recognizes common, supported server
# names, paths, types and environments. Doing this may require a new
# server or license, and it may affect functionality of some features.
# ==============================================================================
# server:
# Override the reported server name.
# name: localhost
# Override the reported server path.
# path: NEEDS_TO_BE_SET
# Override the reported server type.
# type: NEEDS_TO_BE_SET
# Set the environment directly to override the default set
# by the Contrast UI. This allows the user to configure the
# environment dynamically at startup rather than manually
# updating the Server in the Contrast UI themselves afterwards.
#
# Valid values include `QA`, `PRODUCTION` and `DEVELOPMENT`.
# For example, `PRODUCTION` registers this Server as
# running in a `PRODUCTION` environment, regardless of the
# organization's default environment in the Contrast UI.
#
# environment: NEEDS_TO_BE_SET
# 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
# Set to `false` to disable detection of cloud
# provider metadata such as resource identifiers.
# discover_cloud_resource: true