Flex Agent manual installation and configuration

Use this procedure to install Flex Agent manually on Linux. 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. Windows and macOS are not supported.
Supported languages: .NET, Java, Node.js, Python, and PHP
Required C standard library: GLibC or MUSL
Required: A Contrast API token
One of the following is required:
- Manual: cURL and shasum
- Debian: apt-get, cURL, gnupg2, and ca-certificates
- 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 CONTRAST__API__TOKEN with your Contrast API token.

curl -s https://download.flex.contrastsecurity.com/installer/install.sh | CONTRAST__API__TOKEN=<token> sudo bash

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.

curl -s -o /tmp/install.sh https://download.flex.contrastsecurity.com/installer/install.sh && \
curl -s -o /tmp/checksum.sha256 https://download.flex.contrastsecurity.com/installer/checksum.sha256 && \
if [[ "$(shasum -a 256 /tmp/install.sh | awk '{print $1}')" == "$(cat /tmp/checksum.sha256 | awk '{print $1}')" ]]; then \
  CONTRAST__API__TOKEN=<token> bash /tmp/install.sh; \
fi

Debian: To install with Debian, set AGENT_TOKEN first, then 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, set AGENT_TOKEN first, then 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 installation script: Use this command:

curl -s -o /tmp/install.sh https://download.flex.contrastsecurity.com/installer/install.sh

Run the installation: Use one of these commands and replace $AGENT_TOKEN with your Contrast API token.
```
sudo bash /tmp/install.sh --api-token $AGENT_TOKEN
```

For manual agent installation, use this command:

sudo /tmp/contrast-flex-agent/install.sh --api-token $AGENT_TOKEN --unattached

Find your application with the app command, which lists out all running processes with open ports:

sudo contrast-flex app

Enable instrumentation with the attach command with the ID from the previous app command:

sudo contrast-flex attach $ID true

Control agent attachment below contains instructions on how to change an installation on Linux 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 set false
```
2. Re-enable attachment with this command:
```
contrast-flex auto-attach set 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}
```
  Alternatively, set to default to defer to the global auto-attach setting.
3. Use your normal application start command to restart the application. The injector attaches to the agent automatically.

In this section: