diff --git a/README.md b/README.md index 285a530..115e3b3 100644 --- a/README.md +++ b/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 diff --git a/cmd/pulse-sensor-proxy/README.md b/cmd/pulse-sensor-proxy/README.md index c174a38..8473b7b 100644 --- a/cmd/pulse-sensor-proxy/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 9ed5fe7..81b1c67 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/operations/sensor-proxy-log-forwarding.md b/docs/operations/sensor-proxy-log-forwarding.md new file mode 100644 index 0000000..1435566 --- /dev/null +++ b/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).