1. F5 Distributed Cloud App Infrastructure Protection (AIP) Support
  2. User Guides
  3. Windows Agent

Deploy Distributed Cloud AIP Windows Agent 2.x Series

Overview

This document describes the installation and configuration steps for the F5 Distributed Cloud App Infrastructure Protection (AIP) host-based Windows Agent 2.x series.

Pre-Installation for the Distributed Cloud AIP Agent

Before you install the Distributed Cloud AIP host-based Agent, please ensure your environment supports one of the following Windows Server Operating System (OS) versions:

  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022

Run Distributed Cloud AIP Windows Agent in Least Privileged Account

If you want to run your Agent from a least privileged account, then starting in Distributed Cloud AIP Windows Agent 2.2.1 you will need to uninstall your existing Windows Agent and install the 2.2.1 version, using the new least privileged option, detailed in the instructions below. For more information on the differences between running the Agent on a root account and a least privileged account, see Windows Agent Permissions and Privileges.

Important

If you want the agent to monitor activity in Windows containers in Kubernetes, then you cannot run your Agent from a least privileged account.

Windows Application Container Support

If you want the Agent to monitor activity in Windows Application Containers, then starting in Distributed Cloud AIP Windows Agent 2.3.0 you will need to uninstall your existing Windows Agent and install the 2.3.0 or higher version, using the container installation flags detailed in the Command Line install instructions below.

Full support is available only for the containerd runtime environment. Microsoft provides documentation for configuring your Windows node pools to use containerd here.

Install the Distributed Cloud AIP Agent

Prerequisites

  • Access to a Distributed Cloud AIP account.
  • Ensure you have administrator privileges on the host to perform the installation.

Begin Agent Download

Click one of the following options to download the Windows Agent software:

  • To install the latest version, click this button: Latest Windows Installer
  • To pin a specific version of the Windows Agent, then use the following format: pkg.threatstack.com/v2/Windows/Threat+Stack+Cloud+Security+Agent.X.X.X.msi. Replace the X's with the release version number. The most recent release is 2.3.0.

Once you have downloaded the installer, select one of the installation methods below.

Windows Setup Installation

Important

Ensure you are logged into the machine on an administrator account before proceeding.

  1. Go to the location of the Threat Stack Cloud Security Agent.msi file.
  2. Double click the file to run it. A setup wizard window opens.
  3. Click the Next button.


    1_Win_2.4_Welcome.png

  4. If applicable, update the following settings:

    2_Win_2.4_Register.png

    1. Install Distributed Cloud AIP Cloud Security Platform to – By default, the installation location is "C:\Program Files\Threat Stack\". Click the Change... button to browse to a location of your choice.
    2. AIP URL – By default, the value is set to “https://app.threatstack.com”. Distributed Cloud AIP does not recommend changing this value.
    3. Enter the Ruleset Name – By default, the value is set to Windows Rule Set. You can include multiple rule sets by separating them with a comma. For example, to include a Windows and a PCI ruleset, type the following: 
      Windows Rule Set, PCI Rule Set
    4. Enter the Deployment Key – Your deployment key is required to complete the installation. To find your deployment key, log into Distributed Cloud AIP and go to the Settings page > Keys tab > Deployment Key section.
    5. Password for the ThreatStack Account – You can choose to have the Agent run under a least privileged account by specifying a new password for the Distributed Cloud AIP account, which will then be created for the Agent to run under.

      Important

      • The Windows Agent cannot check the health of the EventLog and/or Sysmon services when run as a least privileged account. A warning message is logged when the Agent starts to record this fact.
      • The Agent cannot monitor activities in a Windows container in Kubernetes in least privileged mode.

      Leave this field blank to allow the Agent to run using the default root “LocalSystem” account.

    6. Start the services after setup is complete checkbox – By default, the checkbox is selected. If you deselect the checkbox, then the Windows Agent installs services but does not start until you reboot the host.
    7. Monitor Sysmon Events checkbox – By default, this checkbox is not selected. Select this checkbox to enable the Distributed Cloud AIP Agent to monitor Sysmon events.
  5. Click the Next button.
  6. Once you review your selections, click the Install button. The Threat Stack Cloud Security Platform installs.

Note

