Overview

The Contrast Proxy agent is application language and framework agnostic, similar to a WAF or Next Generation WAF. It provides runtime protection by analyzing HTTP request and response data at the web server level rather than the application level. The agent supports Contrast Protect only.

About the Proxy Agent

The Proxy agent provides runtime protection of HTTP ingress and egress traffic as it's processed by a web server. In the most-common case, a web server is running in reverse proxy mode, and the agent is transparent to the application behind the reverse proxy. This enables the agent to Protect a variety of application technologies, such as PHP, Go, Perl, Groovy or any other language without a dedicated Contrast language agent.

The agent is targeted to specific web server products and versions. For more information, see Supported Technologies for the Proxy agent.

Use the Agent

To start protecting your application with the Proxy agent, see the Installation instructions for obtaining the software.

Supported Technologies

The Proxy agent supports the following web servers:

  • NGINX versions 1.12.2+.

It also supports IPv6 and HTTP/2 configurations of NGINX.

OS Support

The agent is officially supported on 64-bit Linux platforms. However, the agent may work on other platforms that NGINX supports.

Installation

The Contrast Proxy agent is available for installation from a Linux package repository.

Prerequisites

The Proxy agent targets the official Stable NGINX server. You must install their official package as a dependency for Contrast's Proxy agent module. If you have a distro's NGINX package installed, you must remove it in favor of the official NGINX distributed package.

You can find and install the required NGINX package from Contrast's package repository. If you want to obtain it from NGINX directly, use their instructions to configure your system to pull from the official NGINX repository.

Note: NGINX also offers a Mainline distribution option. It's configured differently than, and not interchangeable for, the Stable distribution that's required for the Proxy agent.

You must also ensure that your system is properly configured with the Contrast Linux package repository.

Install from Linux Packages

Use the following commands to install the Proxy agent.

Debian/Ubuntu:

 sudo apt-get update
 sudo apt-get install contrast-webserver-agent-nginx contrast-service

RedHat/Centos:

 sudo yum install contrast-webserver-agent-nginx contrast-service

After this stage, you're ready to configure the software.

Air-Gapped Users

Users that aren't connected to the internet must import Contrast's Linux packages to their internal network since their package manager doesn't reach them. Many organizations have automated import and synchronization procedures for keeping up to date with repositories on the internet disconnected from their air-gapped network. You should ensure your organization doesn't already have an import process that can help with this process. But, regardless of your situation, the following information for manually obtaining the packages is helpful for completing installation.

To manually import the packages, you must go directly to the location where Contrast hosts packages for your packaging system, and download the newest versions. A dependency listing of what you will need:

contrast-server -> contrast-modsecurity
contrast-webserver-agent-nginx -> nginx

The following distro-specific instructions walk you through the process to download the newest version of each of the four packages and import them to your network. After importing and installing the packages, you can move to configuration.

Redhat/Centos

The repository files are located at https://contrastsecurity.jfrog.io/contrastsecurity/rpm-public/. Once you select the folder of your distro, the files are ready for download. You can install them with the following commands:

sudo yum install contrast-modsecurity-<version>.rpm
sudo yum install contrast-service-<version>.rpm
sudo yum install nginx-<version>.rpm
sudo yum install contrast-webserver-agent-nginx-<version>.rpm

Debian/Ubuntu

The repository files are located at https://contrastsecurity.jfrog.io/contrastsecurity/debian-public/pool/. The Debian/Ubuntu repository organizes all of its various distro files in the same directory.

The distro of each package is embedded at the end of the package filename. Download the latest package of the four mentioned above for your particular distro, and import them to your network. You can install them with the following commands:

sudo dpkg -i contrast-modsecurity-<version>.deb
sudo dpkg -i contrast-service-<version>.deb
sudo dpkg -i nginx-<version>.deb
sudo dpkg -i contrast-webserver-agent-nginx-<version>.deb

Configuration

