Enterprise-on-Premises (EOP) customers can manage their own instance of Contrast, including security policy, database settings and authentication. To modify system configuration settings for the Contrast application, you must have the SuperAdmin role. Individual users can be granted SuperAdmin permission on a case-by-case basis. Organization administators, known as OrgAdmins, can also access and change many of these settings for a specific organization in Organization Settings.
To get started in System Settings, log in to the Contrast UI. In the top right corner (by your profile name and image) of the screen, select the dropdown user menu and then SuperAdmin. Once you're in the SuperAdmin view, open the user menu again, and select System Settings.
General settings define the Contrast application URL for both browsing and RESTful requests. If you want to integrate with Contrast Hub for library and CVE updates, you can select the option to "Try Hub". Any change to this value will require you to Restart Contrast.
If you moved the installation, or had to change the hostname or IP address, simply update the TeamServer URL field with the new value. Again, any change will require a system restart.
Note: You will have to replace your agents so they know which address they should report to.
In the Licensing page, get a glimpse of license allocation, see if any licenses are nearing expiration, and update your license when needed. For more information, read how to Manage Licenses in Organization Settings.
Use the Policy page to manage the compliance policy for your organization(s) by creating restrictions or version requirements for libraries. Contrast will then flag libraries that violate the compliance settings, and alert you to violation.
Contrast supports a the following authentication providers. Any change to this setting in the Authentication page requires a system restart.
Change this setting with caution. It's very unlikely that a SuperAdmin will need change these values. In the event of a system restore operation, changes to the values of this configuration - such as the URL, which contains host information, or username and password - in Database page may be required. Any change to this value also requires a system restart.
Contrast can send email notifications to users when significant events occur, like a password reset. Configure settings for a SMTP server using the following fields in the Mail page.
The SuperAdmin can change the default log level for the various log files. Any change to this setting will take effect after a system restart.
You can customize the score settings for both overall application score and libraries in the Score Settings page. This setting allows EOP administrators to configure how scores get calculated and permit an individual organization to override the setting.
If you want to alert all users in your organizations to important changes, you can send a system message, which they'll receive every time they log in to Contrast until the message expires or is deleted. Select the Create a Message button in the System Messages page to get started.
Contrast Diagnostics measures customer usage of Contrast products to help Contrast provide faster, more proactive support and guide delivery of new functionality.
Contrast periodically sends snapshots of relevant data elements and data aggregations up to Contrast Diagnostics, a service on Contrast’s Software as a Service (SaaS) platform. Data that could be used to identify a customer or organization is obscured using a one-way hash, and is encrypted both in transit and at rest. Due to privacy concerns, the data doesn’t include application names, personally identifying information, code, vulnerability identities or customer network identifiers.
As Contrast securely transmits the data over an encrypted connection to the Contrast Diagnostics service, the data is anonymized and not attributable to any particular Contrast installation. The data is then stored in the Contrast Diagnostics database, where it’s made available to approved Contrast Support and Product Development users for analysis and reporting. Within the database, the data is attributed to customers to provide Customer Support insight into how to better assist Contrast customers.
Diagnostics helps Contrast provide proactive support to customers through technical assistance and expert guidance in three main areas.
Customer Support will analyze the data sent back to Contrast for markers, which can indicate potential issues, and allow Customer Support to reach out proactively and work with you to prevent problems.
Contrast can use the collected data to quickly diagnose existing problems and reduce the cycle time for successfully resolving support cases.
Insight into deployment and usage helps Contrast product development teams to adjust and deliver new functionality to help customers get the most out of their Contrast deployment.
SuperAdmins can enable and disable the Contrast Diagnostics feature through the SuperAdmin dashboard. SuperAdmins may also use the Contrast REST API to preview the data that will be transmitted to Contrast Diagnostics. You can find information about how to use the REST API in Contrast’s API documentation.
To view the Diagnostics setting in the Contrast UI, go to the user menu > System Settings > General Settings > Internet Settings section. Diagnostics is enabled by default; however, you can use the toggle to disable and re-enable it as needed.
Note: Your proxy settings apply to your Hub and Diagnostics settings.
As Contrast becomes an integral part of your development lifecycle, you might want to let users know about situations like scheduled downtime or that an update has been applied. System messages allow you to immediately alert all users in your organizations every time they log in to Contrast, and continue to send the alert until your chosen expiration date.
To create a new system message, navigate to your SuperAdmin view, and go to the user menu > System Settings > System Messages tab.
Click the button to Create a Message. In the dialog that appears, set an expiration date and time for the message, and add the text in the Message field. Contrast will display this message until you deleted or it reaches expiration.
Note: Users must manually acknowledge system messages before they can continue with their tasks in the Contrast UI.
If you want to immediately deactivate an active system message, use the checkbox to select the message, and click the Delete button.
To learn how to set user notifications from Organization Settings, read the Notifications article.
The Stats dashboard is designed to help administrators get the most out of Enterprise-on-Premises (EOP) deployment through better understanding of scaling and performance issues, as well as to help troubleshoot user problems.
Go to the Stats page from the top navigation menu to view data on your Contrast application. At the top of the page, use the button to change the refresh rate of the charts and tables.
The Queue Breakdown chart shows you how effectively the Contrast application is handling the agent traffic. If queues seem to be growing faster than Contrast can handle them, it's a good indication that you should scale up or out.
While extremely uncommon, it's possible that corrupted data could make it into one of the Contrast queues, and cause the queue to freeze and stop processing. If you believe a problem has occurred and that clearing could resolve it, or if instructed to do so by a Contrast Support Agent, click the Clear Queues button.
The Logged In Users chart displays all users who are currently logged in to either the user or administrator UI. Click on the Show Details icon to see additional information about each user's session.
The Stats section shows compiled information about the JVM and the system on which Contrast is running. The data is separated into Server, Memory and Memory Pool tables.
If SSL is part of your Enterprise-on-Premises (EOP) deployment, System Admins may find the following commands and introductory principles to be useful.
There are three workflows in which Contrast users typically add SSL:
The following examples are intended to help describe workflows in which you could use SSL, as well as the possible commands for implementation and debugging.
The following command creates a new KeyStore (if one doesn't exist), KeyPair and an alias called "
keytool -genkeypair \ -alias teamserver \ -keyalg RSA \ -keystore contrast.jks
When running this command, you'll be prompted for information to identify yourself and your organization. This command requires a password that you'll need for future integrations.
Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: john smith What is the name of your organizational unit? [Unknown]: devteam What is the name of your organization? [Unknown]: Example, Inc What is the name of your City or Locality? [Unknown]: New York City What is the name of your State or Province? [Unknown]: NY What is the two-letter country code for this unit? [Unknown]: US Is CN=john smith, OU=devteam, O=Example, Inc, L=New York City, ST=NY, C=US correct? [no]: y
The directory after this command shows:
$ ls contrast.jks
Your certificate authority (CA) needs a certificate signing request (CSR) from you to create a SSL certificate.
keytool -certreq \ -alias teamserver \ -file teamserver.csr \ -keystore contrast.jks
After this command, the directory shows:
$ ls contrast.jks teamserver.csr
You can now share the teamserver.csr with your CA. In response, they should send you a signed SSL certificate to use in your environment.
When importing root and intermediate certificates, you'll need to be aware of a small change to the
-file options. As a general rule, most purchased SSL certificates will be recognized as valid because their root CA is already part of the default KeyStore. However, the default will change with your distribution and Java version. You can find the default KeyStore at $JAVA_HOME/jre/lib/security/cacerts.
To view the contents of this KeyStore, use:
$ keytool -keystore cacerts -list Enter keystore password:
If you're using an internal CA, you must obtain root and intermediate certificates to verify the chain of trust through the KeyStores on both sides of the connection.
To obtain the root certificate:
keytool -import \ -trustcacerts -alias root -file my-root-cert.crt -keystore contrast.jks
To obtain the intermediate certificate:
keytool -import \ -trustcacerts -alias intermediate -file my-intermediate-cert.crt -keystore contrast.jks
The alias used is the same in all of the previous examples, specifically for CSR. You should receive a my-ca-signed-cert.crt in response to a CSR.
It's very important that this signed certificate is imported to the alias that matches the private key used to create the CSR.
keytool -import \ -trustcacerts -alias teamserver -file my-ca-signed-cert.crt -keystore contrast.jks
When debugging your KeyStore and client connections, it's helpful to match fingerprints between client and server.
keytool -list \ -keystore contrast.jks
$ keytool -list \ > -keystore contrast.jks Enter keystore password: Keystore type: JKS Keystore provider: SUN Your Keystore contains 1 entry teamserver, May 6, 2016, PrivateKeyEntry, Certificate fingerprint (SHA1): 5C:23:48:BF:80:2D:AE:78:57:8C:BE:45:C4:39:BA:A8:D8:77:70:D8
To list them verbosely:
keytool -list \ -v \ -keystore contrast.jks
To export a certificate from your KeyStore:
keytool -export -alias teamserver -file teamserver.crt -keystore contrast.jks
To delete an alias from your KeyStore:
keytool -delete \ -alias teamserver \ -keystore contrast.jks
To rename an alias in your KeyStore:
keytool -changealias \ -alias teamserver \ -destalias contrast-teamserver \ -keystore contrast.jks
To change your KeyStore password:
keytool -storepasswd \ -keystore contrast.jks
By default, Contrast uses HTTP for UI and agent connections. This may not be a big deal in some organizations; in others, you may find that you need to add or replace HTTP with HTTPS for both UI and agent traffic. There are two ways to accomplish this requirement.
Reverse proxy method: Use a standard web server, such as Apache HTTPD or NGINX, in front of the Contrast server configured to reverse proxy requests using Contrast's AJP connector.
Contrast HTTPS connector: Configure Contrast to listen to HTTPS connections on a port that you specify.
Each method has its own benefits. Providing the option to use either method allows Contrast to fit in with many different organization security policies and architectures.
To use AJP with a reverse proxy, you must ensure that the Contrast server is configured to listen for connections using the AJP protocol. To verify this setting, open the $CONTRAST_HOME/data/conf/server.properties file in your text editor and ensure that the following options are set.
You can configure the
ajp.port setting to reflect the port on which you'd like the server to listen for incoming connections. In some cases, you might want to also disable the
After updating the server.properties file, restart the Contrast server service so that the changes to take effect.
Refer to your server's documentation for instructions on how to configure it to use AJP. Also refer to the following links for Apache and NGINX instructions.
Configuring Contrast to use a HTTPS connector is a straight-forward process. These instructions are written in the context that you have a certificate to use. The certificate can be CA signed or self signed.
To begin, import your certificate into a new Java KeyStore (JKS) for use by Contrast. If you already have a KeyStore, you can skip this step and place it in the $CONTRAST_HOME/data/conf/ssl directory.
Note: All commands used in this guide should be run in a command shell with administrative privileges from the directory in which Contrast was installed.
This is the quickest and easiest method for generating the proper certificate and KeyStore. The following command prompts you for information about your organization and then generates a KeyStore with a self-signed certificate.
$ jre/bin/keytool -genkey -keyalg RSA -alias contrast-server -keystore data/conf/ssl/contrast-server.jks -validity 365 -keysize 2048
Contrast recommends using this method over generating certificates with OpenSSL. For more complicated SSL configurations, Contrast recommends using a reverse proxy. The following section walks you through enabling SSL in the Contrast server.
To begin, generate a new KeyStore.
$ jre/bin/keytool -genkey -alias contrast-server -keystore data/conf/ssl/contrast-server.jks
Once it's created, import your server's certificate into the new KeyStore.
$ jre/bin/keytool -import -keystore data/conf/ssl/contrast-server.jks -storepass <keystore password> \ -file <path to certificate> -alias <server hostname>
You may also need to import intermediate CA certifications into the KeyStore. (See your CA's documentation to verify that this is the case.) For a private CA server, you need any intermediate certificates and the root CA certificate in the KeyStore.
$ jre/bin/keytool -import -trustcacerts -alias <ca-name> -storepass <keystore password> \ -file <path to ca or intermediate certificate>
Note: In order for the Contrast UI to use the SSL Certificate, the certificate can't be protected with a passphrase.
Once KeyStore setup is complete, open the $CONTRAST_HOME/data/conf/server.properties file in your text editor, and update the following properties.
https.enabled=true https.port=<port to listen for https connections on> https.keystore.file=<full path to jks created above> https.keystore.pass=<password for the jks created above> https.keystore.alias=<hostname of the server>
You may find it useful to set the
ajp.enabled options to
false to ensure that only connections made over HTTPS are allowed to the Contrast server.
After updating the
server.properties, restart the Contrast server service, and ensure that it's now listening on the HTTPS port you configured.
If you switch from HTTP to HTTPS, update the server to tell future Contrast agents that they should connect back using HTTPS instead of HTTP.
Open the $CONTRAST_HOME/data/conf/general.properties file, and change the value of the
teamserver.url property to reflect your change. Agents must be updated manually the first time after you make this change. Future updates to the agent will be automatic.
Note: The Contrast .NET agent needs additional configuration to connect to a Contrast application using a self-signed certificate.