If you have administrator privileges but are not logged into your administrator account, then when you click the Install button, a User Account Control (UAC) notification message displays.

  1. Once the installation completes, a confirmation message displays. Click the Finish button to close the window.
    Win_2.4_Complete.png
  2. To confirm the Windows Agent is running on the host, open a Command Prompt window.
  3. In the install directory, type the following command and press ENTER  
    tsagent status

    Your newly installed server displays in Distributed Cloud AIP on the Servers page.

Command Line Installation

The Agent can be installed from the command line by either using Windows PowerShell or a Command Line. The example below shows the installation process using the Command Line.

Important

Ensure you are logged into the machine on an administrator account before proceeding.

  1. Open the Command Line Window as an administrator.
  2. Type the following command and press ENTER:
    msiexec /qn /i "c:\path\to\threatstack.msi" TSDEPLOYKEY=<DEPLOY_KEY>
    The command line parameters are as follows:
    • “C:\path\to\threatstack.msi” – Indicates the location of the msi installer. For example, if the installer was saved in the Downloads folder on your server, then you type: 
      “C:\Users\Administrator\Downloads\threatstack.msi”
    • TSDEPLOYKEY – Indicates the deployment key used to register with the platform. Replace <DEPLOY_KEY> with your deployment key, which can be found by logging into Distributed Cloud AIP and going to the Settings page > Application Keys tab > Deployment Key section.
    • TSACCOUNTPASSWORD (optional) – You can choose to have the Agent run with the minimum necessary privileges and permissions by specifying a new password for the Agent. This then creates a “ThreatStack” account under which the Agent runs. For example, to create the “ThreatStack” account using the password 1234567890!@#$%^&*()qwerty, type: 
      TSACCOUNTPASSWORD=“1234567890!@#$%^&*()qwerty”

      Important

      • The Windows Agent cannot check the health of the EventLog and/or Sysmon services when run as a least privileged account. A warning message is logged when the Agent starts to record this fact.
      • The Agent cannot monitor activities in a Windows container in Kubernetes in least privileged mode.

      If you do not use this command, then the Agent defaults to using the “LocalSystem” root account.

    • TSPROXY=[insert proxy URL:PORT here](optional) – You can choose to forward TCP/IP connections through a forward proxy by adding this command. For example, to configure the Agent to use the proxy at http://10.11.12.13 listening on port 4567: 
      TSPROXY=http://10.11.12.13:4567
    • TSEVENTLOGLIST (optional) – You can choose to capture System Monitoring (Sysmon) events by adding the following command: 
      TSEVENTLOGLIST=“Security,Microsoft-Windows-Sysmon/Operational” 
    • TSCLOUDURL (optional) – Indicates the URL of the Distributed Cloud AIP platform. By default, the value is https://app.threatstack.com.
    • TSRULESETNAMES (optional) – Indicates the rule set(s) being used. The value defaults to the Windows Rule Set. You can include multiple rule sets by separating them with a comma. For example, to include a Windows and a PCI rule set, type the following:
      TSRULESETNAMES=“Windows Rule Set, PCI Rule Set”
    • TSSTARTSERVICES (optional) – You can set the Distributed Cloud AIP Agent (tsagent) service to not start after the installation by adding the following command: 
      TSSTARTSERVICES=”No”

      The services only start once you reboot the host.

    • INSTALLDIR (optional) – Indicates the installation location. By default, the value is "C:\Program Files\Threat Stack\".
    • TSENABLECONTAINERDMONITORING (optional) – To use the Agent to monitor a Windows container on Kubernetes, then run the following command: 
      TSENABLECONTAINERDMONITORING=”True”
    • TSCONTAINERPRUNEINTERVAL (optional) – Indicates how often the Agent clears stale container metadata from its internal cache. By default, the value is 30 seconds. To change the interval, run the following command: 
      TSCONTAINERPRUNEINTERVAL=”<number>s”

      where the value of <number> is a duration, such as 30s, 1m30s or 5m.

    The installation runs in the background. Once complete, a new command line displays.

  3. To confirm the Agent is running on the host, in the install directory, type the following command and press ENTER: 
    tsagent status

    If the correct parameters were used to install the Windows Agent, then a "tsagent is running and connected" message displays. Additionally, your newly installed server displays in Distributed Cloud AIP on the Servers page.

System Monitor (Sysmon) Installation and Configuration

