Agent installation guide
Overview
This guide offers examples for using Contrast Security’s Python agent with Docker. We encourage you to take this guide, make it your own, and distribute it to teams who both need to instrument Python applications and manage them through Docker.
The main portion of the guide details the most popular methods customers use to instrument Python applications contained in Docker and see security data in Contrast.
There is also a lab section that describes how to instrument a sample python application called DjanGoat. It’s a good way to learn before proceeding with your own applications. You can instrument DjanGoat with Docker and see security data for this application in Contrast using the source code samples section at the end of this guide.
Main steps
Update the application’s Dockerfile:
- Add the Contrast Python agent
- Configure the agent
- Add authentication credentials for your environment
Instrument your application
Supported technologies
Before you begin, please be sure Contrast supports your preferred tools and environments for Python: Supported technologies for the Python agent
This guide assumes you have:
- Some familiarity with DevOps practices and how Docker works
- Access to the pypi repository for the Contrast agent
The information to instrument applications with the Python agent and see results in Contrast:
Install the Python agent
gcc
, make
, automake
and autoconf
. The package names may be different on different platforms. Installing your platform's version of build-essential
or installing system headers may be necessary. If running an agent on Alpine OS, libtool
is required. Some base OS images, already come with these installed, but if not, they must be installed in the container prior to installation.
Instructions
To begin, update the Dockerfile for your application.
1) Add the Contrast Python agent
Here are two options to add the Contrast agent and basic configuration to a Docker image. Choose the one that works best for you.
Option 1: Add to the Dockerfile
In this approach, you add the Contrast agent to the application’s Dockerfile. You can add the most recent agent:
RUN pip install contrast-agent
|
OR target a specific version:
RUN pip install contrast-agent==5.17.1
|
Example: Dockerfile configuration
FROM python:2.7-buster |
Option 2: Add to the requirements.txt
In this approach, you add the agent to the requirements.txt file. To do this:
- Add the Contrast agent to the application’s requirements.txt file. Specify the agent version, if desired.
- Add the requirements install to the docker file if not already present.
Example: adding the agent to requirements.txt
contrast-agent==3.3.1
|
pip install -r requirements.txt
|
Configure the middleware
See Contrast documentation for the complete listing of framework specific configurations: Configure middleware
Example: updating settings.py in Django middleware
MIDDLEWARE = [ |
2) Configure the agent
There are different values you can use to configure Contrast agents. This is the order of precedence, and each level overrides the next: 1 is highest.
- Corporate rule (e.g., expired license overrides assess.enable)
- Environment variable value
- YAML configuration file value
- Contrast UI value
- Default value
Order of precedence is explained more here:
Order of precedence
We recommend a mixed approach:
- Keep the common configuration in the YAML file so it can be placed in the base image.
- Use environment variables for authentication and application-specific settings.
Common configuration
This approach keeps a core set of configurations in the YAML file. These can be added to a base image and overridden by environment variables when needed.
To do this:
- Add a base service and logging configuration:
agent: |
- Copy the edited YAML into the base image Dockerfile:
This can be copied into any of the following locations in the container:
- <approot>/contrast_security.yaml
- /etc/contrast_security.yaml
- /etc/contrast/python/contrast_security.yaml
For more options, see Contrast documentation:
Example:
COPY WORKSPACE/contrast_security.yaml approot/contrast_security.yaml |
Application-specific configuration
To set an application-specific configuration, use the environment variables in the application’s container. These are some common configuration options. NOTE: use double-underscores here.
For more, see Contrast documentation: Python-specific configuration
- Application name: Specify the application name reported to Contrast
CONTRAST__APPLICATION__NAME
- Application group: Specify the application access group for this application during onboarding. NOTE: Application access groups have to be created first in Contrast.
CONTRAST__APPLICATION__GROUP
- Application tags: Add labels to an application
CONTRAST__APPLICATION__TAGS
- Server name: Specify the server name reported to Contrast
CONTRAST__SERVER__NAME
- Server environment: specify in which environment the application is running. Valid values for this configuration are: Development, QA and Production.
CONTRAST__SERVER__ENVIRONMENT
- Server tag: Add labels to the server
CONTRAST__SERVER__TAG
3) Add authentication credentials for your environment
For the Python agent to send data to Contrast, it needs an API URL and agent credentials for authentication to the server. This is sensitive data and should be treated carefully.
CONTRAST__API__URL=https://app.contrastsecurity.com/Contrast |
You can get API values (agent keys) from Contrast or by downloading a YAML file for the Python agent. For more, see Contrast documentation: Find the agent keys
4) Instrument your application
You can now run the application image with Contrast enabled. Contrast will instrument your application during startup and begin reporting security vulnerabilities to Contrast.
You can verify that Contrast is running by checking the container log. You should see messages such as:
web_1 | Django version 1.11.1, using settings 'pygoat.settings' |
Source code example: djangoat
Use this GitHub repository to learn how first. It contains a lab that walks you through different ways to instrument Python applications via Docker for security monitoring with Contrast.
https://github.com/marklacasse/DjanGoat/tree/docker
Known Issues