Flex Agent manual installation and configuration

Instead of using the Multi-language agent wizard to install the Flex Agent, use this procedure to install it manually. This procedure might be useful if you are using automation to deploy applications at scale.

How the Flex Agent works

The Flex Agent analyzes processes as they start on a machine to determine if they're a candidate for agent instrumentation.

After installation, it provides an injector that determines the language of a process. If a corresponding agent is available for that process, it tries to attach one. When attachment succeeds, the agent instruments the process.

Using the standard agent configuration, agents report data to the Contrast web interface.

Before you begin

Root access is required
Supported operating system: Most versions of Linux
Required C standard library: GLibC or MUSL
Required: A Contrast API token
One of the following is required:
- Manual: tar and cURL.sha256sum (optional)
- Debian: apt-get, cURL, and gnupg2
- RPM: tee and yum

Install and attach the Flex Agent to all processes

Use these quick installation commands if you want the Flex Agent to attach agents to all running web processes.

cURL: To install with cURL, use this command and replace $AGENT_TOKEN with your Contrast API token.

curl -L --output /tmp/contrast-flex-agent.tar.gz https://contrastsecurity.jfrog.io/artifactory/flex-agent-release/latest/contrast-flex-agent.tar.gz
mkdir /tmp/contrast-flex-agent
sudo tar -xpzf /tmp/contrast-flex-agent.tar.gz -C /tmp/contrast-flex-agent
sudo /tmp/contrast-flex-agent/install.sh --api-token $AGENT_TOKEN

To verify the signature of the contrast-flex-agent.tar.gz download, run this command before you run the untar command. For any output other than OK, remove and re-download the artifact. Sha1 and MD5 checksums are available if you prefer to use them instead of Sha256.

curl -L --output /tmp/contrast-flex-agent.tar.gz.sha256 https://contrastsecurity.jfrog.io/artifactory/flex-agent-release/latest/contrast-flex-agent.tar.gz.sha256
hash=$(cat /tmp/contrast-flex-agent.tar.gz.sha256)
echo "$hash contrast-flex-agent.tar.gz" > /tmp/contrast-flex-agent.tar.gz.sha256
sha256sum --check /tmp/contrast-flex-agent.tar.gz.sha256

Debian: To install with Debian, use this command:

curl https://pkg.contrastsecurity.com/api/gpg/key/public | gpg -o /usr/share/keyrings/contrast-keyring.pgp --dearmor
echo "deb [signed-by=/usr/share/keyrings/contrast-keyring.pgp] https://pkg.contrastsecurity.com/debian-public/ $(sed -rne 's/^VERSION_CODENAME=(.*)$/\1/p' /etc/*ease) contrast" | tee /etc/apt/sources.list.d/contrast.list
echo "deb [signed-by=/usr/share/keyrings/contrast-keyring.pgp] https://pkg.contrastsecurity.com/debian-public/ all contrast" | tee -a /etc/apt/sources.list.d/contrast.list          
sudo apt-get update && sudo apt-get install -y contrast-flex-agent

RPM: To install with RPM, use this command:

rpm --import https://pkg.contrastsecurity.com/api/gpg/key/public
tee /etc/yum.repos.d/contrast.repo <<-"EOF"

[contrast]
name=Contrast redhat-$releasever repo
baseurl=https://pkg.contrastsecurity.com/rpm-public/redhat-$releasever/
gpgcheck=0
enabled=1
gpgkey=https://pkg.contrastsecurity.com/api/gpg/key/public
repo_gpgcheck=1
EOF

yum install contrast-flex-agent -y

Start (or restart) the application with your normal start command.

Install Flex Agent step-by-step

Use this procedure if you want the Flex Agent to attach agents to all running web processes, but want to manage all steps or modify installation instructions.

Download the Flex Agent tar file: Use this command:

curl -L --output /tmp/contrast-flex-agent.tar.gz https://contrastsecurity.jfrog.io/artifactory/flex-agent-release/latest/contrast-flex-agent.tar.gz

Extract the Flex Agent tar file: Use this command:

mkdir -p /tmp/contrast-flex-agent
tar -xpzf /tmp/contrast-flex-agent.tar.gz -C /tmp/contrast-flex-agent

Run the installation: Use one of these commands and replace $AGENT_TOKEN with your Contrast API token.
- For automatic agent installation, use this command:
```
sudo /tmp/contrast-flex-agent/install.sh --api-token $AGENT_TOKEN
```
- For manual agent installation, use these commands:
  1. Use this command:
    sudo /tmp/contrast-flex-agent/install.sh --api-token $AGENT_TOKEN --unattached
  2. Find your application with the app command, which lists out all running processes with open ports:
    sudo contrast-flex app
  3. Enable instrumentation with the attach command with the ID from the previous app command:
    sudo contrast-flex attach $ID true
  Control agent attachment contains instructions on how to change an installation to this style after your initial installation. Doing so does not remove instrumentation from running processes until you restart the application.

Control agent attachment

By default, the Flex Agent inspects all processes and tries to attach to agents automatically. If you want to change this behavior or specify specific processes for attachment, use the procedures in this section.

Control auto-attachment for all processes
1. If you want to stop the Flex Agent from attaching to all processes, disable auto-attach globally with this command:
```
contrast-flex auto-attach false
```
2. Re-enable attachment with this command:
```
contrast-flex auto-attach true
```
Using the auto-attach command does not attach or detach agents that are already in existing processes. For the new setting to take effect, restart the application.
Control process attachment
To control whether the Flex Agent attaches to a specific application process, use the attach command and specify the application's ID.
1. To determine the relevant process, use the app command and find process ID:
```
contrast-flex app
```
2. Enable or disable process attachment with this command, where ID is the process ID you found in the previous step:
```
contrast-flex attach ${ID} ${true|false}
```
3. Use your normal application start command to restart the application. The injector attaches to the agent automatically.

In this section: