Overview

The Contrast Service enables communication between the Contrast UI and one of the multi-process dynamic language agents (e.g., Ruby and Python).

About Contrast Service

The Contrast Service is a stand-alone executable that's used by the Ruby and Python agents to communicate with the Contrast UI. It's responsible for passing configuration options to the agent, and to aggregate and send information from the agent back to the Contrast UI.

Use the Service

The Contrast Service is compiled for various supported architectures: Linux 64-bit, Macintosh 64-bit and Windows 64-bit. The Service is packaged with the Ruby and Python agents, and starts automatically when the instrumented application is started.

Configuration

The Contrast Service uses a YAML file to update the service behavior.

Load Path

The configuration file is titled contrast_security.yaml no matter where it's located. The Contrast Service loads the configuration YAML from the following paths in order of precedence:

  1. The current working directory (e.g., ./contrast_security.yaml)
  2. An application-specific configuration directory (e.g., ./config/contrast_security.yaml for Ruby on Rails or ./settings/contrast_security.yaml for Django)
  3. Within the server's etc/contrast/webserver (e.g., /etc/contrast/webserver/contrast_security.yaml) when being used for the Proxy agent
  4. Within the server's etc/contrast directory (e.g., /etc/contrast/contrast_security.yaml)
  5. Within the server's etc directory (e.g., /etc/contrast_security.yaml)

General Configuration Options

The configuration YAML consists of four sections. The agent and Service may share a common configuration file, but only some options and sections are applicable to each process.

Contrast UI properties

Use the properties in this section to connect the agent to the Contrast UI.

  • contrast:
    • url: Set the URL for the Contrast UI.
    • api_key: Set the API key needed to communicate with the Contrast UI.
    • service_key: Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header.
    • user_name: Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.
    • certificate: Allow the use of custom or self-signed certificate authority and certificate files when connecting to the Contrast UI.
      • ca_file: When running an Enterprise-on-Premises (EOP) Contrast instance using a self-signed certificate, use this option to provide the path to a custom CA file.
      • cert_file: Provide a path to the server's certificate PEM file.
      • key_file: Provide a path to the server's key PEM file.

Contrast agent properties

Use the options in this section to allow the agents to find and communicate with the Contrast Service.

  • agent: Use the properties in this section to control the way and frequency with which the agent communicates to logs and the Contrast UI.
    • service:
      • host: Set the the hostname or IP address of the Contrast Service to which the Contrast agent should report.
        Example: localhost
      • port: Set the the port of the Contrast Service to which the Contrast agent should report.
        Example: 30555
      • socket: Set for or the Proxy agent only. If this property is defined, the Service is listening on a Unix socket at the defined path.
        Example: /run/contrast-security.sock
      • logger:
        • path: Set the location to which the Contrast Service saves log output. If no log file exists at this location, the Service creates one.
          Example: /opt/Contrast/contrast_service.log will create a log in the /opt/Contrast directory.
        • level: Set the the log output level. Value options are ERROR, WARN, INFO, and DEBUG.
        • progname: Override the name of the process used in logs.
          Example: Contrast Service

Server properties

Use the options in this section to override the server information sent to Contrast UI.

  • server: Use the properties in this section to set metadata for the server hosting this agent.
    Example: test-server-1
    • name: Override the reported server name.
    • environment: Override the reported server environment.
      Example: development
    • tags: Apply a list of labels to the server. Labels must be formatted as a comma-delimited list.
      Example: label1,label2,label3

Installation

The Contrast Service is packaged with the Ruby and Python agents, and runs automatically when an instrumented Ruby on Rails, Flask or Django application starts.

Installation with System Package Manager

You may install the Contrast Service on Linux using system package managers. Unlike the service executable packaged with the Ruby and Python agents, the Contrast Service installed by system package managers isn't preconfigured with connection parameters. Instead, you must configure the service with a YAML configuration file.

Ubuntu-Based Systems

Install the Contrast Service

To install the Contrast Server for Ubuntu-based systems, complete the following steps.

  • Configure your system to retrieve from the correct Debian repository. Get the CODENAME for your Ubuntu release.
grep VERSION_CODENAME /etc/os-release
  • Update the command below with the CODENAME, and run the commands.
curl https://contrastsecurity.jfrog.io/contrastsecurity/api/gpg/key/public | sudo apt-key add -
echo "deb https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/ CODENAME contrast" | sudo tee /etc/apt/sources.list.d/contrastc.list
  • Once you've finished configuration, install the Contrast Service.
sudo apt-get update && sudo apt-get install contrast-service
  • Edit the /etc/contrast/contrast_security.yaml file to configure Contrast Service to connect to the Contrast UI.

Red Hat-Based Systems

Install the Contrast Service

Complete the following steps to install the Contrast Service for Red Hat Enterprise Linux (RHEL) and CentOS versions 5, 6 and 7.

  • To install Contrast Service from Contrast's Yum repository, configure your system to use the repository.
OSREL=$(rpmquery -E "%{rhel}")
sudo -E tee /etc/yum.repos.d/contrast.repo << EOF
[contrast]
name=contrast repo
baseurl=https://contrastsecurity.jfrog.io/contrastsecurity/rpm-public/centos-$OSREL/
gpgcheck=0
enabled=1
EOF
  • Once you've finished configuration, install the Contrast Service.
yum install contrast-service
  • Edit the /etc/contrast/contrast_security.yaml file to configure the Contrast Service to connect to the Contrast UI.

Remove the Service

If you need to uninstall the Contrast Service, use the appropriate command for each package.

  • To remove the contrast-service package, run apt-get remove contrast-service or yum remove contrast-service.