The Distributed Cloud AIP Windows Agent leverages System Monitor(Sysmon) functionality to focus on security-related events. The majority of rules within the Windows Ruleset rely on Sysmon logs, so we recommend installing Sysmon for optimal performance of the Windows Agent and its associated rules. For customers who choose not to install Sysmon, the functionality of the Windows Agent is limited. However, the Agent will still be able to monitor the host (system) through File Integrity Monitoring (FIM) and a subset of events from the Security event log.

Given the volume of information logged by Sysmon, and some of the complexity and logic available to end users, it is best to apply a configuration file that filters out normal operating system processes and common applications. We recommend using SwiftOnSecurity's well-commented configuration file.

For a full list of Sysmon events supported by the Distributed Cloud AIP Agent, see this list.

Download Sysmon

      1. Review this Microsoft article for a description of Sysmon's functionality and configuration.
      2. Click the Sysmon Download button to download the Sysmon files as a .zip.
      3. Unzip into the C:\Temp directory.

        The downloaded Sysmon.zip file contains 3 files:

        • Eula.txt – An end user license agreement file.
        • Sysmon.exe – A 32-bit Sysmon binary used for installing on 32-bit operating systems.
        • Sysmon64.exe – A 64-bit Sysmon binary used for installing on 64-bit operating systems.
      4. Copy https://github.com/SwiftOnSecurity/sysmon-config/blob/master/sysmonconfig-export.xml file and save as a file in the C:\Temp\sysmonconfig.xml directory.

        Notes

        • SwiftOnSecurity provides a base configuration for a majority of Sysmon event IDs that can be used as a recommended security standard. Use the SwiftOnSecurity configuration to configure Sysmon.
        • Configure support for event IDs 23 – 25 separately, either by using a custom configuration of SwiftOnSecurity’s base configuration or a third-party Sysmon configuration.

Install Sysmon

Important

Ensure you are logged into the machine on an administrator account before proceeding.

      1. Open the Command Line window.
      2. Type the following command and press ENTER:
        sysmon -i sysmonconf.xml

        Note

        The command in this example assumes you downloaded the Sysmon configuration file to the same folder where you saved your Sysmon file.

Once installed, Sysmon starts writing logs to a newly created Event Log. You view the log within the Event Viewer by going to Applications and Services Logs > Microsoft > Windows > Sysmon > Operational.

This log file defaults to a maximum size of approximately 65 megabytes (MB). Sysmon rewrites the oldest logs once this limit is reached. This default size should be sufficient for most customers.

Configure the Distributed Cloud AIP Agent

Important

Ensure you are logged into the machine on an administrator account before proceeding.

    1. Open the Command Line window.
    2. Type the following command to enable monitoring of both the Security and Sysmon Event Logs and press ENTER:
      tsagent config --set EventLogs "Security,Microsoft-Windows-Sysmon/Operational"
    3. Type the following command to restart the Agent and press ENTER. 
      tsagent restart

      You now see events from Sysmon, such as event id 1 for process creation in the Distributed Cloud AIP platform.

FIM Event Configuration for Windows Application Containers

The Windows Agent automatically generates FIM events when installed in Windows containers in Kubernetes. However, you need to configure a FIM rule to receive alerts on FIM events from Windows containers in Kubernetes.

    1. Log into Distributed Cloud AIP.
    2. In the left navigation pane, click the Rules tab. The Rules page displays.
    3. Click the Add Rule button. The Add Rule page displays.
    4. Select a ruleset in which to create the new rule. The Windows Ruleset may be the best option.
    5. Select File Integrity Rule. The Add File Rule page displays.
    6. Fill in the relevant details for the rule and click the Next: File Paths button. A new screen displays.
    7. On the new screen, do the following:
      1. Set File Integrity Paths to \Users\*
      2. Select the Recursive checkbox.
      3. In the Within the paths listed above, ignore files that match: field, type “.doc”.
      4. From the Events to Monitor drop-down menu, select ALL.
    8. Click the Next: Deployment button. A new page displays.
    9. Modify your options as necessary.
    10. Click the Apply Tags button. A confirmation message displays stating that the rule was successfully created.

You will now receive alerts related to any creates/read/writes/deletes to any files in the Users directory and its child directories that do not end in *.doc across all drives, including those in containers.

Was this article helpful?
0 out of 0 found this helpful

Table of Contents

Related articles