Overview

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

Installation

Using Assess, Protect or both requires two installations:

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

We strongly advise the use of Contrast Software as a Service (SaaS). 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.

The Contrast application for Enterprise on Premises (EOP) is designed for ease of deployment and simplicity of configuration. 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.

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.7.0_80 1.7.0_80 or greater
MySQL 5.6.28 5.6.33 MySQL versions 5.7 and higher are currently not supported

MySQL Shared Libraries

To run Contrast, you must preconfigure your base operating system on Linux with a shared library for running MySQL. Depending on which flavor of Linux 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

Sizing Requirements

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 as part of the initial analysis of Contrast during a “Proof of Concept” exercise 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 with a sales engineer 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 4GB 30GB

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 8GB to 12GB 50GB to 100GB

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 16GB to 24GB 100GB 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.

C1 configuration

C1 configurations are recommended for Enterprise on Premises (EOP) customers deploying the Crawler microservice. The compute, resource and storage requirements are minimal for the Crawler.

Most Crawler installations are suitable to run on a single vCPU. However, crawling performance improves with at least two vCPUs. Memory can be configured for the Crawler processes, which are both a Java Virtual Machine and PhantomJS process. Storage is only needed during the crawling operation. Once crawling is complete, the results of the crawling exercise are transferred to the Contrast.

Note: If you use the Crawler service, you'll need more storage for Crawler results.

Contrast advises EOP customers who are implementing Crawler to run on different systems than their Contrast application. While most Contrast deployments can support the additional compute and resource requirements, Contrast still recommends running this service on a different server. Crawler can be configured to run on multiple servers for parallel crawling operations.

vCPUs Clock Speed RAM Storage
~1 to ~2 2.5GHz to 3.3GHz 2GB Less than 10GB

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
    • 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 Applications tab and then the Add Application 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.

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.

New Customer Implementation Guide

Introduction

This guide is a reference for the technical and non-technical parties involved in integrating Contrast to automatically Assess and Protect software and improve performance of existing workflows at your company. As you follow these steps, Contrast’s Customer Success representatives will continue to shepherd you through the setup and onboarding process. Overviews of features and workflows in Contrast include links to documentation and resources with additional details.

Roles and Responsbilities

Designate people for each of the following roles. Your Contrast Security Certified Professional (CSCP) representative needs to be in touch with each of them.

Internal:

Role Description
Project Manager
(often the Security Lead)
Oversee project
Copied on every email
Contrast Admin SaaS and EOP:
Create and delete users
Configure roles
Contrast administration
EOP only:
Perform upgrades and DB backup
Manage infrastructure
Security Lead Create and maintain security policies
Produce success metrics
Development Lead
(for each application)
Oversee agent installation
Perform initial review of results
Triage vulnerabilities
Serve as a lead in vulnerability remediation

At Contrast:

Role Description
CSCP Representative Oversee project
Conduct training
Help deploy
Tune and tailor Contrast application

Installation

Using Assess, Protect or both requires two installations:

  1. Central instance(s) of the Contrast application
  2. Agent for each web application server

The Contrast application

We strongly advise the use of Contrast's Software as a Service (SaaS). It’s SOC-2 Type II compliant, gets security and feature updates as they become available, and is load balanced by professionals who focus on this every day.

If SaaS is an option, please read about six benefits of using the SaaS option versus having Enterprise on Premises (EOP). However, if a multi-tenancy environment isn't feasible, the EOP option is right for you.

Saas

To connect to the SaaS offering of Contrast, follow the instructions that are emailed to your Contrast Admin. They include your credentials to log in to the Contrast application.

EOP

To install Contrast in your own environment, we’ll do the following together.

  1. Verify that your configuration complies with those that are supported and suggested, which is documented in the System Requirements article.
  2. Follow the steps listed in the Contrast Installation article.

Before we begin, make sure that the CSCP knows the contact information for your Contrast Admin and for your Security Lead.

Administration

Read more about configuring System Settings, including the role of SuperAdmin.

Agents

Include the agent on all of your web application servers. Contrast inventories all included servers, applications in each run, vulnerabilities in each application, and CVEs in each library used by each application. This unlimited inventory mode is included for free with Contrast and doesn’t require a license.

To install the Contrast agent into an application web server, we’ll do the following together:

  1. Verify that your configuration complies with those that are supported and suggested, which is documented in the following articles for each agent:

  2. Complete the installation process for the agent.

