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.
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.
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.
The Python agent supports Python versions 2.7 and 3.5 to 3.8. Framework support is currently for:
- 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.
The Python agent has database support for:
PyMySQL and mysql-connector)
The Python agent has NoSQL support for:
The Python agent has ORM support for:
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:
autoconfare required. The package names may be different on different platforms. It may be useful to install your platform's version of
To install the Contrast agent into your Python application, you must complete the following steps.
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.
The contrast-python-agent-[version].tar.gz is a Python package that can be installed using
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:
After editing the requirements.txt, you can install normally:
pip install -r requirements.txt
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 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 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:
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 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.
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 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.
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)
Once the installation process is complete, you can update the agent's configuration file.