Merge pull request #338 from atomicturtle/docs/issue-2028-realtime-limits

Fix for ossec issue #2028

Author: atomicturtle

docs/faq/syscheck.rst

@@ -1,7 +1,7 @@
 Syscheck: FAQ
 -------------
 
-.. contents:: 
+.. contents::
     :local:
 
 
@@ -104,6 +104,22 @@ To enable this functionality, <alert_new_files> must be set to yes inside the <s
 Also, the rule to alert on new files (rule 554) is set to level 0 by default. 
 The alert level will need to be raised in order to see the alert.
 Alerting on new files does not work in realtime, a full scan will be necessary to detect them.
+See :ref:`syscheck-realtime-limits`.
+
+Why don't permission changes alert immediately with realtime enabled?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``realtime="yes"`` uses filesystem event notifications to re-check files quickly, but only
+**content integrity** changes (checksums/size) on existing files produce immediate alerts.
+A ``chmod`` or ownership change on a monitored file is detected on the next **scheduled
+syscheck scan**, not at the moment the permission is changed. See :ref:`syscheck-realtime-limits`.
+
+Why does auto_ignore not suppress noisy realtime alerts?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``auto_ignore`` is applied on the manager when handling events from scheduled scans. Alerts
+from the realtime monitoring path are not subject to ``auto_ignore``. Use ``<ignore>`` or a
+local rule for files that change frequently in realtime directories.
 
 Add the following to local_rules.xml:
 

docs/manual/syscheck/index.rst

@@ -121,6 +121,15 @@ Real time Monitoring
 OSSEC supports realtime (continuous) file integrity monitoring on Linux (support was added kernel version 2.6.13) and Windows systems.
 
 The configuration is very simple. In the ``<directories>`` option where you specify what directories to monitor, adding ``realtime="yes"`` will enable it.
+
+.. warning::
+
+   **``realtime="yes"`` does not make every ``check_*`` option instantaneous.** Realtime
+   monitoring uses filesystem notifications (inotify on Linux, ``ReadDirectoryChangesW`` on
+   Windows) to detect changes quickly, but only **file content integrity** (checksum/size
+   changes on existing files) is evaluated in near real time. See :ref:`syscheck-realtime-limits`
+   below.
+
 For example:
 
 .. code-block:: xml
@@ -132,6 +141,36 @@ For example:
 
 In this case, the directories /etc, /usr/bin and /usr/sbin will be monitored in real time. The same applies to Windows too.
 
+.. _syscheck-realtime-limits:
+
+Realtime limitations
+^^^^^^^^^^^^^^^^^^^^
+
+Although ``check_all="yes"`` enables permission, ownership, group, size, and checksum
+monitoring for a directory, **realtime mode only alerts immediately for content integrity
+changes** (for example MD5, SHA1, or SHA256 hash changes) on files already present in the
+syscheck database.
+
+The following are **not** detected immediately when only realtime monitoring is enabled:
+
+* **Permission changes** (``check_perm``) — ``chmod`` and similar attribute updates are
+  picked up on the next **scheduled scan**, not instantly.
+* **Ownership or group changes** (``check_owner``, ``check_group``) — same as permissions;
+  wait for the next scheduled scan.
+* **New files** — requires the ``alert_new_files`` option and a full scan; see
+  :doc:`Why aren't new files creating an alert? </docs/faq/syscheck>`.
+
+Additionally:
+
+* **`auto_ignore`** is enforced on the manager when processing syscheck events from
+  scheduled scans. It **does not apply** to alerts generated by the realtime monitoring
+  path. For frequently changing files in realtime directories, use ``<ignore>`` or a local
+  rule instead.
+
+If you need immediate alerting on permission or ownership changes, combine realtime with an
+appropriate scan ``frequency`` and accept that metadata-only changes may lag until the next
+scan completes.
+
 .. warning:: 
 
     The real time monitoring will not start immediately. First ossec-syscheckd needs to scan the file system and add each sub-directory to the realtime queue.

docs/syntax/ossec_config.syscheck.trst

@@ -10,7 +10,15 @@
 
     - **realtime**: Value=yes
 
-        - This will enable realtime/continuous monitoring on Linux (using the inotify system calls) and Windows systems.
+        - Enable realtime/continuous monitoring on Linux (inotify) and Windows
+          (``ReadDirectoryChangesW``).
+
+        .. note::
+
+           Realtime mode alerts immediately on **file content integrity** changes (checksums
+           and size) for files already in the syscheck database. Permission, ownership, and
+           group changes are detected on the **next scheduled scan**, not instantly. See
+           :ref:`syscheck-realtime-limits`.
 
     - **report_changes**: Value=yes
 
@@ -138,6 +146,13 @@
 
     **Valid:** server, local
 
+    .. note::
+
+       ``auto_ignore`` applies to syscheck events processed from **scheduled scans** on the
+       manager. It does **not** apply to alerts from realtime monitoring. For noisy files
+       under ``realtime="yes"`` directories, use ``<ignore>`` or a local rule instead. See
+       :ref:`syscheck-realtime-limits`.
+
 .. _alert_new_files:
 .. object:: alert_new_files
 
@@ -152,6 +167,7 @@
     .. note::
 
        New files will only be detected on a full scan, this option does not work in realtime.
+       See :ref:`syscheck-realtime-limits`.
 
 .. object:: scan_on_start