Before we begin, make sure that the CSCP knows the contact information for your Security Lead and the Development Lead for each web application server.

Security Controls and Exclusions

The Contrast agent recognizes a wide range of popular security controls out of the box. If your development teams are using any custom security libraries for validation or sanitization, follow the steps in Security Controls to teach Contrast about them and fine tune your findings.

You may also have situations in which you don't want to hear about events for one reason or another – usually because there's a compensating control that isn't visible from the application perspective. Find details on suppressing these findings in Application Exclusions.

Integrations

Contrast has an ecosystem of optional integrations - and, of all the bugtrackers that we support, JIRA is the most popular.

Note: You can set up these configurations after including Contrast in your processes.

Get Started

With everything in place, it’s time to include Contrast in your existing workflow. We’ll do the following together:

Before we begin, make sure that the CSCP knows the contact information for your Contrast Admin, Security Lead and Development Lead for each web application server. If other people (e.g., JIRA Administrator or Software Developers) will be involved, your CSCP needs their contact information as well.

People

Before turning on licenses, your CSCP will arrange the following trainings.

Administrator training:

  • How to set up user groups and their access
  • Monitoring and combining applications
  • When and how to access log files
  • How to integrate with other applications and other administrative tasks

To prepare for the meeting, attendees should review the instructions on Contrast Configuration.

User training:

  • How to access information about your applications
  • How to explore a finding
  • Other tasks relevant to a security professional or a technical user performing security analysis

To prepare for the meeting, attendees should review the steps in the Quick Start Guide for new users.

Products

There are many ways to start using Assess, Protect or both. To get value quickly, use Assess in your continuous integration (CI) pipeline as part of the functional test environment. Also use Protect in Monitor mode in your penetration testing environment before adding it to your Production environments. Consider the following scenarios before discussing what works best for you with your CSCP.

Assess

Start by turning on Assess licenses for all applications in a QA environment. While QA performs their regular tests - even ones that are automated - Assess monitors data flows through the application and finds vulnerabilities. Include these security issues in your bug tracker, treating them like other finding. Assess requires some tuning, especially if you use custom libraries or methods to mitigate security vulnerabilities. Once you’re comfortable with how this works, include Assess in Development servers and then deployment web servers, even if they don’t have any active licenses.

Protect

Start by turning on Protect for an application being attacked as part of a security assessment. By default, all Protect rules are in Monitor mode. Notice which attacks Protect is able to rebuff and log. Based on your environment and requirements, teach Protect about any IPs that should be implicitly trusted and added to the Trusted Hosts list, or automatically blocked and added to the Blacklist. Begin to switch any appropriate rules to Block mode in order to make your applications self protecting. Once you’re comfortable with this workflow, include Protect in deployment web servers.

APIs

Contrast includes APIs to give programmatic access to a myriad of features and functions. The APIs, return objects and flows for using APIs and objects are available on the Contrast RESTful API page.

Access to APIs is included with your access to Contrast. Ask your CSCP for suggestions on which APIs to use to create your intended workflow. They can also help you scope any professional services that may help you.

Metrics

Schedule meetings with your CSCP to track metrics that are important to you. For each application, consider the following metrics. They can be monitored from the Contrast dashboard and Attacks pages.

Assess:

  • Custom Code Score (Number of vulnerabilities discovered)
  • Library Score (Number of CVEs in the libraries you use)
  • Score in Vulnerability Trend
  • Average Time to Remediate
  • Licenses Used

Protect:

  • Attacks Seen
  • Attacks Blocked
  • Number of Protect servers
  • Number of Monitored applications
  • Applications at Risk
  • Licenses Used

Go Live

You’re ready to start with your first tranche of applications to Assess and Protect. (Review the Quick Start Guide one more time, just for good measure.)

Review

After each application is onboarded, your CSCP will hold the following meetings to ask a few questions.

Day One

  • Is everything working?

Week One

  • Is everything working?
  • What are you finding (i.e., metrics)?
  • What tuning would improve results?

Month One

  • What are you finding (i.e., metrics)?
  • What tuning would improve results?

Month Two

  • What are you finding (i.e., metrics)?
  • What tuning would improve results?
  • What application(s) should you bring on next?

Month Three (and every three months afterward)

  • What are you finding (i.e., metrics)?
  • What tuning would improve results?
  • What application(s) should we bring on to Assess and/or Protect next?
  • What improvements can be made to the product?