Configure the following items for the Proxy agent:

  • The communication link between Contrast-Service and the Contrast UI
  • The NGINX service enabling the agent to inspect traffic to certain endpoints

Configure the Contrast-Service

Contrast-Service is controlled by the configuration file located at /etc/contrast/webserver/contrast_security.yaml.

This YAML file controls how the Proxy agent is represented to the Contrast application (and shown in the UI). The default configuration installed with the contrast-service Linux package has most necessary items filled in; however, you must add the location of the Contrast application and API key. You must also configure how you want your agent represented to the Contrast application.

  • server:
    • name: Override the reported server name.
      Example: test-server-1
    • path: Override the reported server path.
    • type: Override the reported server type.
      Example: Proxy
    • environment: Override the reported server environment.
      Example: development

You can find the information for following configuration properties in Your Account in the Contrast UI.

  • contrast:
    • user_name: Set the user name used to communicate with the Contrast UI. It is used to calculate the Authorization header.
    • service_key: Set the service key needed to communicate with the Contrast UI. It is used to calculate the Authorization header.
    • api_key: Set the API key needed to communicate with the Contrast UI.
    • url: Set the URL for the Contrast UI.
      Example: https://app.contrastsecurity.com/Contrast

If this configuration has an issue or incorrect values, the contrast-service fails to connect to Contrast. You can troubleshoot the failed connection result at /var/log/contrast/service.log.

Configure the NGINX Service

The Proxy agent is configured within the NGINX configuration files located at /etc/nginx. You must add the Proxy agent module as well as the configuration properties that enable the agent for certain endpoints to the /etc/nginx.conf file.

The following example is for the agent-specific configuration within the NGINX configuration files.

Example:


    load_module modules/ngx_http_contrast_connector_module.so;

    events {
      worker_connections 1024;
    }

    http {

      contrast on;
      contrast_debug off;
      contrast_unix_socket "/run/contrast-service.sock";

      error_log logs/error.log debug;

      server {
        listen 80;
        server_name localhost;

        # sample static site config
        location / {
          autoindex on;
          index index.html index.html;
          contrast_app_name "APP_NAME_A";
        }

        # sample reverse proxy config
        location /app {
          rewrite /MY_APP/(.*) /$1 break;
          proxy_set_header Host $host;
          proxy_set_header X-Real-IP $remote_addr;
          proxy_pass http://127.0.0.1:4567;
          contrast_app_name "APP_NAME_B";
        }
      }
    }

The important parts to note are the load_module directive at the top, which loads the Proxy agent into NGINX, and the various contrast_* directives. You can place the contrast_* directives at the http, server or location context in a NGINX configuration. The individual directives are explained below.

  • contrast: Turn the loaded agent on or off. Value options are on or off.
    Default: off
  • contrast_debug: Turn debug logging on or off. Value options are on or off.
    Default: off
  • contrast_unix_socket: Specify the the Unix domain socket file path. This must agree with the location at which the Contrast Service has configured it. Values must be formatted as a string.
    Default: /run/contrast-service.sock
  • contrast_app_name: Set the application name for the agent as it appears in the Contrast UI. Values must be formatted as a string.
  • contrast_analyze_response_body: Turn on response body processing in the NGINX module. Processing response bodies can slow NGINX significantly and use more resources on the system. Value options are on or off.
    Default: off

Run the Services

The Proxy agent ties into the local system's service management tools. For recent Debian-based systems, this will be systemd.

Manage the Contrast Service with the following commands:

 sudo systemctl enable contrast-service
 sudo systemctl restart contrast-service
 sudo systemctl status contrast-service

Manage the NGINX service with the following commands:

 sudo systemctl enable nginx
 sudo systemctl restart nginx
 sudo systemctl status nginx

Once these services are running, the Proxy agent will protect applications through the NGINX server. To enforce specific Protect settings on a new application, configure application-specific Protect Rules in the Contrast UI.