Python - Agent update guide – Contrast Security Support Portal

Overview

This guide offers examples to easily update the Contrast Python agent and keep it updated. Contrast frequently releases new versions of agents, so this is important to do. We encourage you to take this guide, make it your own, and distribute it to teams who need to update agents.

Main Steps

Choose a source for the Contrast Python agent.
- PyPI repository
- Contrast API
Install the agent and use scripts for automatic updates.
- Use requirements.txt
- Install and update manually

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 Python’s pip package manager.
Access to the PyPI repository for the Contrast agent.
Confirmed that your Python application runs properly without the Contrast Python agent
Previously successfully installed the Contrast Python agent.
Defined a policy for how and when to update the agent, based on your change management policy and the environment where you deploy agents.

Instructions

The most reliable and effective way to automatically update the Contrast Python agent is to use the Python pip package installer to install and download the latest version available. Because pip manages all dependencies for your Python application, it should already be available and part of your build environment. How frequently you update the Contrast Python agent and where you get updates depends on your organization’s preferences and your Contrast implementation: SaaS or on-premises.

1) Choose a source for the Contrast Python agent

PyPI public (or private) repository
Contrast API

Depending on your Contrast installation, you can use one or both sources to get the latest Contrast Python agent:

For SaaS installations:
Contrast Python agents are synchronized between Contrast and the public PyPI repository. You can get the latest version of the agent from either source, so use your preference. If your organization prefers to validate agents before using them, you can also use a private PyPI repository with approved versions only.
For on-premises (EOP) installations:
Many organizations that use EOP installations do not immediately update core software or agents when Contrast releases new software. Because of this, we don’t recommend public repositories (like PyPI) to update the agent. These typically host new versions of the agent that are not designed or tested to work with older versions of Contrast.
In this situation, Contrast recommends that you source agent updates directly from the Contrast API or from a private PyPI repository where you only store versions of the agent that match your EOP Contrast installation.

2) Install the agent and use scripts for automatic updates

There are two ways to install the agent into your environment, if you want to easily update it. Choose the method that works for your situation:

Specify the Contrast Python agent as a dependency in requirements.txt

Manually retrieve and add the Contrast Python agent

Method 1: use requirements.txt

requirements.txt is the file where you specify which dependencies you want to automatically resolve every time your Python application builds with artifacts from PyPI (public or private). Include the Contrast Python agent here to easily keep every new build of your application aligned with the latest version of the agent. Do not specify a version for contrast-agent, and it will retrieve the latest version.

Here is an example that shows how to update the agent in requirements.txt:

contrast-agent
Django==2.0.3
mysql-connector-python==8.0.6

After you update requirements.txt, use the following command when you build your application. This will automatically download and add or update the Contrast Python agent from PyPI to the Python application:
$ pip install -U -r requirements.txt

Method 2: install and update manually

For some organizations, the requirements.txt file must be consistent across environments, or they do not plan to install the Contrast Python agent into all environments. In these cases, install the agent manually. You can manually update agents as part of a Python build process.

Use the following command to manually retrieve and add or update the Contrast Python agent from PyPI (public or private) to the Python application:
$ pip install -U contrast-agent

You can also manually add or update to the Contrast Python agent directly from the Contrast API. Use the following authentication details and commands:

CONTRAST_URL=https://app.contrastsecurity.com OR EOP TeamServer URL
ORG_ID=<YOUR TEAMSERVER ORGANIZATION ID>
AUTH_TOKEN=<YOUR TEAMSERVER AUTHENTICATION TOKEN>
API_KEY=<YOUR TEAMSERVER API KEY>
curl -X GET $CONTRAST_URL/Contrast/api/ng/$ORG_ID/agents/default/PYTHON \
  -o /PATH/TO/PYTHON/APP/DIR/contrast-agent.tar.gz -H 'Authorization: $AUTH_TOKEN' \
  -H 'API-Key: $API_KEY' -H 'Accept: application/json' -OJ
pip install /PATH/TO/PYTHON/APP/DIR/contrast-agent.tar.gz

Expected output

After initial execution for either method, you will see output that looks like the following:

Collecting contrast-agent==3.2.0
  Downloading contrast-agent-3.2.0.tar.gz (57.6 MB)
    |████████████████████████████████| 57.6 MB 9.3 MB/s
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Requirement already satisfied: protobuf>=3.12 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from contrast-agent==3.2.0) (3.12.4)
Requirement already satisfied: psutil>=5.7 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from contrast-agent==3.2.0) (5.7.2)
Requirement already satisfied: setuptools in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from protobuf>=3.12->contrast-agent==3.2.0) (41.2.0)
Requirement already satisfied: six>=1.9 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from protobuf>=3.12->contrast-agent==3.2.0) (1.15.0)
Building wheels for collected packages: contrast-agent
  Building wheel for contrast-agent (PEP 517) ... done
  Created wheel for contrast-agent: filename=contrast_agent-3.2.0-cp38-cp38-macosx_10_14_x86_64.whl size=58136641 sha256=31180161afa45f80056a44f134b64fd80290f647618a71bc37c83ace1c3ad887
  Stored in directory: /Users/eklein/Library/Caches/pip/wheels/0c/ac/40/c1173cd375a96d1d72e774def15310ffa167db8f8d31db49cd
Successfully built contrast-agent
Installing collected packages: contrast-agent
Successfully installed contrast-agent-3.2.0

You will know the update succeeded when you see a verification like this:

$ pip list
Package                Version
---------------------- ----------
contrast-agent         3.2.0

If there is not a new Contrast Python agent since the last update, Python application builds will return output like this:

Requirement already satisfied: contrast-agent==3.2.0 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (3.2.0)

When there is a new Contrast Python agent to download and apply, Python application builds will return output like this:

Collecting contrast-agent==3.2.1
  Downloading contrast-agent-3.2.1.tar.gz (57.6 MB)
    |████████████████████████████████| 57.6 MB 6.4 MB/s
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Requirement already satisfied: protobuf>=3.12 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from contrast-agent==3.2.1) (3.12.4)
Requirement already satisfied: psutil>=5.7 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from contrast-agent==3.2.1) (5.7.2)
Requirement already satisfied: six>=1.9 in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from protobuf>=3.12->contrast-agent==3.2.1) (1.15.0)
Requirement already satisfied: setuptools in /Users/eklein/.pyenv/versions/3.8.2/lib/python3.8/site-packages (from protobuf>=3.12->contrast-agent==3.2.1) (41.2.0)
Building wheels for collected packages: contrast-agent
  Building wheel for contrast-agent (PEP 517) ... done
  Created wheel for contrast-agent: filename=contrast_agent-3.2.1-cp38-cp38-macosx_10_14_x86_64.whl size=58136898 sha256=9963a1ce8b26545a8dd4dba466c43d5e4629ae71b803cba010fed582c4293459
  Stored in directory: /Users/eklein/Library/Caches/pip/wheels/b6/aa/78/bd4a0f94cb73c12215f46f3b7ee9c59a44f30acdaca2b75e03
Successfully built contrast-agent
Installing collected packages: contrast-agent
  Attempting uninstall: contrast-agent
    Found existing installation: contrast-agent 3.2.0
    Uninstalling contrast-agent-3.2.0:
      Successfully uninstalled contrast-agent-3.2.0
Successfully installed contrast-agent-3.2.1

Known issues

Unless Contrast Technical Support advises you to do this, we do not recommend using a version of the Contrast Python agent that is ahead of the version available from your Contrast instance.
Check for the latest Python agent installation issues here: Python Agent installation issues

Agent Update Guides articles: