Distributed Cloud AIP Containerized Agent

Overview

Containers are a standardized unit of software. A container packages an application’s code, configurations, and dependencies into a single unit that can be quickly and reliably deployed to any environment that supports containers, regardless of the underlying operating system (OS).

The F5 Distributed Cloud App Infrastructure Protection (AIP) Agent can be deployed as a container. You can deploy the containerized Agent on any supported Linux distribution in Docker-based container environments.

In the Agent 1.x series, the containerized Agent runs as a privileged container. By operating as a privileged container, the containerized Agent can talk to the kernel and other containers to ensure host security is adequately monitored. In the Agent 2.x and later (2.x+) series, the Agent does not need to run as a privileged container, but rather includes capabilities that can talk to the kernel and other containers.

In the Agent 1.x series, the containerized Agent has feature parity with the host-based Agent, with one exception: the customer must create a configuration file for the containerized Agent, as the deploy script does not automatically create one. In the Agent 2.x+ series, the configuration file is included with the deploy script.

Since customers deploy the containerized Agent in containerized environments, Distributed Cloud AIP does not support direct commands to the Agent. Do not use the following commands:

  • Agent 3.x series:
    • sudo tsagent start
    • sudo tsagent stop
    • sudo tsagent restart
    • sudo tsagent config
  • Agent 2.x series:
    • sudo tsagent start
    • sudo tsagent stop
    • sudo tsagent restart
    • sudo tsagent config
  • Agent 1.x series:
    • sudo cloudsight start
    • sudo clousight stop
    • sudo cloudsight restart
    • sudo cloudsight config

Notes

  • After deployment, customers only access the containerized Agent directly to gather logs for support requests. Container restarts, starts, and stops can be performed outside of the container, through the orchestration layer. For more information on the orchestration level, see Distributed Cloud AIP Kubernetes DaemonSet.
  • The containerized Agent is a standalone Agent and cannot be run side-by-side on the host with another Distributed Cloud AIP Agent.
  • Securing AWS Elastic Container Search (ECS) workloads requires the Distributed Cloud AIP host-based Agent. For more information, see FAQ: How do I secure my AWS ECS workload with Distributed Cloud AIP?
  • If you want to constrain Agent memory and CPU utilization, you can configure the Agent to use Self-Control to further conserve resources. For more information, see Self-Control Agent Resource Utilization.
System Consideration for the Containerized Agent

To optimize performance of your containerized Agent, we recommend configuring your host following these guidelines:

  • Allocate enough host memory to run a 256 mebibyte (MiB) application.
    • It can be increased to 384MiB or more for performance as necessary.

    Tip

    Specify limits for CPU and memory values the Agent can utilize. For more information about the minimum and maximum ranges for these values, see:

  • Ability to disable auditd on the host to ensure all Agent services run, including the Audit Collection Service.
    • From the Command Line, enter the following commands to stop and disable auditd:
      sudo systemctl stop auditd
      sudo systemctl disable auditd
  • Configure outbound network connectivity over port 443.
  • Allow the container to mount a file system on the host.
What Information Does the Containerized Agent Collect?

The containerized Agent collects the same information collected by the non-containerized Agent.

Additionally, the Docker rule set is recommended to be added for the containerized Agent.

How Do I Deploy the Containerized Agent?

Prerequisites

  • Access to DockerHub
  • Docker installed and running

    Note

    If Docker is not installed or is not running, then any attempt to start the Agent will result in the Agent exiting and an error message that states: “If problems persist, please disable tscontainers.”.

  • Access to the Distributed Cloud AIP containerized Agent
  • Access to the Distributed Cloud AIP console

Warning

There is a known Linux issue where the default auditd process only allows one connection for audit socket control. As a result, any applications that use auditd conflict with the Distributed Cloud AIP Agent over access to socket control. This can cause customer issues for several reasons:

  • The customer uses non-Distributed Cloud AIP audit rules to process logs.
  • The customer sends all logs to an SIEM or other log aggregator.
  • The customer deploys non-Distributed Cloud AIP agents that need access to auditd data.

For information about a workaround that addresses this issue, see FAQ: Workaround for the Known Linux Limitation with auditd.

Tip

