docs(controller): Telegraf Controller 1.2.0 follow-up updates

content/telegraf/controller/admin/audit-logs/_index.md

@@ -1,3 +1,3 @@
 ---
 title: Audit logs
 description: >
@@ -60,7 +60,8 @@
 - **Source**: IP address and user-agent of the request, where applicable.
 - **Outcome**: `Success`, `Failure`, or `Denied`.
 - **Timestamp**: when the event occurred, in UTC.
-- **Sequence number, hash, and previous hash**: used to detect tampering.
+- **Sequence number, hash, previous hash, and key fingerprint**: used to
+  detect tampering.
 
 ## Where audit logs are stored
 
@@ -89,10 +90,38 @@
 
 ## Tamper detection
 
-Each entry includes a SHA-256 hash that incorporates the entry's contents
-and the hash of the previous entry, forming a chain.
+Each entry includes an HMAC-SHA256 hash that incorporates the entry's
+contents and the hash of the previous entry, forming a chain.
+{{% product-name %}} computes the hash with a signing key that you configure
+at startup and records a fingerprint of that key (the first 16 hexadecimal
+characters of the key's SHA-256 digest) in the entry's `secretId` field.
 Sequence numbers are contiguous within and across monthly files.
-Any modification, deletion, or out-of-order insertion breaks the chain.
+Any modification, deletion, or out-of-order insertion breaks the chain, and
+an entry re-sealed with a different key fails signature verification.
+
+{{% product-name %}} verifies the current month's chain when audit logging
+starts and logs the result.
+The `GET /api/audit-logger/verify` endpoint verifies every retained monthly
+file on demand.
+See [Verify integrity](/telegraf/controller/admin/audit-logs/view/#verify-integrity).
+
+> [!Important]
+> #### The signing key is the trust boundary
+>
+> Anyone who can read the signing key can alter entries and re-sign the
+> chain.
+> Keep the key outside the audit log data directory, restrict who can read
+> it, and forward audit events to an external destination that the
+> {{% product-name %}} host cannot modify.
+> See [Forward audit events](/telegraf/controller/admin/audit-logs/enable-configure/#forward-audit-events).
+
+Entries written by {{% product-name %}} 1.1 and earlier were signed with a
+built-in key and carry the key fingerprint `123`.
+Upgrading does not rewrite them.
+The first entry signed with your key links to the last of those entries, so
+the chain stays continuous, but verification reports them separately as
+legacy entries because their signatures cannot prove that they were not
+altered before the upgrade.
 
 In a high-availability cluster, each node maintains its own hash chain and
 sequence numbers, so events from different nodes merged into a single stream do
@@ -107,11 +136,13 @@
 and is unavailable in the free tier.
 With a valid license:
 
-- Audit logging is **enabled at startup only** by setting `AUDIT_ENABLED`.
+- Audit logging is **enabled at startup only** by setting `AUDIT_ENABLED`
+  and configuring a signing key.
   See [Enable and configure audit logging](/telegraf/controller/admin/audit-logs/enable-configure/).
 - Only the retention period is modifiable at runtime, from the **Settings**
   page.
-- Only the **Owner** and **Administrator** roles can read audit log entries.
+- Reading audit log entries requires the `audit:read` permission, which the
+  **Owner** and **Administrator** roles hold.
   See [View audit logs](/telegraf/controller/admin/audit-logs/view/).
 
 {{< children hlevel="h2" >}}

content/telegraf/controller/admin/audit-logs/enable-configure.md

@@ -2,9 +2,9 @@
 title: Enable and configure audit logging
 list_title: Enable and configure audit logging
 description: >
-  Enable audit logging in Telegraf Controller at startup, configure the
-  retention period, and optionally forward audit events to syslog, a
-  webhook, or a file.
+  Enable audit logging in Telegraf Controller at startup with a signing key,
+  configure the retention period, and optionally forward audit events to
+  syslog, a webhook, or a file.
 aliases:
   - /telegraf/controller/audit-logs/enable-configure/
 menu:
@@ -17,9 +17,9 @@
   - /telegraf/controller/telegraf-enterprise/apply-license/
 ---
 
-Enable audit logging in {{% product-name %}} at startup, change the
-retention period as needed, and optionally forward events to external
-destinations for long-term storage or SIEM integration.
+Enable audit logging in {{% product-name %}} at startup with a signing key,
+change the retention period as needed, and optionally forward events to
+external destinations for long-term storage or SIEM integration.
 
 {{< telegraf/enterprise-feature "Audit logging" >}}
 
@@ -33,6 +33,8 @@
 
 - A valid [Telegraf Enterprise license](/telegraf/enterprise/)
   applied to your {{% product-name %}} instance.
+- A signing key of at least 32 characters.
+  See [Generate a signing key](#generate-a-signing-key).
 - Permission to modify the {{% product-name %}} startup environment (for
   example, the systemd unit file or startup environment).
 - The **Owner** or **Administrator** role to change the retention period
@@ -43,12 +45,58 @@
 >
 > Per {{% product-name %}}'s security policy, settings that change the
 > application's security boundary, including whether audit logging is
-> enabled and where audit events are forwarded, can only be changed at startup.
+> enabled, the signing key, and where audit events are forwarded, can only be
+> changed at startup.
 > Retention is the only audit setting that can be modified at runtime.
 
 ## Enable audit logging
 
-Set `AUDIT_ENABLED` to `true` before starting {{% product-name %}}.
+Audit logging requires two settings at startup: `AUDIT_ENABLED` set to
+`true`, and a signing key of at least 32 characters that {{% product-name %}}
+uses to sign each audit entry.
+Provide the key in one of the following ways:
+
+- The `AUDIT_HMAC_KEY` environment variable, which holds the key itself.
+- The `AUDIT_HMAC_KEY_FILE` environment variable or the
+  `--audit-hmac-key-file` command flag, which name a file that holds the key.
+  {{% product-name %}} trims surrounding whitespace, so a trailing newline
+  in the file is fine.
+
+If both are set, `AUDIT_HMAC_KEY` takes precedence.
+{{% product-name %}} never writes the key to disk or to the database.
+
+### Generate a signing key
+
+Any random string of at least 32 characters works as a key.
+To generate one and store it in a file:
+
+{{< code-tabs-wrapper >}}
+{{% code-tabs %}}
+[Linux/macOS](#)
+[Windows (PowerShell)](#)
+{{% /code-tabs %}}
+{{% code-tab-content %}}
+
+```bash
+openssl rand -base64 48 > /etc/telegraf-controller/audit-key
+chmod 600 /etc/telegraf-controller/audit-key
+```
+
+{{% /code-tab-content %}}
+{{% code-tab-content %}}
+
+```powershell
+-join ((48..57 + 65..90 + 97..122) | Get-Random -Count 48 | ForEach-Object { [char]$_ }) |
+  Set-Content -NoNewline "C:\ProgramData\TelegrafController\audit-key"
+```
+
+{{% /code-tab-content %}}
+{{< /code-tabs-wrapper >}}
+
+Store the file outside the audit log data directory and restrict read
+access to the account that runs {{% product-name %}}.
+
+### Start {{% product-name %}} with audit logging enabled
 
 {{< tabs-wrapper >}}
 {{% tabs %}}
@@ -59,12 +107,13 @@
 {{% /tabs %}}
 {{% tab-content %}}
 
-Add `AUDIT_ENABLED=true` to your systemd unit file (typically
-`/etc/systemd/system/telegraf-controller.service`):
+Add `AUDIT_ENABLED=true` and the key file path to your systemd unit file
+(typically `/etc/systemd/system/telegraf-controller.service`):
 
 ```ini
 [Service]
 Environment=AUDIT_ENABLED=true
+Environment=AUDIT_HMAC_KEY_FILE=/etc/telegraf-controller/audit-key
 ```
 
 Reload systemd and restart the service:
@@ -77,42 +126,55 @@
 {{% /tab-content %}}
 {{% tab-content %}}
 
-Set the variable, or pass `--audit-enabled` on the command line:
+Set the variables, or pass `--audit-enabled` and `--audit-hmac-key-file`
+on the command line:
 
 ```bash
 export AUDIT_ENABLED=true
+export AUDIT_HMAC_KEY_FILE=/etc/telegraf-controller/audit-key
 telegraf_controller --no-interactive
 ```
 
 ```bash
-telegraf_controller --audit-enabled --no-interactive
+telegraf_controller --audit-enabled \
+  --audit-hmac-key-file=/etc/telegraf-controller/audit-key \
+  --no-interactive
 ```
 
 {{% /tab-content %}}
 {{% tab-content %}}
 
-Set the variable in PowerShell, or pass `--audit-enabled` on the command line:
+Set the variables in PowerShell, or pass `--audit-enabled` and
+`--audit-hmac-key-file` on the command line:
 
 ```powershell
 $env:AUDIT_ENABLED="true"
+$env:AUDIT_HMAC_KEY_FILE="C:\ProgramData\TelegrafController\audit-key"
 ./telegraf_controller.exe --no-interactive
 ```
 
 ```powershell
-./telegraf_controller.exe --audit-enabled --no-interactive
+./telegraf_controller.exe --audit-enabled `
+  --audit-hmac-key-file="C:\ProgramData\TelegrafController\audit-key" `
+  --no-interactive
 ```
 
 {{% /tab-content %}}
 {{% tab-content %}}
 
-Pass `AUDIT_ENABLED=true` when starting the container:
+Pass `AUDIT_ENABLED=true` and mount the key file read-only when starting
+the container:
 
 ```bash
 docker run \
   --env AUDIT_ENABLED=true \
+  --env AUDIT_HMAC_KEY_FILE=/run/secrets/audit-key \
+  --volume /etc/telegraf-controller/audit-key:/run/secrets/audit-key:ro \
   influxdata/telegraf-controller:{{< latest-patch >}}
 ```
 
+The container runs as the `telegraf-controller` user (UID `10001`), so the
+key file must be readable by that user.
 Include your standard container options, such as EULA acceptance, published
 ports, and the data volume.
 See [Run {{% product-name %}} in Docker](/telegraf/controller/install/docker/).
@@ -125,9 +187,34 @@
 - The **Settings > Audit Logging** section displays as enabled.
 - Audit entries begin appearing in the platform data directory described in
   [Where audit logs are stored](/telegraf/controller/admin/audit-logs/#where-audit-logs-are-stored).
+- The server log reports the result of the startup chain check.
+  See [Verify integrity](/telegraf/controller/admin/audit-logs/view/#verify-integrity).
 
 {{< img-hd src="/img/telegraf/controller-settings-audit-retention.png" alt="Telegraf Controller audit log retention dropdown" />}}
 
+### Start without a key
+
+If `AUDIT_ENABLED` is `true` but no signing key is configured, or the key is
+shorter than 32 characters, {{% product-name %}} starts with audit logging
+disabled and logs the reason, for example:
+
+```
+Audit HMAC key is not configured: set AUDIT_HMAC_KEY or pass --audit-hmac-key-file; audit logging stays disabled
+```
+
+The **Settings > Audit Logging** section displays as disabled until you
+restart with a key.
+
+When you start the executable in a terminal without `--no-interactive` and
+no key is configured, {{% product-name %}} prompts for the key instead:
+
+```
+Audit log signing key (at least 32 characters, empty to start without audit logging):
+```
+
+Input is hidden, and the key applies to that run only.
+Press Enter without a key to start with audit logging disabled.
+
 ## Configure retention
 
 {{% product-name %}} keeps audit entries for 90 days (2160 hours) by default
@@ -176,6 +263,12 @@
 Forwarders are configured **at startup only** and run independently, which lets
 you enable any combination of syslog, webhook, and file forwarders.
 
+Every audit event is forwarded, including sign-in, sign-out, constant, and
+agent-deletion events.
+If a forwarder fails, {{% product-name %}} logs `Audit forward failed` with a
+running failure count and keeps running.
+The entry is still written to local storage.
+
 ### Forward to syslog
 
 Forward audit events to a syslog server over TCP or UDP.
@@ -229,6 +322,7 @@
 
 To turn audit logging off, remove `AUDIT_ENABLED` (or set it to a value
 other than `true`) and restart {{% product-name %}}.
+Starting without a signing key has the same effect.
 The startup-only policy applies in both directions: audit logging cannot be
 disabled from the UI.