diff --git a/docs/examples/output/syslog_output_examples.trst b/docs/examples/output/syslog_output_examples.trst index a8155f57..c58fb561 100644 --- a/docs/examples/output/syslog_output_examples.trst +++ b/docs/examples/output/syslog_output_examples.trst @@ -28,3 +28,36 @@ Send all alerts level 6 and above to 10.10.10.127 on port 515: 515 6 + + +Forward JSON alerts over TCP (no TLS): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 4.3.0 + +.. code-block:: xml + + + siem.example.com + 514 + tcp + json + + + +Forward CEF alerts over TLS to a collector on 6514: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 4.3.0 + +.. code-block:: xml + + + siem.example.com + 6514 + tcp + yes + yes + /etc/pki/tls/certs/ca-bundle.crt + cef + diff --git a/docs/manual/output/syslog-output.rst b/docs/manual/output/syslog-output.rst index ca488d7d..52a3a6d4 100644 --- a/docs/manual/output/syslog-output.rst +++ b/docs/manual/output/syslog-output.rst @@ -80,4 +80,44 @@ rule, location and the actual event that generated it): srcip: 192.168.2.190; user: root; Jul 25 13:26:24 slacker sshd[20440]: Accepted password for root from 192.168.2.190 port 49737 ssh2 +TCP and TLS +----------- + +.. versionadded:: 4.3.0 + +By default ``ossec-csyslogd`` still uses UDP. Set ``protocol`` to ``tcp`` for a +persistent stream with newline framing (RFC 6587 non-transparent). Enable TLS with +``tls`` (implies TCP). Optional ``tls_ca`` and ``tls_verify`` control certificate +validation (same idea as SMTP TLS in maild). + +TLS destinations require an OSSEC build with OpenSSL (``LIBOPENSSL_ENABLED``). The +socket is opened before chroot so hostnames and ``tls_ca`` paths resolve on the +host filesystem. On send failure, csyslogd reconnects once. + +.. code-block:: xml + + + siem.example.com + 6514 + tcp + yes + yes + /etc/pki/tls/certs/ca-bundle.crt + json + + + +Message size limits +------------------- + +``ossec-csyslogd`` builds each forwarded alert (default, CEF, JSON, or Splunk format) +into a fixed buffer of ``OS_MAXSTR`` bytes (6144). Longer alert bodies are truncated +with a trailing ``...``. Earlier releases used a 2048-byte buffer, which commonly +cut off CEF ``msg=`` fields around 2–3 KB (#1762). + +**UDP** (default) may still fragment or drop large datagrams on the network path +even when OSSEC emits the full buffer. **TCP** and **TLS** avoid UDP MTU truncation +for those payloads (still capped at the 6K assemble buffer). + + .. include:: ../../examples/output/syslog_output_examples.trst diff --git a/docs/syntax/ossec_config.syslog_output.trst b/docs/syntax/ossec_config.syslog_output.trst index 8eb21c98..1bcd8094 100644 --- a/docs/syntax/ossec_config.syslog_output.trst +++ b/docs/syntax/ossec_config.syslog_output.trst @@ -22,7 +22,55 @@ - Minimum alert level of the alerts to be forwarded. - - **Allowed:** 1 - 16 + - **Allowed:** 1 - 16 + + - protocol + + .. versionadded:: 4.3.0 + + - Transport for this syslog destination. TCP uses newline framing + (RFC 6587 non-transparent; one alert per line). Prefer TCP or TLS when + CEF/JSON alerts approach the 6K assemble limit and UDP would truncate + on the wire. + + - **Default** udp + + - **Allowed:** udp, tcp + + - tls + + .. versionadded:: 4.3.0 + + - Wrap the TCP connection in TLS (RFC 5425-style stream). Implies + ``protocol`` tcp. Requires an OSSEC build with OpenSSL + (``LIBOPENSSL_ENABLED``). ``tls=yes`` with ``protocol`` udp is an + error. + + - **Default** no + + - **Allowed:** yes, no + + - tls_verify + + .. versionadded:: 4.3.0 + + - Verify the peer certificate and hostname (or IP) when ``tls`` is yes. + Same idea as ``global.smtp_tls_verify`` for maild. Setting this to + ``no`` disables peer verification (not recommended in production). + + - **Default** yes + + - **Allowed:** yes, no + + - tls_ca + + .. versionadded:: 4.3.0 + + - Optional path to a CA certificate file (PEM). Loaded before chroot. If + unset, OpenSSL default verify locations are used when ``tls_verify`` + is yes. + + - **Allowed:** Path to a readable CA file - group