Skip to content

Configure a Python agent with Contrast in five minutes

Configure a Python agent with Contrast in five minutes

These days, it’s not enough to scan your code for vulnerabilities before deploying it. You also must implement runtime security and counter live threats that predeployment testing may have missed. Contrast Security gives you the tools you need to do these things. We provide agents for multiple languages and frameworks that look at live data flowing through the application and take defensive steps if they sense threats. This article explores agents and how to configure a Python-specific one to secure your Python applications.

The Contrast agent is a piece of code that runs locally on a machine, collecting data from your application and generating traces based on this data. It scans these traces for anomalous patterns that violate Contrast rules. Suppose a query trying to launch an SQL injection attack passes to your Python application, for example. In that case, the Contrast agent recognizes it, observes that the request violates the Contrast security rules for SQL injection and reports it to Contrast.

The analysis engine that powers these important decisions does most of its job locally and enables Contrast to scale and without slowing down your application unnecessarily.

Before we move on, ensure you have an active Contrast Security account. You need an upgraded account, as the free one doesn’t support Python-based agents. Follow these steps to set up a fully functioning agent for Python:

  1. Install the Contrast service binary.
  2. Install the Python agent using PyPI.
  3. Configure the framework-specific middleware.

Now, let’s take a look at each step in turn.

Installing and configuring Contrast service binary

The service is supported on 64-bit Linux, Mac and Windows operating systems (OSes). It's packaged with the Python agent and starts automatically whenever the Python agent launches. However, you can have more control over the Contrast service by installing it as a standalone application on your system.

To install it on a Debian-based Linux distro:

  1. Get the CODENAME for your Ubuntu release:

  grep VERSION_CODENAME /etc/os-release

  1. Update the command below with the CODENAME and run the following commands:

  curl | sudo apt-key add -

    echo "deb CODENAME contrast" | sudo tee /etc/apt/sources.list.d/contrastc.list

This command adds the Contrast Security repository to your system so that APT can install the Contrast service from there.

  1. Install the Contrast service:

  sudo apt-get update && sudo apt-get install contrast-service

If you use a different OS, refer to Contrast’s official documents for more guidance.

After installation, you must configure the service. Contrast uses a YAML configuration file for this purpose. Where you place the YAML file depends on whether you want to share this configuration among all the apps on your system.

If you don't want it to be shared, place the configuration file at: 


If you want it to be shared, place the configuration file at:


There should already be a placeholder configuration at:


The file should look something like this:


  # XXX: Replace with your actual Contrast license values and TeamServer

  # instance

  #user_name: __CONTRASTUSER__

  #service_key: __SKEY_

  #api_key: __AKEY__

  #url: https://__TEAMSERVERHOST__/Contrast



    path: /var/log/contrast/agent.log

    level: INFO


    path: /var/log/contrast/security.log

    level: INFO



      path: /var/log/contrast/service.log

      level: INFO

    socket: /run/contrast-service.sock

You must update the api section with your official keys. You can get them from the Contrast security portal

Follow the steps below to get your API and service keys:



You can look at a detailed sample configuration file in Contrast’s guide for more information about available configuration options.

Installing and configuring Python agent

Installing a Python agent is simple. Just run this pip command: pip install contrast-agent

If you decided not to install the Contrast service separately, now is a good time to create ./config/contrast_security.yaml in the root of your application folder and set it up like we did the Contrast service in the previous section — the Python agent defaults to using this file for configuration.

If you’ve already configured the Contrast service in the previous section, you don't need to create a new configuration file.

Configuring Python middleware

The installation of the Python agent does nothing unless you use it through middleware. This step varies based on which Python web framework you end up using. We focus on Flask for this tutorial, but a list of all possible options is available in this Contrast guide.

This is what a typical Flask application looks like:

import Flask

app = Flask(__name__)


def index():

  return render_template('index.html') 

You can modify this to include Contrast middleware as follows:

import Flask

app = Flask(__name__)

from contrast.flask import ContrastMiddleware

app.wsgi_app = ContrastMiddleware(app)


def index():

  return render_template('index.html') 

You might also have to use certain configuration options with your web server, and some web servers do not work properly with Contrast when launched with their default values. You can refer to this Contrast guide regarding configuration options for the Gunicorn, Uvicorn and uWSGI servers.

Now go ahead and run your Python application and the accompanying server to benefit from the enhanced security provided by Contrast. You can access the portal for the community edition at this link. Upon successful login, you should be able to see aggregated stats for all of your applications. Go to the Applications tab and select the most recent application to see the stats for that specific application:


It's easy to improve the security of our Python applications with a bit of help from Contrast. While it's always helpful to test your application for security vulnerabilities before launch, having a live agent is equally important to capture and thwart attacks targeted toward your application in production. Furthermore, with the increasing sophistication and frequency of application attacks, it's paramount to be prepared to counter them quickly.

Give Contrast Security a try and explore our support options for Python-based applications today.


Omair Dawood, Principal Product Marketing Manager, Contrast Security

Omair Dawood, Principal Product Marketing Manager, Contrast Security