Quick Start Guide

Before you begin the process of setting up Contrast, explore the requirements, processes and benefits to including it in your current workflows.

About the Contrast Application

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.

Installation for EOP

Using Assess, Protect or both as an EOP customer requires two installations:

  • Central instance of the Contrast application
  • Agent for each web application server

The installation contains all embedded components that make up the system configuration. These components include a Tomcat servlet container, MySQL database instance, Cassandra NoSQL instance and an Oracle 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.

Configuration

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.

Agents

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 agent analyzes the behavior of .NET web applications running on IIS as users interact with these applications.

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

System Requirements

Prepare for the Installation

The Contrast application for Enterprise on Premises (EOP) includes a Tomcat servlet container, a MySQL database instance and an Oracle 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:

  • System with adequate compute and memory resources based on guidance from our sizing recommendations
  • Adherence to the system requirements specified below
  • Installation of the MySQL run-time libraries (Linux Only)

System Requirements

Category Minimum Recommended Description
OS Architecture 64-bit 64-bit Due to memory requirements, the Contrast application can only run on 64-bit architectures.
Operating System
  • Microsoft Windows 2008 R2 64-bit
  • Ubuntu 12.04 LTS
  • Centos 6
  • Microsoft Windows 2012 R2
  • Ubuntu 14.04 LTS
  • Centos 7
Any modern Operating System should run Contrast. Contrast officially supports the following:
  • Ubuntu Linux
  • Debian Linux
  • Redhat Enterprise Linux
  • Centos Linux
  • Windows Server 2008 R2 64-bit
  • Windows 2012 R2
Java 1.8 1.8
MySQL 5.7 5.7.23 MySQL versions 8 and higher are currently not supported

MySQL Shared Libraries

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.

Sizing Recommendations

Overview

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.

Configuration Options

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 configuration

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.

vCPUs Clock Speed RAM Storage
~2 2.5GHz to 3.3GHz 16GB 100GB

TS2 configuration

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.

vCPUs Clock Speed RAM Storage
~4 to ~8 2.5GHz to 3.3GHz 16GB to 24GB 100GB to 200GB

TS3 configuration

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.

vCPUs Clock Speed RAM Storage
~8 to ~16 2.5GHz to 3.3GHz 24GB to 48GB 200GB to 500GB

Use cases for TS3:

  • Advanced use of the Contrast REST API architecture for automation or data extraction purposes.
  • Continuous integration of agents with large automated regression suites.

Running Contrast

The Contrast Service

Running on Windows

In Windows, Contrast is installed as a system service. You can start and stop the service through the Windows Service Manager application.

Running on Linux

Root installation

The Contrast daemon is registered as an init.d daemon. Starting and stopping the server should be done by invoking:

/etc/init.d/contrast-server <start|stop|restart|status>

or

service contrast-server <start|stop|restart|status>

Non-root installation

To start the Contrast server independently of the parent shell, execute:

nohup /path/to/installation/contrast/bin/contrast-server start >/dev/null 2>1

Update Java Options

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 Logs

Contrast has several logs that each store different information. The log files and their purposes are shown in the table below:

Log File Description
audit.log Logs audit events such as successful/failed login attempts
console.log Default application event log
contrast-error.log Logs messages printed to stderr
contrast-stdout.log Logs messages printed to stdout
contrast.log Primary application log
esapi.log Captures security events
windward.log Captures reporting server events

Contrast Tools

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.

Encrypted properties editor

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

Create a MySQL Backup

Get Started

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.

Use the Encrypted Properties Editor

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

Manual Database Backups

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:

$CONTRAST_HOME/bin/backup_db.sh

To run on Windows:

$CONTRAST_HOME\bin\backup_db.cmd

Restore Database Backups

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.

  • Using the encrypted property editor, identify the MySQL database settings.
  • Shut down Contrast.
  • Start up MySQL individually using the MySQL service packaged with Contrast
  • Connect to MySQL
    • On Linux: ./mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema>
    • On Windows: mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema>
  • Drop the Contrast database with drop database <jdbc.schema>;.
  • Create the Contrast database with create database <jdbc.schema>;.
  • Grant permissions to the Contrast user with GRANT ALL PRIVILEGES ON *.* to 'contrast'@'%';.
  • Exit from MySQL.
  • Restore the MySQL backup.
    • Restore on Linux: ./mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema> < <backup_location>/<backup_filename>
    • Restore on Windows: mysql -h <jdbc.host> -P <jdbc.port> -u <jdbc.user> -p <jdbc.schema> < <backup_location>/<backup_filename>
  • Shut down MySQL.
  • Restart the fully restored Contrast and MySQL together.

Disable Automated Backups

Automated backups are scheduled through crontab on Linux and schtasks on Windows. To disable automated backups, follow the instructions for your installation.

Linux

To disable backups on Linux, complete the following steps:

  • Switch to the user which was used to install Contrast and run crontab -l. This lists the job, and should result in 0 2 * * * /usr/local/contrast/bin/backup-db.sh.
  • Run crontab -e to delete a single backup.
  • Run crontab -r to delete all backup(s).

Note: The -r option deletes everything, so be careful when using it. The -e option allows edits with Vim.

Windows

To disable backups on Windows, use Task Scheduler to disable or delete ContrastBackup.

Onboard Applications

Identify an Application Server

Start using Contrast by identifying an application server that you want Contrast to analyze. You can choose any of the following types:

  • Developer's local application server running in the integrated development environment (IDE)
  • Continuous integration application server that's used during the automated testing process
  • Test or QA application server
  • Staging application server
  • Embedded server in an appliance
  • Application server running in a virtual machine
  • Remote application server running in the cloud
  • Production application server
    (Using Contrast earlier in the lifecycle is generally advised.)

Download the Contrast Agent

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.

Install the Agent

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:

  • Firewalls that don't allow traffic to the Contrast application's IP address and port: You need to configure host or network firewall.
  • Web gateways and proxies that require authentication: You can configure this in the agent configuration by returning to the Agent Download page, setting the proper configurations and getting a new agent.
  • Contrast application server URL is misconfigured, so the agent is attempting to communicate with the wrong address. You can change this in the agent configuration, if necessary.

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)].

Test the Configuration

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.

Linux Package Distribution

About Linux Package Distribution

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:

  • Ubuntu/Debian: /etc/apt/sources.list.d/contrast.list

  • Centos/Redhat: /etc/yum.repos.d/contrast.repo

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.

Ubuntu

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.

Ubuntu 18.04: bionic

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

Ubuntu 16.04: xenial

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

Ubuntu 14.04: trusty

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

RedHat/CentOS

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