Before you begin the process of setting up Contrast, explore the requirements, processes and benefits to including it in your current workflows.
The Contrast application for Enterprise-on-Premises (EOP) is designed for ease of deployment and simplicity of configuration. EOP customers must only set up the central Contrast application once per organization.
Contrast strongly advises the use of Contrast's Software as a Service (SaaS) product. It’s SOC-2 Type II compliant, and gets security and feature updates as they become available. To connect to SaaS mode, follow the instructions provided to your administrator. These instructions also contain the credentials you need to log in to the Contrast application. SaaS customers can go the following section on Agents for the appropriate installation instructions.
Using Assess, Protect or both as an EOP customer requires two installations:
The installation contains all embedded components that make up the system configuration. These components include a Tomcat servlet container, MySQL database instance, and an AdoptOpenJDK Hotspot Java Virtual Machine. All of these components are embedded within the installation binary and deployed to a single server as part of the Contrast architecture.
As you prepare to install Contrast in your own environment, verify that your configuration complies with Contrast's system requirements and sizing requirements. You can also update Java options, and take advantage of Contrast logs and tools when you run Contrast on Windows or Linux.
To access configuration options, log in to the Administrative interface (/Contrast/superadmin/login.html). The bulk of the application's configuration is handled here. You can configure and update authentication settings from a variety of authentication providers, including Microsoft Active Directory, LDAP and Single Sign-On. Contrast can also be configured to automatically create a MySQL backup of the database on a regular, scheduled basis.
Begin onboarding applications by choosing an application server that you want Contrast to analyze. You can then download and install the Contrast agent that's right for you.
To connect to Contrast agents, install an agent into your web application server. Contrast inventories all included servers, applications in each run, vulnerabilities in each application, and CVEs in each library used by each application.
The Java agent analyzes the behavior of Java web applications running on your container of choice.
The .NET Framework agent analyzes the behavior of .NET web applications running on IIS as users interact with these applications.
The .NET Core agent instruments and analyzes applications running in the .NET Core runtime.
The Node agent analyzes the behavior of Node.js web applications by using established techniques, such as source-to-source compilation, to intercept and add Contrast's sensors to an application prior to execution.
The Ruby agent provides runtime protection of Ruby on Rails web applications.
The Python agent provides runtime protection of Django, Flask and Pyramid web applications.
The Contrast application for Enterprise on Premises (EOP) includes a Tomcat servlet container, a MySQL database instance and an AdoptOpenJDK Hotspot Java Virtual Machine. All of these components are embedded within the installation binary and deployed to a single server as part of the Contrast architecture. You should prepare the following prior to installing the application:
|OS Architecture||64-bit||64-bit||Due to memory requirements, the Contrast application can only run on 64-bit architectures.|
||Any modern Operating System should run Contrast. Contrast officially supports the following:
|MySQL||5.7||5.7.23||Contrast currently runs 5.7.23 in AWS. Contrast doesn't anticipate any issues if you run a different build of MySQL 5.7; if you do experience an issue, please open a Support ticket. MySQL versions 8 and higher are currently not supported|
To run Contrast, you must preconfigure your base operating system with a shared library for running MySQL. Depending on which operating system you deployed with Contrast, follow the installation options below:
Customers running Centos or RHL:
[contrast@myserver ~]# yum install libaio
Customers running Ubuntu or Debian:
[contrast@myserver ~]# apt-get install libaio1 libaio-dev
Customers running Windows will need Visual C++ Redistributable Packages for Visual Studio 2013. MySQL added this as a requirement as part of the MySQL 5.7.18 release.
Contrast is designed for a scale-up architecture with an emphasis on providing more compute (vCPU) and memory resources for customers like you. The CPU and memory resources for Contrast can vary based on the number of agents connected and application traffic communicating back to the Contrast application. Two additional factors that also impact performance:
Web traffic from consumers of Contrast reporting data. Contrast is a highly transactional system that presents calculated and real-time data sets back to consumers of the data. As more users interface with the system, the greater the demand for compute and memory.
Large amounts of data maintained in the application over extended periods of time. You can proactively purge data over time or choose to keep the data. With any transactional system, the larger the data set to query against, the greater the compute requirements.
Contrast supports a wide selection of configurations, which are comprised of varying combinations of CPU, memory and storage capacity to fit different deployment scenarios. These configurations give you the flexibility to choose the appropriate mix of resources for your applications, and allows you to scale resources to the requirements of your target workload.
TS1 configurations are designed for small workloads of one to three agents communicating to Contrast, or a single application agent for a small team of end users. A small contingent of web traffic end users - about one to five - may use the system periodically, during specific training sessions or for demonstration purposes with team members.
TS1 configurations provide a baseline level of CPU performance, but are flexible enough to scale to increasing compute and memory requirements. They are designed for small workloads that don’t use the full CPU capacity to be handling in-bound traces constantly or sustain large web traffic.
|~2||2.5GHz to 3.3GHz||16GB||100GB|
TS2 configurations are recommended for workloads of three to thirty agents communicating to Contrast and larger web traffic of users - about five to twenty five end users. Agents typically run constantly and transport findings to Contrast. End users access the system multiple times of day, and actively engage in Contrast features such as alerts, reports and integrations including Active Directory, LDAP and Issue Tracking Systems.
TS2 configurations provide a suitable level of performance for most deployments fitting the workloads described above. They are designed for typical workloads and scenarios within Contrast. The greater the number of connected agents, the greater the memory requirements are for Contrast to handle inflight traces. Storage depends on the life of trace data and the preservation of log files by system administrators.
|~4 to ~8||2.5GHz to 3.3GHz||16GB to 24GB||100GB to 200GB|
TS3 configurations are intended for larger workloads of 30 to more than 100 agents communicating to Contrast and larger web traffic of users for full-scale enterprise deployments. Agents are connected at all times and transporting findings to Contrast. End users access the system multiple times of day, and actively engage in Contrast features such as alerts, reports and integrations including Active Directory, LDAP and Issue Tracking Systems.
TS3 configurations provide a high degree of performance and scalability for most deployments fitting the workloads described above. The greater the number of connected agents and end users, the greater the memory requirements for Contrast to handle inflight traces. Storage depends on the life of trace data and the preservation of log files by system administrators. Taking advantage of the Crawler microservice requires an extra storage demand.
|~8 to ~16||2.5GHz to 3.3GHz||24GB to 48GB||200GB to 500GB|
In Windows, Contrast is installed as a system service. You can start and stop the service through the Windows Service Manager application.
The Contrast daemon is registered as an
init.d daemon. Starting and stopping the server should be done by invoking:
service contrast-server <start|stop|restart|status>
To start the Contrast server independently of the parent shell, execute:
nohup /path/to/installation/contrast/bin/contrast-server start >/dev/null 2>1
If you need to change the Java Virtual Machine (JVM) settings for your Contrast server instance, you can open the file $CONTRAST_HOME/bin/contrast-server.vmoptions. This file contains standard JVM parameters that are passed to the underlying virtual machine when the Contrast server process starts. For example, if you want to update the server to allow more heap memory usage, you could update the -Xmx setting to a different value.
Contrast has several logs that each store different information. The log files and their purposes are shown in the table below:
|audit.log||Logs audit events such as successful/failed login attempts|
|console.log||Default application event log|
|contrast-error.log||Logs messages printed to
|contrast-stdout.log||Logs messages printed to
|contrast.log||Primary application log|
|esapi.log||Captures security events|
|windward.log||Captures reporting server events|
Contrast comes with various utilities that you can run from the command line to assist with performing maintenance, managing encrypted properties files and performing backups of the database.
You may need to access the values of encrypted properties files outside of the application interface, or automate the updating of some property such as automated bind password rotation. Using the encrypted properties editor is a powerful way to perform these types of operations.
The encrypted properties editor binary is located at $CONTRAST_HOME/bin/edit-properties. As an interactive property editor, invoking it is as simple as providing the path to your ESAPI configuration and the file that needs work.
$CONTRAST_HOME/bin/edit-properties -e $CONTRAST_HOME/data/esapi -f $CONTRAST_HOME/data/conf/ad.properties
This opens an interactive application that allows you to update the values of properties. You can also retrieve the unencrypted value of a property - like a shell script to back up the database - by passing another parameter to the tool:
$CONTRAST_HOME/bin/edit-properties \ -e $CONTRAST_HOME/data/esapi \ -f $CONTRAST_HOME/data/conf/database.properties \ -p jdbc.username \ -o
Update the value of a property in the file by passing a different set of arguments:
$CONTRAST_HOME/bin/edit-properties \ -e $CONTRAST_HOME/data/esapi \ -f $CONTRAST_HOME/data/conf/database.properties \ -p jdbc.username \ -v joe.blow \ -c "Updating JDBC Password"
Get help by executing edit-properties with no arguments:
$ bin/edit-properties usage: property-editor -c,--comment <text> The comment for the top of the file -e,--esapi <path> The path to the ESAPI.properties file -f,--targetFile <file> The properties file to edit -o,--print-value Print out the value of the property and exit -p,--property <name> The name of the property to set -v,--value <val> The value of the property
As an EOP administrator, you can configure Contrast to automatically create a MySQL backup of the database on a regularly scheduled basis. During installation, you're prompted that you can make a backup of the database; and, if you want to do so, you can define a time and location for storing it. Most customers configure backups during installation. However, if you decide to skip over this step, you can configure Contrast post-installation to schedule database backups.
Note: EOP administrators can also run a packaged tool to back up the database.
You can find Contrast database settings in $CONTRAST_HOME/data/conf/database.properties. This file is encrypted by default and requires use of the encrypted property editor to identify database settings. The example below shows that database backups are enabled, scheduled and have a specific location. You can edit these properties if any specific settings need to change.
contrast@TeamServer:~/contrast/bin$ ./edit-properties -e ../data/esapi/ -f ../data/conf/database.properties database.bk.time : 4:0:0 database.bk.enabled : true database.bk.dir : /mnt/backups/mysql/contrast
You may want to take fresh backups of your MySQL system prior to an upgrade to capture any data created or changed since the last scheduled backup. In order to take backups, the user executing the script must have permission to run the script. (This is typically the owner of the installation for a Contrast, Root or a Windows Administrator account.) Contrast must be up and running, and MySQL needs to be available. Finally, the database backup location
database.bk.dir must be configured.
The tool to take a backup is an interactive script. You must run it from a command line for both Linux and Windows.
To run on Linux:
To run on Windows:
If you need to restore a database backup, Contrast provides the necessary steps to reliably perform this operation. Database restoration should be performed by a MySQL Database Administrator.
./mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema>
mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema>
drop database <jdbc.schema>;.
create database <jdbc.schema>;.
GRANT ALL PRIVILEGES ON *.* to 'contrast'@'%';.
./mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema> < <backup_location>/<backup_filename>
mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema> < <backup_location>/<backup_filename>
Automated backups are scheduled through
crontab on Linux and
schtasks on Windows. To disable automated
backups, follow the instructions for your installation.
To disable backups on Linux, complete the following steps:
crontab -l. This lists the job, and should result in
0 2 * * * /usr/local/contrast/bin/backup-db.sh.
crontab -eto delete a single backup.
crontab -rto delete all backup(s).
-roption deletes everything, so be careful when using it. The
-eoption allows edits with Vim.
To disable backups on Windows, use Task Scheduler to disable or delete
Start using Contrast by identifying an application server that you want Contrast to analyze. You can choose any of the following types:
Log into the Contrast interface using your Organization Admin (not SuperAdmin) account. Your username and password are the same as the Contrast Hub credentials that you used to download the installer and license.
Click on the Add Agent button to start the agent download and installation wizard. Follow the on-screen instructions to configure and download the appropriate agent for the application server that you're enabling.
Follow the on-screen instructions to add the agent to your application server. Once you restart the application server, the Contrast agent should start and immediately connect to the Contrast application. If this doesn't happen, something may be preventing the agent from communicating with the application. The most common causes and solutions are:
Note: Each application in the same organization must have an unique name. If multiple applications have the same name, Contrast incrementally appends each instance of the display name [e.g., App1, App1 (1), App1 (2)].
Browse the applications on the application server with Contrast enabled - just click through a few pages and forms - to generate enough activity for good information on your application inventory and dashboard. You can check that Contrast is working by returning to the Dashboard of your Contrast interface to review results. From this point forward, you have an up-to-date application security dashboard for all the applications on that application server.
Some of Contrast's products, including the Proxy agent, are distributed through Linux packages. This makes installation and updates very easy and familiar as it utilizes the Linux packaging and distribution system.
To use the Contrast package repository, you must configure your package management system to include the appropriate reference. While most Contrast packages are tied to the specific Linux distribution you're using, some are applicable to any distribution. The following steps for Ubuntu and RedHat/CentOS users configure both distribution points; once configured, you will have access to all our Linux-packaged products.
This is a one-time configuration step. Once it's done, you're connected to the Contrast software distribution pipeline, and can solely manage it through your distribution's package manager. If you already completed this step, the appropriate repository definition file will be present:
Note: Some Linux package managers need a public GPG key that's used to verify the signed packages from our repository; this is included in the configuration steps, if it's applicable to your system.
To verify which version of Ubuntu you're running, run
cat /etc/os-release. Once you determine your Ubuntu version, copy and paste one of the following scripts to your command line to set up the appropriate Linux repository for your version.
curl https://contrastsecurity.jfrog.io/contrastsecurity/api/gpg/key/public | sudo apt-key add - echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ bionic contrast" | sudo tee /etc/apt/sources.list.d/contrast.list echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ all contrast" | sudo tee -a /etc/apt/sources.list.d/contrast.list sudo apt-get update
curl https://contrastsecurity.jfrog.io/contrastsecurity/api/gpg/key/public | sudo apt-key add - echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ xenial contrast" | sudo tee /etc/apt/sources.list.d/contrast.list echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ all contrast" | sudo tee -a /etc/apt/sources.list.d/contrast.list sudo apt-get update
curl https://contrastsecurity.jfrog.io/contrastsecurity/api/gpg/key/public | sudo apt-key add - echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ trusty contrast" | sudo tee /etc/apt/sources.list.d/contrast.list echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ all contrast" | sudo tee -a /etc/apt/sources.list.d/contrast.list sudo apt-get update
For Red Hat Enterprise Linux (RHEL) and CentOS versions 5, 6 and 7, copy and paste the following single script into your shell to configure your RedHat-based system for Contrast's package repository.
sudo tee /etc/yum.repos.d/contrast.repo <<-"EOF" [contrast] name=Contrast centos-$releasever repo baseurl=https://contrastsecurity.jfrog.io/contrastsecurity/rpm-public/centos-$releasever/ gpgcheck=0 enabled=1 EOF