Skip to main content

Manage agents with the Flex Agent

The Flex Agent has options that help you manage other Contrast agents. You can use these options without re-installing the Flex Agent.

Use the procedures in this topic to install the latest version of a specific agent as well as change settings for a default agent.

Note

All Flex Agent operations require elevated permissions. Run the following procedures as root or another user with proper write access.

How the Flex Agent works

When you intall or update agents with the Flex Agent, it accesses the agent's public repository and queries for the latest version. If that agent version is not currently installed on your system, the Flex Agent downloads that version.

When you update to the latest version, the updated agent becomes the default agent that attaches to any new process on the host.

Flex agent supported languages

The Flex Agent includes the latest, supported language, agents (at the time of the Flex Agent release). The currently supported languages are:

  • .NET Core

  • Java

  • Node.js

  • Python

  • PHP

List agents with the Flex Agent

To display a list of agents on your system, use the agents command.

Command usage:

contrast-flex-service agents [AGENT_LANGUAGE] or Usage: contrast-flex-service agents list [AGENT_LANGUAGE]

The AGENT_LANGUAGE option displays only the agents for the specified language. Specify one of the supported language options : java, dotnet-core, python, node, php.

If you don't specify a language, the command lists all agents.

Examples:

To see a list of all available agents, use this command:

contrast-flex-service agents list

To see a list of available agents for Java, use this command:

contrast-flex-service agents list java

Pin agents with the Flex Agent

Pinning an agent sets a default version of the agent to be attached to your application when not explicitly told to use a version for a given application. By default, the Flex Agent uses the latest version of an agent available.

To pin an agent, use the pin command.

Command usage:

Usage: contrast-flex-service agents pin <AGENT_LANGUAGE> <PIN_VERSION>

The AGENT_LANGUAGE option displays only the agents for the specified language. Specify one of the supported language options : java, dotnet-core, python, node, php.

The PIN_VERSION option must specify the latest or a valid semantic version

Example:

To make Java version 6.18.1 the default Java agent version, use this command:

contrast-flex-service agents pin java 6.18.1

Unpin agents with the Flex Agent

Unpinning an agent changes the previously set version to the latest agent version.

Command usage:

Usage: contrast-flex-service agents unpin <AGENT_LANGUAGE>

The AGENT_LANGUAGE option displays only the agents for the specified language. Specify one of the supported language options : java, dotnet-core, python, node, php.

Example:

To unpin the Java agent, use this command:

contrast-flex-service agents unpin java

Update agents with the Flex Agent

To update all agents or a specific agent language and version, use the update command.

Command usage:

contrast-flex agents update <AGENT_LANGUAGE> [UPDATE_VERSION]

The AGENT_LANGUAGE option displays only the agents for the specified language. Specify one of the supported language options : java, dotnet-core, python, node, php.

The UPDATE_VERSION option, if provided, must specify the latest or a valid semantic version. If you don't specify a version, the Flex Agent uses the latest version.

Examples:

To update Java agents to the the latest version, use this command:

contrast-flex-service agents java update 

To update Java agents to a specific version, use this command:

contrast-flex-service agents java update 6.20.1

Use custom repositories with the Flex Agent

You can use private or third party repositories for agent updates provided they follow the same standards as their public counterparts.

.NET Core and Nuget

By default, the Flex Agent reaches out to https://www.nuget.org to retrieve the Contrast.SensorsNetCore artifact of a specified version. To change location to a different repository, use this command:

contrast-flex config set-key flex_agent.agent.dotnet-core.repository ${URL}

Replace ${URL} with URL of your custom repository.

Java and Maven

By default, the Flex Agent reaches out to https://repo1.maven.org/maven2 to retrieve the com/contrastsecurity/contrast-agent artifact of a specified version. To change location to a different repository, use this command:

contrast-flex config set-key flex_agent.agent.java.repository ${URL}

Replace ${URL} with URL of your custom repository.

Node and NPM

By default, the Flex Agent reaches out to https://registry.npmjs.org to retrieve the @contrast/agent-bundle artifact of a specified version. To change location to a different repository, use this command:

contrast-flex config set-key flex_agent.agent.node.repository ${URL}

Replace ${URL} with URL of your custom repository.

Note

This artifact is slightly different than the standalone Node agent. To avoid reliance on npm being available, it requires dependencies to be bundled.

PHP and Debian

By default, the Flex Agent reaches out to https://pkg.contrastsecurity.com/debian-public to retrieve the contrast-php-agent artifact of a specified version. To change location to a different repository, use this command:

contrast-flex config set-key flex_agent.agent.php.repository ${URL}

Replace ${URL} with URL of your custom repository.

Note

This artifact is the Debian version of the agent. Other package manager formats are not supported

Python and PyPi

By default, the Flex Agent reaches out to https://pypi.org to retrieve the contrast-agent-bundle artifact of a specified version. To change location to a different repository, use this command:

contrast-flex config set-key flex_agent.agent.python.repository ${URL}

Replace ${URL} with URL of your custom repository.