Overview

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

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.

From its position within the middleware stack, 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.

Use the Agent

To start protecting your application, download the Python agent and service, and create a configuration file as described in Python Agent Installation. The Python agent is installed as a standard Python package, and communicates with a standalone Contrast Service that runs outside your application.

Supported Technologies

The Python agent supports Python versions 2.7+ and 3.4 - 3.6. Framework support is currently for:

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

Note: 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. The agent has no C dependencies, and may work in other operating system environments.

Installation

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

  1. Add the contrast-agent-*.tar.gz to the application's requirements.txt. (This is outlined in the Setup section below.)
  2. Add the contrast_security.yaml file to the application's config directory. (This is outlined in the Configuration section below.)
  3. Run the Contrast Service as a standalone service on the same server as the application. (This is outlined in the section below to Run the Service.)

Setup

The contrast-agent-*.tar.gz is a standard packaged Python library that you can add to the application's requirements.txt.

Contrast as a Python Package

To use Contrast, add this line to your application's requirements.txt after downloading the agent:

-e ./path/to/contrast-agent-<version>.tar.gz

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

pip install -r requirements.txt

Manual installation

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

pip install ./path/to/contrast-agent-<version>.tar.gz

Middleware inclusion

To hook into incoming requests and outbound responses, a middleware needs to be added to your application. To add the middleware to your application, see the following guidance:

Django; in your settings.py file:

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

Flask:

import Flask

from contrast.agent.middlewares.flask_middleware import FlaskMiddleware as ContrastMiddleware

app = Flask(__name__)

app.config.from_pyfile('dev.cfg')
app.wsgi_app = ContrastMiddleware(app)

@app.route('/')
def index():
    return render_template('index.html')

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

Pyramid:

from pyramid.config import Configurator
config = Configurator()

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

WSGI:

from contrast.agent.middlewares.wsgi_middleware import WSGIMiddleware as ContrastMiddleware

# other app code

app = get_wsgi_application()

app = ContrastMiddleware(app)

Configuration

Download a standard configuration file from the Contrast application. You must place the file in the web application's config directory, and define the following fields, at a minimum:

agent:
  service:
    host: 
    port: