Overview

The Contrast Python agent provides runtime protection of Django, Flask and Pyramid web applications.

Version 2.3.0 of the agent introduces beta Assess functionality. This provides the ability to find vulnerabilities in applications before they can be exploited.

Note: The beta Assess feature can be licensed in alpha and eval instances of the Contrast UI.

About Python

The Python agent is a WSGI- and framework-specific middleware that's compatible with the most-popular web application frameworks. The agent's goal is to be fully WSGI compatible along with other web frameworks.

In Protect mode, the Python agent inspects HTTP requests to identify potentially harmful input vectors. During the request, the agent inspects database queries, file writes and other potentially damaging actions resulting from the request. At the end of the request, the agent inspects the rendered output for successful attacks, and can block a successful attack from being forwarded to the application user. The service sends the details of the attack to the Contrast application, which then sends you an alert and displays attack details in the interface.

In Assess mode, the agent identifies vulnerable dataflow paths and other issues during normal execution of your application. It reports these findings to your organization in the Contrast UI; you can then remediate the vulnerabilities before deploying the application in a live environment.

Use the Agent

To start using your application with Contrast, download the Python agent and create a configuration file as described in Python Agent Installation. The Python agent is installed as a standard Python package, and uses the Contrast Service to communicate results.

By default, the service is started automatically when your application starts. It's also possible to configure the agent to communicate with a standalone Contrast Service that runs independently. See the Contrast Service documentation for more details.

Supported Technologies

The Python agent supports Python versions 2.7 and 3.5 to 3.7. Framework support is currently for:

  • Django: 1.10+ and 2.0+
    (Django 2 is available for Python 3 only.)
  • Flask: 0.10 - 0.12 and 1.0+
  • Pyramid: 1.9 (Beta)
  • Pylons: 1.0+

Notes:

  • Only Django is officially supported for the beta release of Assess capability.
    • The Python agent is meant to be WSGI compatible. It may be compatible to other WSGI applications as long as the guidelines are followed.

Database Support

The Python agent has database support for:

  • MySQL (MySQLdb)
  • Oracle (cx_Oracle)
  • SQLite3 (sqlite3 and pysqlite2)
  • PostgreSQL (psycopg2)

NoSQL Support

The Python agent has NoSQL support for:

  • Mongo (pymongo)

Database Support

The Python agent has ORM support for:

  • SQLAlchemy (SQLAlchemy)
  • Flask-SQLAlchemy (Flask-SQLAlchemy)

OS Support

Agent testing is done on 64-bit OSX and 64-bit Linux.

Starting with version 2.3.0 of the agent, the package installation step requires the compilation of C extensions. This process is automatic, but it requires that certain software is installed in the target environment:

  • At a minimum, gcc, make, automake and autoconf are required. The package names may be different on different platforms. It may be useful to install your platform's version of build-essential.
  • On some platforms, it may be necessary to install system headers.

Installation

To install the Contrast agent into your Python application, you must complete the following steps.

  • Add the contrast-python-agent-[version].tar.gz to the application's requirements.txt. (This is outlined in the Setup section below.)
  • Add the contrast_security.yaml file to the application's working directory. (This is outlined in the Configuration section below.)

You may also start a standalone instance of the Contrast Service. By default, the service is started automatically by the agent when your application starts. For more details on running the standalone service, see the Contrast Service documentation.

See Supported Technologies for more requirements.

Setup

The contrast-python-agent-[version].tar.gz is a Python package that can be installed using pip.

Contrast as a Python Package

To use Contrast, add the following line to your application's requirements.txt (usually found at the top level of the application source tree) after downloading the agent:

./path/to/contrast-python-agent-[version].tar.gz

After editing the requirements.txt, you can install normally:

pip install -r requirements.txt

Manual installation

To install the Contrast agent manually, download the contrast-python-agent-[version].tar.gz file to a local directory and run:

pip install ./path/to/contrast-python-agent-[version].tar.gz

Middleware inclusion

Middleware is the name for a software component that's part of a web application, and is capable of reading and modifying inbound requests and outbound responses.

The Python agent is implemented as a middleware for all of the frameworks that Contrast supports. To use the agent, you must configure the middleware for the framework that your application uses. Specific instructions for each of the supported frameworks are below.

Django

Django middleware is configured in the settings.py file. This file isn't found in the same location for all applications, but it's generally near the top of the application source tree. Common locations include:

  • /settings.py
  • config/settings.py
  • app/settings.py

Note: When searching the source tree to find the settings.py, make sure to exclude any directories that correspond to Python virtual environments.

Some applications have multiple settings.py files, which may correspond to different configurations of the application (e.g., prod or test). In these cases, add the Contrast agent middleware to any and all of the configurations where it will be used.

For Django 1.10+ and 2.0+, look for the MIDDLEWARE configuration variable, which is an array. Add the Contrast agent module to the list, as shown:

MIDDLEWARE = [
  'contrast.agent.middlewares.django_middleware.DjangoMiddleware',
  # OTHER MIDDLEWARE,
]

In general, it's best practice to include the Contrast middleware as early in the list as is possible; although modifying the order may be necessary to get the application working in some circumstances.

Older versions of Django have a different architecture for middlewares. For Django 1.6 to 1.9, look for the MIDDLEWARE_CLASSES configuration variable in settings.py.

MIDDLEWARE_CLASSES = [
  'contrast.agent.middlewares.legacy_django_middleware.DjangoMiddleware',
  # OTHER MIDDLEWARE
]

See the Django documentation for more details on middleware inclusion.

Flask

Flask middleware is a WSGI middleware which operates by wrapping the Flask application instance. The following example shows a sample Flask application wrapped by the Contrast middleware class:

import Flask

# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.flask_middleware import FlaskMiddleware as ContrastMiddleware

# This is where the example app is declared. Look for something similar in your
# application since this instance needs to be wrapped by Contrast middleware
app = Flask(__name__)

# This line wraps the application instance with the Contrast middleware
app.wsgi_app = ContrastMiddleware(app)

# Everything below this line is part of the example app. It should not be added
@app.route('/')
def index():
    return render_template('index.html')

if __name__ == '__main__':
    app.run(...)

See the Flask documentation for more details on using WSGI middleware.

Pyramid

In Pyramid, middlewares are called "tweens". See the example below for adding the Contrast middleware to a Pyramid application:

from pyramid.config import Configurator
config = Configurator()

config.add_tween('contrast.agent.middlewares.pyramid_middleware.PyramidMiddleware')

See the Pyramid documentation for additional details on tween configuration.

WSGI

WSGI middleware is implemented as a class that wraps the application instance. (This is also the basis for both Flask and Pylons middleware.)

# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.wsgi_middleware import WSGIMiddleware as ContrastMiddleware

# other app code

app = get_wsgi_application()

# This line wraps the application instance with the Contrast middleware
app = ContrastMiddleware(app)

See the WSGI spec for additional details on WSGI middleware.

Pylons

Like Flask, Pylons middleware is WSGI middleware which operates by wrapping the Flask application instance:

from pylons.wsgiapp import PylonsApp
# This line imports the Contrast middleware class from the package
from contrast.agent.middlewares.wsgi_middleware import WSGIMiddleware as ContrastMiddleware

app = PylonsApp()
# This line wraps the application instance with the Contrast middleware
app = ContrastMiddleware(app)

Next Steps

Once the installation process is complete, you can update the agent's configuration file.