Overview
This guide offers examples to easily update the Contrast .NET Framework 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.
The .NET Framework has 2 versions, legacy and modern. The method of keeping the agent up to date will depend on which of the legacy/modern agent you are using.
Main steps
There are three ways to update the .NET Framework agent:
- Option 1: Automatically update the agent
- Option 2: Download the agent from the JFrog repository (legacy agent versions only)
- Option 3: Use the Contrast API to download the agent and install at the command line
Supported technologies
Before you begin, please be sure Contrast supports your preferred tools and environments for .NET Framework: https://docs.contrastsecurity.com/en/-net-framework-supported-technologies.html
This guide assumes you have:
- Confirmed your .NET Framework application runs properly without the Contrast .NET Framework agent.
- Previously successfully installed the Contrast .NET Framework agent.
- Defined a policy for how and when to update the agent, based on your change management policy, workflow, and the environment where you deploy agents.
- Some familiarity with Windows scripting methods, including PowerShell
Instructions
There are three methods to keep the agent up to date. The one you choose partially depends on which version of the .NET Framework agent you have:
- The modern agent automatically updates. Contrast supports and releases new versions of the modern agent.
- This is agent versions 20.5.1 and higher
- The legacy agent does not auto-update. Except for critical bug fixes, Contrast does not fully support this agent. See more: https://docs.contrastsecurity.com/en/legacy--net-framework-supported-technologies.html
- This is agent versions 20.4.5 and lower. Any fixes for the legacy agent may expand release numbers to 20.4.6, 20.4.7, etc.
- Note: version 20.4.3 will not auto-update on WS2008 or if .NET 4.7.1 is not present
Option 1: Automatically update the agent
The .NET Framework agent automatically updates when you:
- Restart the IIS server
- Restart the Agent Tray
- Restart the Contrast .NET Windows service
- Modify and save the contrast_security.yaml file
- Use the following settings in the contrast_security.yaml file, so the agent checks for updates daily. You can still use the previous options for automatic updates without changing these settings.
Note: you must set the enable configuration value to true and use the same formatting:
agent: |
The modern agent will not auto-update if it detects an unsupported environment.
When the agent detects a newer version from Contrast and begins the update, you will see Contrast Tray messages like these:
Option 2: Download the agent from the Jfrog repository (legacy agent only)
If you need to stay on the legacy agent, you can download it from Jfrog Artifactory.
- The latest legacy agent version is 20.4.6 (as of February 2021). You can get it here:
https://pkg.contrastsecurity.com/ui/repos/tree/General/dotnet-legacy-release
- This agent does not automatically update. You will need to manually update it: check for any updates because of critical bug fixes, download the new version, and install it.
After you download the agent, use the silent installer via the command line to update the agent:
ContrastSetup.exe -s -norestart
|
Option 3: Use the Contrast API to download the agent
You can download the Contrast agent directly from the Contrast API. This works for both SaaS and enterprise on-premises (EOP) instances of Contrast.
- You need an account (service or user) to access the API
- Note: if you have an On-Premise installation of Contrast, you can manually update the agent archive that is bundled with your installation.
- After you download the updated agent, use the silent installer to install it at the command line. This can also be part of a script you normally use. For more, see Contrast documentation: https://docs.contrastsecurity.com/en/command-line-for--net-framework.html
Here is a sample PowerShell command to download the .NET agent from the Contrast API:
$ORG_ID = “Your Organization ID” |
Please replace the bolded variables with your values. You can find out your credentials through these steps.