Before you begin the process of setting up Contrast, explore the requirements, processes and benefits to including it in your current workflows.
Using Assess, Protect or both requires two installations:
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.
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 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 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:
|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:
|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|
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
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 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.
|~2||2.5GHz to 3.3GHz||4GB||30GB|
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||8GB to 12GB||50GB to 100GB|
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||16GB to 24GB||100GB to 500GB|
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.
|~1 to ~2||2.5GHz to 3.3GHz||2GB||Less than 10GB|
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 Applications tab and then 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:
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.
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.
Designate people for each of the following roles. Your Contrast Security Certified Professional (CSCP) representative needs to be in touch with each of them.
(often the Security Lead)
Copied on every email
|Contrast Admin||SaaS and EOP:
Create and delete users
Perform upgrades and DB backup
|Security Lead||Create and maintain security policies
Produce success metrics
(for each application)
|Oversee agent installation
Perform initial review of results
Serve as a lead in vulnerability remediation
|CSCP Representative||Oversee project
Tune and tailor Contrast application
Using Assess, Protect or both requires two installations:
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.
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.
To install Contrast in your own environment, we’ll do the following together.
Before we begin, make sure that the CSCP knows the contact information for your Contrast Admin and for your Security Lead.
Read more about configuring System Settings, including the role of SuperAdmin.
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:
Verify that your configuration complies with those that are supported and suggested, which is documented in the following articles for each agent:
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.
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.
Note: You can set up these configurations after including Contrast in your processes.
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.
Before turning on licenses, your CSCP will arrange the following trainings.
To prepare for the meeting, attendees should review the instructions on Contrast Configuration.
To prepare for the meeting, attendees should review the steps in the Contrast UI Introduction for new users.
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.
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.
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.
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.
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.
You’re ready to start with your first tranche of applications to Assess and Protect. (Review the UI Introduction one more time, just for good measure.)
After each application is onboarded, your CSCP will hold the following meetings to ask a few questions.
Month Three (and every three months afterward)