Distributed Cloud AIP recommends using side-by-side windows – one browser window for DockerHub and one window for the Command Line – to deploy the Agent.

Docker Restart Policies and the Distributed Cloud AIP Agent

Docker provides restart policies to control whether your containers start automatically when they exit, or when Docker restarts. Restart container policies can be used in conjunction with containerized Agent deployments.

To configure the restart policy for a container, use the --restart flag when using the docker run command.

  • --restart no: It indicates the container will not automatically be restarted. Specify this command to be immediately alerted if you are using a monitoring solution, and if the Distributed Cloud AIP Agent and the related container are no longer present on the host.
  • --restart always: It indicates the container will always be restarted if it stops. Specify this command to prevent the Distributed Cloud AIP Agent and the related container from being terminated when automatic updates are run.

Note

Distributed Cloud AIP does not have a recommended default restart policy.

For more information, see Docker restart policies.

Deploy Containerized Agent for 3.x Series

Note

Beginning with Linux Containerized Agent version 2.3.3, the Distributed Cloud AIP Agent supports both ARM 64-bit and x86 64-bit architecture. The multi-architecture Agent tag allows you to pull the correct container Agent for your environment's underlying system architecture. However, as the Agent only pulls the target architecture's image, if you tag or push the container Agent to your own container registry, rather than directly from Docker, then you will only push the single architecture that you pulled.

To recreate the multi-architecture tag for a private registry, we recommend pulling the architecture-specific images and using the docker manifest command to create your own internal multiarchitecture-image.

  1. Open the Command Line.
  2. Paste the deploy command from threatstack/ts-docker2, append the following, and press ENTER:
    :latest

    Example:

    docker pull threatstack/ts-docker2:latest
  3. To find your image ID, type the following command and press ENTER:
    docker images

    Note

    Running this command displays a list of docker repositories, along with their respective IMAGE ID.

  4. Copy the image ID.
  5. The following command is the deploy command for the container. It should be entered as one block. Type or copy and paste the following command and press ENTER:
    export DEPLOY_KEY=<your deploy key> 
    sudo docker run -it -d \
    -e THREATSTACK_SETUP_ARGS="-deploy-key ${DEPLOY_KEY} -ruleset 'Base Rule Set, Docker Rule Set'" \
    -e THREATSTACK_CONFIG_ARGS="log.level info" \
    --name=ts-docker \
    --network=host \
    --pid=host \
    --security-opt=apparmor=unconfined \
    --cap-add=AUDIT_CONTROL \
    --cap-add=SYS_ADMIN \
    --cap-add=SYS_PTRACE \
    --cap-add=SYS_NICE \
    --cap-add=SYS_RESOURCE \
    --cap-add=IPC_LOCK \
    -v /:/threatstackfs/:ro \
    -v /sys/kernel/debug:/sys/kernel/debug \
    <paste IMAGE ID here>

    Replace <your deploy key> with your deployment key.

    Replace <paste your IMAGE ID here> with your Image ID you copied in step 4.

    Note

    The apparmor:unconfined parameter enables additional Distributed Cloud AIP Agent network syscall event enrichment. Specifically, it includes information about the local IP and port. If you do not want to receive this information, then you can delete this line from the command.

    The containerized Agent successfully deploys to the Docker environment.

  6. Confirm the containerized Agent deployed correctly.
    1. Log into Distributed Cloud AIP and view the new server.
    2. Log into the container and run the following command:
      sudo docker exec <container name> tsagent status
      Replace <container name> with the container name specified in step 5 for --name.
Deploy Containerized Agent for 2.x Series

Note

Beginning with Linux Containerized Agent version 2.3.3, the Distributed Cloud AIP Agent supports both ARM 64-bit and x86 64-bit architecture. The multi-architecture Agent tag allows you to pull the correct container Agent for your environment's underlying system architecture. However, as the Agent only pulls the target architecture's image, if you tag or push the container Agent to your own container registry, rather than directly from Docker, then you will only push the single architecture that you pulled.

