feat(trend-micro) role and playbook

CHANGELOG.md

@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* **role:trend_micro_v1es**: Add a role to install and activate the Trend Vision One Endpoint Security agent (Endpoint Sensor and Server & Workload Protection).
 * **role:matomo_import_logs**: New role that imports Apache access logs into Matomo on a schedule, one systemd timer per site, and ships the Matomo log-analytics import script (`import_logs.py`). The `token_auth` is provided via a per-site auth file instead of the command line (passing `--token-auth`, `--login` or `--password` is deprecated, since they are visible in the process list and now log a deprecation warning). The script also supports the Traefik access-log format and fixes a possible endless loop when reading a config file.
 * **role:glances**: Add RHEL 10 / Rocky 10 / Alma 10 support by installing glances into a Python venv via the `python_venv` role, since the package is not available in EPEL 10. RHEL 10 is now marked proven (`x`) in COMPATIBILITY.
 * **role:graylog_datanode**: Add `graylog_datanode__http_publish_uri` to set the REST API URI the DataNode advertises, needed when the bind address is not directly reachable (multiple interfaces, a NAT gateway, or a `0.0.0.0` bind address).

COMPATIBILITY.md

@@ -162,6 +162,7 @@ Which Ansible role is proven to run on which OS?
 | timezone                              |  (x)   |  (x)   |   x    |   x    |    x    |    (x)    |    (x)    |    (x)    | Fedora 35                                    |
 | tmux                                  |  (x)   |  (x)   |  (x)   |   x    |   (x)   |    (x)    |    (x)    |    (x)    |                                              |
 | tools                                 |        |        |   x    |   x    |    x    |           |           |           | Fedora                                       |
+| trend_micro_v1es                      |        |        |   x    |   x    |    x    |           |           |           |                                              |
 | unattended_upgrades                   |  (x)   |  (x)   |        |        |         |    (x)    |    (x)    |    (x)    |                                              |
 | uptimerobot                           |        |        |        |        |         |           |           |           | controller-side, talks to UptimeRobot API    |
 | vsftpd                                |        |        |   x    |  (x)   |   (x)   |           |           |           |                                              |

README.md

