From 056f0c9efc00b7275a166a25b338091be6f5ea76 Mon Sep 17 00:00:00 2001
From: "Scott R. Shinn" <scott@atomicorp.com>
Date: Wed, 5 Aug 2026 15:14:21 -0400
Subject: [PATCH] Document modsec-audit log format and ModSecurity samples.

Describe the new serial audit collector format and add nginx/libmodsecurity
plus audit-log examples for ossec-hids#1390.
---
 .../security_devices/modsecurity.rst          | 28 +++++++++++++++++++
 docs/syntax/ossec_config.localfile.trst       | 26 +++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/docs/log_samples/security_devices/modsecurity.rst b/docs/log_samples/security_devices/modsecurity.rst
index 2aacd1d0..9cebde81 100644
--- a/docs/log_samples/security_devices/modsecurity.rst
+++ b/docs/log_samples/security_devices/modsecurity.rst
@@ -9,6 +9,34 @@ Access denied:
   [Sun Jan 16 10:56:49 2005] [error] [client 192.168.2.10] mod_security: Access denied with code 403. Pattern match "111" at THE_REQUEST [hostname "192.168.2.101"] [uri "/index.html?111"]
 
 
+Nginx / libmodsecurity error log:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+  2019/08/29 09:59:06 [error] 13#13: *1031 [client 203.0.113.10] ModSecurity: Access denied with code 403 (phase 2). Matched "Operator" against variable "ARGS:q" [id "941100"] [hostname "example.com"] [uri "/"] [unique_id "abc123"]
+
+
+Serial audit log (``modsec-audit``):
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configure logcollector with ``<log_format>modsec-audit</log_format>`` so each
+transaction (``--id-A--`` … ``--id-Z--``) is one event. Example sections:
+
+.. code-block:: console
+
+  --fbd13fc1-A--
+  [22/Dec/2015:15:25:00 +0000] VnhlYH8AAQEAADYdAUkAAAAA 127.0.0.1 55275 127.0.0.1 80
+  --fbd13fc1-B--
+  GET /?q=test HTTP/1.1
+  Host: localhost
+
+  --fbd13fc1-H--
+  Message: Access denied with code 403 (phase 2). Pattern match "test" at ARGS:q
+  Action: Intercepted (phase 2)
+  --fbd13fc1-Z--
+
+
 Access denied by pattern:
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/syntax/ossec_config.localfile.trst b/docs/syntax/ossec_config.localfile.trst
index 81aa4782..3e63ee3f 100644
--- a/docs/syntax/ossec_config.localfile.trst
+++ b/docs/syntax/ossec_config.localfile.trst
@@ -131,6 +131,32 @@
 
          - djb-multilog
 
+         .. _logformat_audit:
+
+         - audit
+             Linux Auditd log format.
+
+         .. _logformat_modsec-audit:
+
+         - modsec-audit
+             Serial ModSecurity / libmodsecurity audit logs (for example
+             ``/var/log/modsec_audit.log``). Logcollector gathers one transaction
+             from the ``--id-A--`` header through the ``--id-Z--`` trailer and
+             emits a single event for analysisd.
+
+             **Example:**
+
+             .. code-block:: xml
+
+                <localfile>
+                  <log_format>modsec-audit</log_format>
+                  <location>/var/log/modsec_audit.log</location>
+                </localfile>
+
+             Prefer monitoring the web server error log when possible; Apache and
+             Nginx ModSecurity error-log lines are also decoded. Use
+             ``modsec-audit`` when you need the full serial audit file.
+
          .. _logformat_multi-line:
 
          - multi-line