From eeb1f64a1009a460bf3c6ec17a14f97ce72d905e Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Wed, 5 Aug 2026 11:25:21 -0400 Subject: [PATCH 1/2] Document FIM maintenance mode for patch windows. Replace the stop-manager syscheck_control -u FAQ with agent_control -M enable/disable workflow. --- docs/faq/syscheck.rst | 39 +++++++++++++++++++++++++++------ docs/programs/agent_control.rst | 19 ++++++++++++++++ 2 files changed, 51 insertions(+), 7 deletions(-) diff --git a/docs/faq/syscheck.rst b/docs/faq/syscheck.rst index 8ac80ed4..fb040fd6 100644 --- a/docs/faq/syscheck.rst +++ b/docs/faq/syscheck.rst @@ -154,11 +154,36 @@ and create a rule to alert when an appropriate log is created. How do I stop syscheck alerts during system updates? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There is no easy way to do this, but there are work-arounds. -Stop the OSSEC processes on the manager, and run ``/var/ossec/bin/syscheck_control -u AGENT_ID``. -This will clear the syscheck database for the agent, -and the next time syscheck runs it will create a new baseline. -Next, start the OSSEC processes on the manager. -Once the system update is complete, run a syscheck scan on that agent. -The database will be populated with new values, and should not trigger "file modified" alarms. +Use **FIM maintenance mode** on the manager so syscheck updates the integrity +database for that agent without generating alerts. The manager and other agents +keep running. + +1. Enable maintenance for the agent:: + + # /var/ossec/bin/agent_control -M enable -u AGENT_ID + +2. Apply OS patches / package updates on the host. + +3. Force a syscheck scan and wait for it to finish:: + + # /var/ossec/bin/agent_control -r -u AGENT_ID + + On the agent, look for ``Ending syscheck scan`` (and pre-scan completed if + applicable). + +4. Disable maintenance:: + + # /var/ossec/bin/agent_control -M disable -u AGENT_ID + +While maintenance is enabled, file modifications and new files are written into +the syscheck database as the new baseline and do **not** alert. After you +disable it, only subsequent changes generate alerts. + +Check status with ``agent_control -M status -u AGENT_ID`` or +``agent_control -i AGENT_ID``. + +The older workaround (stop the manager and run ``syscheck_control -u``) is no +longer necessary for patch windows. Clearing the database with +``syscheck_control -u`` remains available if you intentionally want a full +rebuild; prefer maintenance mode for routine updates. diff --git a/docs/programs/agent_control.rst b/docs/programs/agent_control.rst index 0bfa74cc..67c18185 100644 --- a/docs/programs/agent_control.rst +++ b/docs/programs/agent_control.rst @@ -6,6 +6,8 @@ agent_control The agent_control tool allows you to query and get information from any agent you have configured on your server and it also allows you to restart (run now) the syscheck/rootcheck scan on any agent. +It can also enable **FIM maintenance mode** so integrity updates during OS patching are absorbed +quietly into the syscheck database (see :option:`agent_control -M`). Enabling `active response <../manual/ar/index.html>`_ will be necessary to start scans remotely and possibly other functions. @@ -54,6 +56,23 @@ agent_control argument options that will perform the requested action. +.. option:: -M + + Per-agent FIM maintenance mode. ```` is one of ``enable``, + ``disable``, or ``status``. Must be used with :option:`agent_control -u`. + + While enabled, the manager updates that agent's syscheck integrity database + from incoming scans **without** generating file-modified or file-added + alerts. Use this around OS patching so package updates do not flood alerts; + then disable maintenance after a forced scan has absorbed the new baseline. + + Example:: + + # /var/ossec/bin/agent_control -M enable -u 002 + # /var/ossec/bin/agent_control -r -u 002 + # /var/ossec/bin/agent_control -M disable -u 002 + + agent_control example usage ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From d690767e019139f2c6b9b05e75d1a5207f377ada Mon Sep 17 00:00:00 2001 From: "Scott R. Shinn" Date: Wed, 5 Aug 2026 11:42:26 -0400 Subject: [PATCH 2/2] Document FIM maintenance -M end workflow and safeguards. --- docs/faq/syscheck.rst | 38 ++++++++++++++++++--------------- docs/programs/agent_control.rst | 18 ++++++++++------ 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/docs/faq/syscheck.rst b/docs/faq/syscheck.rst index fb040fd6..71e3af83 100644 --- a/docs/faq/syscheck.rst +++ b/docs/faq/syscheck.rst @@ -158,32 +158,36 @@ Use **FIM maintenance mode** on the manager so syscheck updates the integrity database for that agent without generating alerts. The manager and other agents keep running. -1. Enable maintenance for the agent:: +**Canonical workflow** (preferred):: - # /var/ossec/bin/agent_control -M enable -u AGENT_ID + # /var/ossec/bin/agent_control -M enable -u AGENT_ID + # … apply OS patches / package updates … + # /var/ossec/bin/agent_control -M end -u AGENT_ID -2. Apply OS patches / package updates on the host. +``-M end`` marks the agent for pending end, restarts syscheck/rootcheck, and +**clears maintenance automatically** when the agent reports +``syscheck-db-completed``. That avoids disabling mid-scan or forgetting a scan +and getting a flood afterward. -3. Force a syscheck scan and wait for it to finish:: +While maintenance is enabled: - # /var/ossec/bin/agent_control -r -u AGENT_ID +* File modifications and new files update the syscheck DB as the new baseline + and do **not** alert. +* Silent accepts are appended to ``logs/fim_maintenance.log`` on the manager. +* ``agent_control -l`` shows ``Maint`` (or ``Maint(pending-end)``) for agents + in this mode. +* Leaving maintenance on for more than 24 hours produces a periodic manager + WARN — keep windows short. Maintenance trusts FIM events (including malicious + ones) for that agent. - On the agent, look for ``Ending syscheck scan`` (and pre-scan completed if - applicable). +**Emergency:** ``agent_control -M disable -u AGENT_ID`` clears the flag +immediately without waiting for a scan. Prefer ``end`` for routine patching. -4. Disable maintenance:: - - # /var/ossec/bin/agent_control -M disable -u AGENT_ID - -While maintenance is enabled, file modifications and new files are written into -the syscheck database as the new baseline and do **not** alert. After you -disable it, only subsequent changes generate alerts. - -Check status with ``agent_control -M status -u AGENT_ID`` or +Check detail with ``agent_control -M status -u AGENT_ID`` or ``agent_control -i AGENT_ID``. The older workaround (stop the manager and run ``syscheck_control -u``) is no longer necessary for patch windows. Clearing the database with ``syscheck_control -u`` remains available if you intentionally want a full -rebuild; prefer maintenance mode for routine updates. +rebuild. diff --git a/docs/programs/agent_control.rst b/docs/programs/agent_control.rst index 67c18185..4162d105 100644 --- a/docs/programs/agent_control.rst +++ b/docs/programs/agent_control.rst @@ -59,18 +59,24 @@ agent_control argument options .. option:: -M Per-agent FIM maintenance mode. ```` is one of ``enable``, - ``disable``, or ``status``. Must be used with :option:`agent_control -u`. + ``disable``, ``status``, or ``end``. Must be used with + :option:`agent_control -u`. While enabled, the manager updates that agent's syscheck integrity database from incoming scans **without** generating file-modified or file-added - alerts. Use this around OS patching so package updates do not flood alerts; - then disable maintenance after a forced scan has absorbed the new baseline. + alerts. Silent accepts are logged to ``logs/fim_maintenance.log``. + ``agent_control -l`` marks agents with ``Maint`` or ``Maint(pending-end)``. - Example:: + **Preferred patch workflow**:: # /var/ossec/bin/agent_control -M enable -u 002 - # /var/ossec/bin/agent_control -r -u 002 - # /var/ossec/bin/agent_control -M disable -u 002 + # … apply OS patches … + # /var/ossec/bin/agent_control -M end -u 002 + + ``end`` restarts syscheck and clears maintenance when the baseline scan + completes. Use ``disable`` only for an immediate emergency clear (it does + not wait for a scan). Keep maintenance windows short; the manager warns if + an agent stays in maintenance longer than 24 hours. agent_control example usage