@@ -463,6 +463,20 @@ ansible-user ALL=(ALL) NOPASSWD: ALL
 ```
 
 
+**Q: How do I route a role's outbound traffic through an HTTP proxy?**
+
+Some roles download installers or contact external APIs directly from the managed node. LFOps does not expose per-role proxy variables. Instead, set the proxy globally on the target in `/etc/environment`; the variables are picked up by tasks running over SSH, including key-based logins:
+
+```
+HTTP_PROXY=http://192.0.2.30:8080/
+HTTPS_PROXY=http://192.0.2.30:8080/
+http_proxy=http://192.0.2.30:8080/
+https_proxy=http://192.0.2.30:8080/
+```
+
+Set `NO_PROXY` / `no_proxy` (comma-separated hosts, domains or CIDRs) for destinations that must be reached directly.
+
+
 **Q: How do I find out which playbooks ran against a host?**
 
 All playbooks log every run to `/var/log/linuxfabrik-lfops.log` on the target host:

playbooks/README.md

@@ -1381,6 +1381,13 @@ Calls the following roles (in order):
 * [tools](https://github.com/Linuxfabrik/lfops/tree/main/roles/tools)
 
 
+## trend_micro_v1es.yml
+
+Calls the following roles (in order):
+
+* [trend_micro_v1es](https://github.com/Linuxfabrik/lfops/tree/main/roles/trend_micro_v1es)
+
+
 ## unattended_upgrades.yml
 
 Calls the following roles (in order):

playbooks/all.yml

@@ -145,6 +145,7 @@
 - import_playbook: 'timezone.yml'
 - import_playbook: 'tmux.yml'
 - import_playbook: 'tools.yml'
+- import_playbook: 'trend_micro_v1es.yml'
 - import_playbook: 'unattended_upgrades.yml'
 - import_playbook: 'vsftpd.yml'
 - import_playbook: 'yum_utils.yml'

playbooks/trend_micro_v1es.yml

@@ -0,0 +1,29 @@
+- name: 'Playbook linuxfabrik.lfops.trend_micro_v1es'
+  hosts:
+    - 'lfops_trend_micro_v1es'
+
+  pre_tasks:
+    - ansible.builtin.import_role:
+        name: 'shared'
+        tasks_from: 'log-start.yml'
+      tags:
+        - 'always'
+
+    - ansible.builtin.import_role:
+        name: 'shared'
+        tasks_from: 'global-variables.yml'
+      tags:
+        - 'always'
+
+
+  roles:
+
+    - role: 'linuxfabrik.lfops.trend_micro_v1es'
+
+
+  post_tasks:
+    - ansible.builtin.import_role:
+        name: 'shared'
+        tasks_from: 'log-end.yml'
+      tags:
+        - 'always'

roles/trend_micro_v1es/README.md

@@ -0,0 +1,194 @@
+# Ansible Role linuxfabrik.lfops.trend_micro_v1es
+
+This role installs and activates the [Trend Vision One Endpoint Security](https://www.trendmicro.com/en_us/business/products/hybrid-cloud/vision-one-endpoint-security.html) agent (`v1es`) on Linux servers. It covers pre-flight checks, agent download and installation via the XBC API, agent registration, and Server & Workload Protection (SWP) activation.
+
+
+*Available in the next LFOps release.*
+
+
+## How the Role Behaves
+
+Trend Vision One Endpoint Security combines two products on the same host, and this role configures both:
+
+* Endpoint Sensor (XDR/EDR) is the Endpoint Basecamp agent (`tmxbc`). It is downloaded and installed through the XBC API.
+* Server & Workload Protection (SWP) is the Deep Security agent (`ds_agent`). It ships inside the same full package and is activated against a Deep Security Manager (DSM).
+
+The "Server & Workload Protection (SWP)" deployment script generated in the Vision One console contains every value the role needs. It bundles both products in one full package: it lists two scenario IDs (one for the Endpoint Sensor, one for SWP) and carries the SWP activation values. The role installs that package, waits for the SWP agent to come up, and then activates it against the DSM.
+
+The role decides whether to run the install and activation by checking two files that the agents create once they are registered: `/opt/TrendMicro/EndpointBasecamp/etc/.identity` (Endpoint Sensor) and `/var/opt/ds_agent/dsa_core/ds_agent.crt` (SWP). Once both exist the role is a no-op, so re-running it against an installed host changes nothing. If either file is missing (a partial install, or one of the agents was removed) the role downloads the package again and reinstalls and reactivates both agents. To force a clean reinstall, remove the agents so both files are gone before running the role.
+
+Further reading:
+
+* Trend Micro concepts and products: https://docs.linuxfabrik.ch/software/trend-micro.html
+* Agent platform compatibility: https://help.deepsecurity.trendmicro.com/20_0/on-premise/agent-compatibility.html
+
+
+## Known Limitations
+
+The role does not configure an HTTP/HTTPS proxy. On hosts that reach the Trend Micro backends only through a proxy, set the proxy globally on the target so both the installer download and `tmxbc` pick it up, for example in `/etc/environment`:
+```bash
+HTTP_PROXY=http://192.0.2.30:8080/
+HTTPS_PROXY=http://192.0.2.30:8080/
+http_proxy=http://192.0.2.30:8080/
+https_proxy=http://192.0.2.30:8080/
+```
+
+
+## Requirements
+
+* At least 2 GB of RAM. The Server & Workload Protection agent (`ds_agent`) enforces this minimum during its pre-check; on a host with less memory the pre-check fails and `ds_agent` is never installed.
+* Running as `root` (use `become: true`).
+* `/tmp` must be writable on the target host.
+
+Supported architectures: `x86_64`, `aarch64`.
+
+Manual steps:
+
+* Generate the **Server & Workload Protection (SWP)** deployment script in the Vision One console and read the role variable values from it. This is mandatory: the script is the only source of the customer ID, company ID, scenario IDs and SWP activation values the role needs.
+  **Use the SWP deployment script, not the Endpoint-Sensor-only one.** The Endpoint-Sensor-only script lists a single scenario ID and none of the SWP activation values (tenant ID, token, DSM FQDN), so the SWP agent (`ds_agent`) cannot be installed.
+
+    1. In the Vision One console, make sure a "Server & Workload Protection" product instance exists. If not, create it under Service Management -> Create product instance -> Server & Workload Protection.
+    2. Navigate to Endpoint Security -> Endpoint Inventory -> Agent Installer -> Deployment Script.
+    3. Select "Server & Workload Protection" as the endpoint group and "Linux" as the operating system.
+    4. The previewed script contains every value the role needs.
+
+The script is a `bash` installer. Map its values to the role variables as follows (the script has separate `x86_64` and `aarch64` blocks; `company_id` is identical in both, only `scenario_ids` differ per architecture):
+
+| Role variable                                    | Where it appears in the deployment script                                     |
+| -------------                                    | -----------------------------------------                                     |
+| `trend_micro_v1es__customer_id`                  | `CUSTOMER_ID="..."`                                                           |
+| `trend_micro_v1es__group_id`                     | `GROUP_ID=...` (optional, defaults to `0`)                                    |
+| `trend_micro_v1es__policy_id`                    | `POLICY_ID=...` (optional, defaults to `0`)                                   |
+| `trend_micro_v1es__relay_group_id`               | `RELAY_GROUP_ID=...` (optional, defaults to `0`)                              |
+| `trend_micro_v1es__swp_dsm_fqdn`                 | the host in `dsa_control -a dsm://<host>:443/`                                |
+| `trend_micro_v1es__swp_login.tenant_id`          | `tenantID:...` in the `dsa_control` activation line                           |
+| `trend_micro_v1es__swp_login.token`              | `token:...` in the `dsa_control` activation line                              |
+| `trend_micro_v1es__xbc_env`                      | `XBC_ENV="..."` (optional, defaults to `prod-eu1`)                            |
+| `trend_micro_v1es__xbc_fqdn`                     | `XBC_FQDN="..."`                                                              |
+| `trend_micro_v1es__xbc_installer_company_id`     | `company_id` in the `HTTP_BODY` (identical in both `archType` blocks)         |
+| `trend_micro_v1es__xbc_installer_<arch>_scenario_ids`| `scenario_ids` in the `HTTP_BODY` of the matching `archType` block (both IDs) |
+
+
+## Tags
+
+`trend_micro_v1es`
+
+* Runs the pre-flight checks (supported architecture, scenario IDs, writable `/tmp`, minimum RAM).
+* Installs the required packages (`curl`, `tar`).
+* Downloads the installer from the XBC API and installs the Endpoint Sensor agent (`tmxbc`).
+* Waits for agent registration.
+* Activates Server & Workload Protection (`ds_agent`) against the Deep Security Manager.
+* Triggers: none.
+
+
+## Mandatory Role Variables
+
+`trend_micro_v1es__customer_id`
+
+* Customer ID used in the installer API request.
+* Type: String.
+
+`trend_micro_v1es__swp_dsm_fqdn`
+
+* Deep Security Manager FQDN used to activate Server & Workload Protection.
+* Type: String.
+
+`trend_micro_v1es__swp_login`
+
+* Server & Workload Protection activation credentials.
+* Type: Dictionary.
+* Subkeys:
+
+    * `tenant_id`:
+
+        * Mandatory. Tenant ID used to activate Server & Workload Protection.
+        * Type: String.
+
+    * `token`:
+
+        * Mandatory. Activation token used to activate Server & Workload Protection.
+        * Type: String.
+
+`trend_micro_v1es__xbc_installer_aarch64_scenario_ids`
+
+* List of scenario IDs for the aarch64 installer API request. Include all IDs from the deployment script (endpoint sensor and SWP). Required on aarch64 hosts only.
+* Type: List of strings.
+
+`trend_micro_v1es__xbc_installer_company_id`
+
+* Company ID for the installer API request. The same value for both architectures.
+* Type: String.
+
+`trend_micro_v1es__xbc_installer_x86_64_scenario_ids`
+
+* List of scenario IDs for the x86_64 installer API request. Include all IDs from the deployment script (endpoint sensor and SWP). Required on x86_64 hosts only.
+* Type: List of strings.
+
+Example:
+```yaml
+# mandatory
+trend_micro_v1es__customer_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+trend_micro_v1es__swp_dsm_fqdn: 'agents.workload.de-1.cloudone.trendmicro.com'
+trend_micro_v1es__swp_login:
+  tenant_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+  token: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+trend_micro_v1es__xbc_installer_aarch64_scenario_ids:
+  - 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+  - 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+trend_micro_v1es__xbc_installer_company_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+trend_micro_v1es__xbc_installer_x86_64_scenario_ids:
+  - 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+  - 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
+```
+
+
+## Optional Role Variables
+
+`trend_micro_v1es__group_id`
+
+* Agent group for organisation.
+* Type: Number.
+* Default: `0`
+
+`trend_micro_v1es__policy_id`
+
+* Security policy to apply. `0` means no specific policy.
+* Type: Number.
+* Default: `0`
+
+`trend_micro_v1es__relay_group_id`
+
+* Relay group for agent communication.
+* Type: Number.
+* Default: `0`
+
+`trend_micro_v1es__xbc_env`
+
+* XBC environment identifier.
+* Type: String.
+* Default: `'prod-eu1'`
+
+`trend_micro_v1es__xbc_fqdn`
+
+* XBC backend FQDN. Use the FQDN matching your region.
+* Type: String.
+* Default: `'api-eu1.xbc.trendmicro.com'`
+
+Example:
+```yaml
+# optional
+trend_micro_v1es__group_id: 10
+trend_micro_v1es__policy_id: 42
+trend_micro_v1es__relay_group_id: 5
+trend_micro_v1es__xbc_fqdn: 'api-us1.xbc.trendmicro.com'
+```
+
+
+## License
+
+[The Unlicense](https://unlicense.org/)
+
+
+## Author Information
+
+[Linuxfabrik GmbH, Zurich](https://www.linuxfabrik.ch)

roles/trend_micro_v1es/defaults/main.yml

@@ -0,0 +1,5 @@
+trend_micro_v1es__group_id: 0
+trend_micro_v1es__policy_id: 0
+trend_micro_v1es__relay_group_id: 0
+trend_micro_v1es__xbc_env: 'prod-eu1'
+trend_micro_v1es__xbc_fqdn: 'api-eu1.xbc.trendmicro.com'

roles/trend_micro_v1es/meta/argument_specs.yml

@@ -0,0 +1,67 @@
+argument_specs:
+  main:
+    options:
+
+      trend_micro_v1es__customer_id:
+        type: 'str'
+        required: true
+        description: 'Customer ID used in the installer API request.'
+
+      trend_micro_v1es__group_id:
+        type: 'int'
+        required: false
+        default: 0
+        description: 'Agent group for organisation. 0 means no specific choice.'
+
+      trend_micro_v1es__policy_id:
+        type: 'int'
+        required: false
+        default: 0
+        description: 'Security policy to apply. 0 means no specific choice.'
+
+      trend_micro_v1es__relay_group_id:
+        type: 'int'
+        required: false
+        default: 0
+        description: 'Relay group for agent communication. 0 means no specific choice.'
+
+      trend_micro_v1es__swp_dsm_fqdn:
+        type: 'str'
+        required: true
+        description: 'Deep Security Manager FQDN used to activate Server & Workload Protection.'
+
+      trend_micro_v1es__swp_login:
+        type: 'dict'
+        required: true
+        description: >-
+          Server & Workload Protection activation credentials. Must contain the
+          keys `tenant_id` and `token`.
+
+      trend_micro_v1es__xbc_env:
+        type: 'str'
+        required: false
+        default: 'prod-eu1'
+        description: 'XBC environment identifier.'
+
+      trend_micro_v1es__xbc_fqdn:
+        type: 'str'
+        required: false
+        default: 'api-eu1.xbc.trendmicro.com'
+        description: 'XBC backend FQDN. Use the FQDN matching your region.'
+
+      trend_micro_v1es__xbc_installer_aarch64_scenario_ids:
+        type: 'list'
+        elements: 'str'
+        required: false
+        description: 'List of scenario IDs for the aarch64 installer API request. Required on aarch64 hosts only.'
+
+      trend_micro_v1es__xbc_installer_company_id:
+        type: 'str'
+        required: true
+        description: 'Company ID for the installer API request. Same value for both architectures.'
+
+      trend_micro_v1es__xbc_installer_x86_64_scenario_ids:
+        type: 'list'
+        elements: 'str'
+        required: false
+        description: 'List of scenario IDs for the x86_64 installer API request. Required on x86_64 hosts only.'