docs: document sensor proxy log forwarding

README.md

@@ -586,6 +586,7 @@ journalctl -u pulse -f
 - [Sensor proxy audit log rotation](docs/operations/audit-log-rotation.md) – Safely rotate append-only logs and verify poller health.
 - [Adaptive polling rollout](docs/operations/ADAPTIVE_POLLING_ROLLOUT.md) – Enable/disable the adaptive scheduler with guardrails.
 - [Automatic update management](docs/operations/auto-update.md) – Control the `pulse-update` timer/service, trigger manual runs, and roll back safely.
+- [Sensor proxy log forwarding](docs/operations/sensor-proxy-log-forwarding.md) – Ship audit/proxy logs to your SIEM via rsyslog + RELP.
 
 ## Development
 

cmd/pulse-sensor-proxy/README.md

@@ -82,7 +82,9 @@ all HTTP access attempts to the audit log.
 
 Follow `docs/operations/audit-log-rotation.md` for rotation (remove `+a`,
 truncate, restart service, reapply `+a`). Also consider forwarding with
-`scripts/setup-log-forwarding.sh` so audit data lands in your SIEM.
+`scripts/setup-log-forwarding.sh`; see
+`docs/operations/sensor-proxy-log-forwarding.md` for RELP/TLS forwarding
+instructions and verification steps.
 
 ## Metrics & Monitoring
 

docs/README.md

@@ -43,6 +43,7 @@ section groups related guides so you can jump straight to the material you need.
 - [operations/audit-log-rotation.md](operations/audit-log-rotation.md) – Rotate sensor proxy audit logs safely.
 - [operations/ADAPTIVE_POLLING_ROLLOUT.md](operations/ADAPTIVE_POLLING_ROLLOUT.md) – Step-by-step adaptive polling rollout guide.
 - [operations/auto-update.md](operations/auto-update.md) – Manage the automatic update timer/service.
+- [operations/sensor-proxy-log-forwarding.md](operations/sensor-proxy-log-forwarding.md) – Forward sensor proxy logs to a SIEM over RELP + TLS.
 
 ## Reference
 

docs/operations/sensor-proxy-log-forwarding.md

@@ -0,0 +1,73 @@
+# Sensor Proxy Log Forwarding
+
+Forward `pulse-sensor-proxy` logs to a central syslog/SIEM endpoint so audit
+records survive host loss and can drive alerting. Pulse ships a helper script
+(`scripts/setup-log-forwarding.sh`) that configures rsyslog to ship both
+`audit.log` and `proxy.log` over RELP + TLS.
+
+## Requirements
+
+- Debian/Ubuntu host with **rsyslog** and the `imfile` + `omrelp` modules (present
+  by default).
+- Root privileges to install certificates and restart rsyslog.
+- TLS assets for the RELP connection:
+  - `ca.crt` – CA that issued the remote collector certificate.
+  - `client.crt` / `client.key` – mTLS credentials for this host.
+- Network access to the remote collector (`REMOTE_HOST`, default `logs.pulse.example`,
+  port `6514`).
+
+## Installation Steps
+
+1. Copy your CA and client certificates into a safe directory on the host (the
+   script defaults to `/etc/pulse/log-forwarding`).
+2. Run the helper with environment overrides for your collector:
+   ```bash
+   sudo REMOTE_HOST=logs.company.tld \
+        REMOTE_PORT=6514 \
+        CERT_DIR=/etc/pulse/log-forwarding \
+        CA_CERT=/etc/pulse/log-forwarding/ca.crt \
+        CLIENT_CERT=/etc/pulse/log-forwarding/pulse.crt \
+        CLIENT_KEY=/etc/pulse/log-forwarding/pulse.key \
+        /opt/pulse/scripts/setup-log-forwarding.sh
+   ```
+   The script writes `/etc/rsyslog.d/pulse-sensor-proxy.conf`, ensures the
+   certificate directory exists (`0750`), and restarts rsyslog.
+
+## What the Script Configures
+
+- Two `imfile` inputs that watch `/var/log/pulse/sensor-proxy/audit.log` and
+  `/var/log/pulse/sensor-proxy/proxy.log` with `Tag`s `pulse.audit` and
+  `pulse.app`.
+- A local mirror file at `/var/log/pulse/sensor-proxy/forwarding.log` so you can
+  inspect rsyslog activity.
+- An RELP action with TLS, infinite retry (`action.resumeRetryCount=-1`), and a
+  50k message disk-backed queue to absorb collector outages.
+
+## Verification Checklist
+
+1. Confirm rsyslog picked up the new config:
+   ```bash
+   sudo rsyslogd -N1
+   sudo systemctl status rsyslog --no-pager
+   ```
+2. Tail the local mirror to ensure entries stream through:
+   ```bash
+   sudo tail -f /var/log/pulse/sensor-proxy/forwarding.log
+   ```
+3. On the collector side, filter for the `pulse.audit` tag and make sure new
+   entries arrive. For Splunk/ELK, index on `programname`.
+4. Simulate a test event (e.g., restart `pulse-sensor-proxy` or deny a fake peer)
+   and verify it appears remotely.
+
+## Maintenance
+
+- **Certificate rotation**: Replace the key/cert files, then restart rsyslog.
+  Because the config points at static paths, no additional edits are required.
+- **Disable forwarding**: Remove `/etc/rsyslog.d/pulse-sensor-proxy.conf` and run
+  `sudo systemctl restart rsyslog`. The local audit log remains untouched.
+- **Queue monitoring**: Track rsyslog’s main log or use `rsyslogd -N6` to check
+  for queue overflows. At scale, scrape `/var/log/pulse/sensor-proxy/forwarding.log`
+  for `action resumed` messages.
+
+For rotation guidance on the underlying audit file, see
+[operations/audit-log-rotation.md](audit-log-rotation.md).