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
- Use
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