IBM Cloud Docs
Set up the Workload Protection agent

Set up the Workload Protection agent

This tutorial describes how to install and configure the Workload Protection agent on Linux.

Workload Protection provides the following features to protect standalone Linux hosts:

  • Threat detection: identify threats and suspicious activity based on application, network and host activity by processing syscall events and investigate with detailed system captures.

  • Posture management: scan host configuration files for compliance and benchmarks such as CIS Linux Benchmark.

  • Host scanning: scan host packages, detect the associated vulnerabilities and identify the resolution priority based on available fixed versions and severity.

This tutorial only covers installing the Workload Protection agent on IBM Cloud® Virtual Servers for Virtual Private Cloud and IBM® Power® Virtual Server hosts running RHEL or SLES Linux. For more compatible operating systems and setup instructions, refer to the Workload Protection documentation under Managing the agent.

There are multiple ways to install the agent depending on your preferences and setup. This tutorial installs the agent through an installation script. For other methods, refer to the official Workload Protection documentation under Managing the agent.

Preparation

Collecting IBM Cloud Security and Compliance Center Workload Protection details

The following details are required to setup the Workload Protection agent:

  • access_key
  • api_endpoint
  • ingestion_endpoint

Getting the Access Key

The Access Key is a token needed to connect the agents to the IBM Cloud® Security and Compliance Center Workload Protection instance in IBM Cloud.

To get the access key for an IBM Cloud Security and Compliance Center Workload Protection instance, complete the following steps:

  1. Navigate to the Workload Protection overview.

    1. Log in to the IBM Cloud console.

    2. Go to the Menu icon Menu icon > Security.

    3. Click on your Workload Protection

  2. Click on Actions > Manage Key and note it down somewhere safe so you can use it in the next steps.

Getting the API and Ingestion Endpoints

Refer to REST API endpoints to find the right private API endpoint for your location.

Refer to Collector endpoints to find the right private ingestion endpoint for your location.

For API endpoint, make sure to note it down with preceding https:// but without any subdirectories like /api. Example:

  • API endpoint: https://private.us-south.security-compliance-secure.cloud.ibm.com

For Ingestion endpoint, make sure to note it down without preceeding https://and without any subdirectories. Example:

  • Ingestion endpoint: ingest.private.us-south.security-compliance-secure.cloud.ibm.com

Agent installation and Setup

The Workload Protection agent needs to be installed on each host. Thus, the following steps have to be performed on each host.

Determine the agent driver

  1. Depending on the kernel version of the linux distribution, a different agent driver is required. For kernel versions newer than 5.8, universal_ebpf is recommended and kmod for older kernel versions.

    To check the kernel version:

    uname -r

  2. Skip this step if your kernel version is 5.8 or newer. Otherwise, install the kernel headers:

    • on RHEL
    yum -y install kernel-devel-$(uname -r)
    • on SLES
    zypper -y install kernel-devel

For more information on the different agent drivers, refer to Understand Agent Drivers

Workload Protection agent installation

  1. If your instance requires a proxy for internet access, make sure it's activated

    export http_proxy=http://<proxy_host_or_ip_port>:3128
export https_proxy=http://<proxy_host_or_ip_port>:3128
export HTTP_PROXY=http://<proxy_host_or_ip_port>:3128
export HTTPS_PROXY=http://<proxy_host_or_ip_port>:3128
export no_proxy=161.0.0.0/0,10.0.0.0/8

  2. Download the installation script and make it executable, adjust the target directory to your needs:

    curl -L https://ibm.biz/install-sysdig-agent --output install-agent.sh
chmod +x install-agent.sh

  3. Run the installation script to install the Workload Protection agent. Make sure to replace ACCESS_KEY, INGESTION_ENDPOINT, and API_ENDPOINT with the values obtained previously:

    • For kernel version 5.8 or newer:
    ./install-agent.sh -a <ACCESS_KEY> -c <INGESTION_ENDPOINT> --collector_port 6443 --secure true --universal_ebpf --additional_conf 'sysdig_api_endpoint: <API_ENDPOINT>\nhost_scanner:\n  enabled: true\n  scan_on_start: true\nkspm_analyzer:\n  enabled: true'
    • For kernel versions older than 5.8:
    ./install-agent.sh -a <ACCESS_KEY> -c <INGESTION_ENDPOINT> --collector_port 6443 --secure true --kmod --additional_conf 'sysdig_api_endpoint: <API_ENDPOINT>\nhost_scanner:\n  enabled: true\n  scan_on_start: true\nkspm_analyzer:\n  enabled: true'

  4. Check that Workload Protection agent is running:

    ps -ef | grep sysdig

    To look for errors, use:

    grep -i error /opt/draios/logs/draios.log
# and
grep -i fatal /opt/draios/logs/draios.log

  5. Check the host shows up on the Workload Protection Dashboard

    • Navigate to the dashboard. You can refer to Creating a Workload Protection instance if you don't remember how to get there.
    • Select Integrations > Data Sources > Sysdig Agents.
    • It may take up to 15 minutes for the agent to show on the dashboard. If successful, it should look similar to this:

    Figure 1. Agent Data Source in Dashboard Example
    Agent Data Source in Dashboard Example

Next step: Get to know the dashboard

Troubleshooting

Downloading the agent installation script fails

  • Make sure your system has internet access
  • If you still can't download the script, you can try downloading it on your local machine and then transferring it to the remote system by using a method of your choice (e.g. scp).

I'm getting an error message saying my kernel headers don't match the expected version

  • For kernel versions 5.8 or newer, make sure to use universal_ebpf driver. For kernel versions older than 5.8, make sure to use kmod driver.
  • If your kernel version is 5.8 or older, make sure you installed the correct kernel headers as shown in Determine the agent driver
  • For more information about the different drivers, refer to Understand Agent Drivers

I see an error message in the logs saying that the endpoint can't be reached

  • Make sure you selected the correct endpoints. The region in the endpoint should match the region of your Workload Protection instance.
  • Check the endpoints in the config file located under /opt/draios/etc/dragent.yaml. Make sure they match the description in Getting the API and Ingestion Endpoints.
  • Make sure you didn't mix up the API and ingestion endpoints. API endpoint starts with https:// and ingestion endpoint start with ingestion.
  • Check the network connectivity of your instance, including firewalls and security groups. Refer to Workload Protection Endpoints to see which IP addresses need to be allowed for outbound traffic.

I have installed the agent as described and I don't see any error messages in /opt/draios/logs/draios.log but my host doesn't show up in the dashboard

  • Check you have the correct endpoints and access key
  • Give it some time, it may up to 15 minutes take a while for the agent to show up in the dashboard.

Additional resources