To recreate the multi-architecture tag for a private registry, we recommend pulling the architecture-specific images and using the docker manifest command to create your own internal multiarchitecture-image.

  1. Open the Command Line.
  2. Paste the deploy command from threatstack/ts-docker2, append the following, and press ENTER:
    :latest

    Example:

    docker pull threatstack/ts-docker2:latest
  3. To find your image ID, type the following command and press ENTER:
    docker images

    Note

    Running this command displays a list of docker repositories, along with their respective IMAGE ID.

  4. Copy the image ID.
  5. The following command is the deploy command for the container. It should be entered as one block. Type or copy and paste the following command and press ENTER:
    $ export DEPLOY_KEY=<your deploy key>
    $ sudo docker run -it -d \
    -e THREATSTACK_SETUP_ARGS="--deploy-key ${DEPLOY_KEY} --ruleset 'Base Rule Set, Docker Rule Set'" \
    -e THREATSTACK_CONFIG_ARGS="enable_containers 1" \
    --name=ts-docker \
    --network=host \
    --pid=host \
    --security-opt=apparmor:unconfined \
    --cap-add=AUDIT_CONTROL \ --cap-add=SYS_ADMIN \
    --cap-add=SYS_PTRACE \
    --cap-add=SYS_NICE \
    -v /:/threatstackfs/ \
    -v /run/containerd/containerd.sock:/run/containerd/containerd.sock \
    -v /var/run/docker/containerd/docker-containerd.sock:/var/run/docker/containerd/docker-containerd.sock \
    -v /var/run/docker.sock:/var/run/docker.sock \
    <paste IMAGE ID here>

    Replace <your deploy key> with your deployment key.

    Replace <paste your IMAGE ID here> with your Image ID you copied in step 4.

    Note

    The apparmor:unconfined parameter enables additional Distributed Cloud AIP Agent network syscall event enrichment. Specifically, it includes information about the local IP and port. If you do not want to receive this information, then you can delete this line from the command.

    The containerized Agent successfully deploys to the Docker environment.

  6. Confirm the containerized Agent deployed correctly.
    1. Log into Distributed Cloud AIP and view the new server.
    2. Log into the container and run the following command:
      sudo docker exec <container name> tsagent status
      Replace <container name> with the container name specified in step 5 for --name.
Deploy Containerized Agent for 1.x Series
  1. Open the Command Line.
  2. Paste the deploy command copied from threatstack/ts-docker, append the following, and press ENTER:
    :latest

    Example:

    docker pull threatstack/ts-docker:latest
  3. Create a configuration file. Distributed Cloud AIP suggests creating it in /etc/ts-agent and name it "ts-config". Ensure the “configuration”: variable is present. Ensure your deploy key is present. Example below. Or Download a sample ts-config.json file.
    {

    "deploy-key": "<your deploy key>",

    "agent_type": "i",

    "ruleset": "Base Rule Set, Docker Rule Set",

    "configuration": {

    "enable_containers":1,

    "log_level": "info"

    }

    }

    Warning

    If you do not provide a configuration file, or if you provide a misconfigured configuration file, then the deployment of the containerized Agent will not work.

  4. To find your image ID, type the following command and press ENTER:
    docker images

    Note

    Running this command displays a list of docker repositories, along with their respective IMAGE ID.

  5. Copy the image ID.
  6. The following command is the deploy command for the container. It should be entered as one block. Type or copy and paste the following command and press ENTER:
    sudo docker run -it -d \
    -e THREATSTACK_CONFIG_PATH="/etc/ts-agent/ts-config" \
    --name=ts-docker \
    --privileged \
    --network=host \
    --pid=host \
    --cap-add=AUDIT_CONTROL \
    --cap-add=AUDIT_READ \
    --cap-add=NET_ADMIN \
    --cap-add=SYS_ADMIN \
    -v /:/threatstackfs/ \
    -v /var/run/docker.sock:/var/run/docker.sock
    <paste IMAGE ID here>

    Replace <paste IMAGE ID here> with the image ID copied in step 5.

    The containerized Agent successfully deploys to the Docker environment.

  7. Confirm the containerized Agent deployed correctly.
    1. Log into Distributed Cloud AIP and view the new server.
    2. Log into the container and run the following command:
      sudo docker exec <container name> cloudsight status
      Replace <container name> with the container name specified in step 6 for --name.
Was this article helpful?
0 out of 0 found this helpful