Rewrite the Notifications documentation

docs/command_line_interface/README.md

@@ -1610,6 +1610,25 @@ Allows administrators to do the following:
 * configure email addresses to submit reports on events execution
 * execute custom scripts on events execution
 
+The settings are stored in <span class="notranslate">_/etc/sysconfig/imunify360/hooks.yaml_</span>.
+**Every event is disabled by default**, and on every panel except Plesk the file does not exist
+until something is configured, so an absent file is the normal state of a fresh installation. On
+Plesk the agent creates the file and enables a <span class="notranslate">SCRIPT</span> target on
+<span class="notranslate">CUSTOM_SCAN_MALWARE_FOUND</span>,
+<span class="notranslate">USER_SCAN_MALWARE_FOUND</span> and
+<span class="notranslate">REALTIME_MALWARE_FOUND</span> for the Imunify extension's
+<span class="notranslate">_send-notifications_</span> script — see
+[Plesk: managing delivery with Plesk Notifications](/features/panel_notifications/#plesk-managing-delivery-with-plesk-notifications).
+The same settings are available in
+the UI — see [Notifications](/features/#notifications) for what each event means, when it fires
+and how the messages are delivered.
+
+::::tip Note
+These are *event* notifications, sent by the server itself. They are not the same thing as the
+security digests that the hosting panel delivers — those are configured separately, see
+[Panel notifications (iContact)](/features/panel_notifications/).
+::::
+
 **Usage:**
 
 <div class="notranslate">
@@ -1728,10 +1747,20 @@ Rules:
 * <span class="notranslate">CUSTOM_SCAN_MALWARE_FOUND</span> – occurs when the on-demand scanning process has finished and malware found.
 
 
+::::tip Note
+The event name says which *scan type* produced the event, not who started the scan. A scheduled
+background scan (<span class="notranslate">`MALWARE_SCAN_SCHEDULE`</span>) reports itself as a
+**user scan**, so it triggers <span class="notranslate">`USER_SCAN_*`</span>, while
+<span class="notranslate">`CUSTOM_SCAN_*`</span> covers on-demand scans started from the admin UI or
+with <span class="notranslate">`malware scan`</span>. See
+[Which scan produces which event](/features/#which-scan-produces-which-event).
+::::
+
 Admin:
 
-* <span class="notranslate">default_emails</span> – specify the default list of emails used for all enabled admin email notifications.
+* <span class="notranslate">default_emails</span> – specify the default list of emails used for all enabled admin email notifications. Only plain addresses are accepted here; the keyword <span class="notranslate">`default`</span> is not.
 * <span class="notranslate">notify_from_email</span> – specify a sender of all emails sent by the Hooks.
+* <span class="notranslate">locale</span> – the language of the admin emails, for example <span class="notranslate">`en`</span> or <span class="notranslate">`ru`</span>. When it is not set, the template default is used. A locale is available only if the corresponding file exists in the template directory of the event (see [Adding custom email template](/command_line_interface/#adding-custom-email-template)).
 
 Let's review all options for a specific event on the <span class="notranslate">REALTIME_MALWARE_FOUND</span> example:
 
@@ -1761,10 +1790,18 @@ Let's review all options for a specific event on the <span class="notranslate">R
 
 <span class="notranslate">**ADMIN**</span>:
 
-* <span class="notranslate">period</span> – set a notification interval in minutes. The data for all events that happened within the interval will be accumulated and sent altogether.
+* <span class="notranslate">period</span> – set a notification interval in seconds. The data for all events that happened within the interval will be accumulated and sent altogether.
 * <span class="notranslate">admin_emails</span> – set `default` to use the default administrator emails and/or specify your emails for notifications.
 * <span class="notranslate">enabled</span> – notify (`True`) the administrator and a custom user list via email upon event occurrence.
 
+:::warning Note
+* <span class="notranslate">`period`</span> is in **seconds** for both targets. The UI labels the admin interval <span class="notranslate">_Notify every (mins)_</span> and converts the value for display, but the config and the CLI always use seconds. Aggregated events are dispatched by a cron job whose interval is the smallest configured period rounded to whole minutes, so a period below 60 seconds behaves like one minute.
+* Only <span class="notranslate">REALTIME_MALWARE_FOUND</span> and <span class="notranslate">SCRIPT_BLOCKED</span> accept <span class="notranslate">`period`</span>. The other events are sent as they occur and have no interval.
+* Email addresses are validated against <span class="notranslate">`^.+@(.+\.)+.+`</span>, so the domain part must contain a dot: <span class="notranslate">`root@localhost`</span> is rejected, <span class="notranslate">`root@localhost.localdomain`</span> is accepted.
+* Script paths must be absolute, and the script must be executable by the <span class="notranslate">`_imunify`</span> user — which also has to be able to traverse every directory on the way to it. A script under <span class="notranslate">_/root_</span> will never run.
+* <span class="notranslate">`update`</span> merges the JSON you pass into the current configuration, so you only need to send the keys you want to change.
+:::
+
 **Examples**:
 
 1. Update admin default emails:

docs/config_file_description/README.md

@@ -405,6 +405,23 @@ systemctl restart imunify360
 <td># your email to receive reports about critical issues, security alerts or system misconfigurations detected on your servers.</td></tr>
 <tr><td><span class="notranslate">enable_icontact_notifications: True</span></td>
 <td># enable/disable delivery of generic (iContact) messages via hosting panel notifications (cPanel iContact / Plesk Notifications). Messages are provided by the Imunify backend (subject + HTML body) and throttled by a per-message period limit. Default value is True. See <a href="/features/panel_notifications/">Panel notifications (iContact)</a>.</td></tr>
+<tr><th colspan="2" align="left"><span class="notranslate">DASHBOARD:</span></th></tr>
+<tr><td colspan="2"># <span class="notranslate"><code>notifications</code></span> holds one switch per <a href="/features/panel_notifications/#message-types">panel notification message type</a>. Every switch defaults to <span class="notranslate">True</span>; setting one to <span class="notranslate">False</span> stops the Imunify cloud from generating that message type for this server. These switches are also available in the UI as <span class="notranslate"><i>Settings → Notifications → Panel notifications</i></span>.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;notifications:</span></td><td></td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;malware_found: True</span></td>
+<td># a user or background scan found malicious files. Generated for <span class="notranslate">ImunifyAV/AV+</span> servers only.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;malware_detected: True</span></td>
+<td># the <a href="/features/#malware-database-scanner-mds">Malware Database Scanner</a> detected malware in a database.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;malicious_redirect_detected: True</span></td>
+<td># a malicious redirect was detected on a website.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;aibolit_vulnerable: True</span></td>
+<td># a vulnerable script was detected.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;insecure_wp_core: True</span></td>
+<td># an installed WordPress core has known vulnerabilities.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;outdated_wp_core: True</span></td>
+<td># an installed WordPress core version is outdated.</td></tr>
+<tr><td><span class="notranslate">&nbsp;&nbsp;&nbsp;&nbsp;scan_not_scheduled: True</span></td>
+<td># no scheduled malware scan is configured (<span class="notranslate"><code>MALWARE_SCAN_SCHEDULE.interval</code></span> is <span class="notranslate"><code>none</code></span>) and no user or background scan has run in the last 30 days.</td></tr>
 <tr><th colspan="2" align="left"><span class="notranslate">SMTP_BLOCKING:</span></th></tr>
 <tr><td><span class="notranslate">enable: False</span></td>
 <td># enable (<span class="notranslate">True</span>) or disable (<span class="notranslate">False</span>) (default value) SMTP Traffic Management. When enabled, the outgoing SMTP traffic would be blocked according to the settings.</td></tr>

docs/dashboard/README.md

@@ -1217,9 +1217,10 @@ The following tabs are available:
 * <span class="notranslate">[General](/dashboard/#general)</span>
 * <span class="notranslate">[Malware](/dashboard/#malware)</span>
 * <span class="notranslate">[Backups](/dashboard/#backups)</span>
-* <span class="notranslate">[Disables Rules](/dashboard/#disabled-rules)</span>
+* <span class="notranslate">[Disabled Rules](/dashboard/#disabled-rules)</span>
+* <span class="notranslate">[Features Management](/dashboard/#features-management)</span>
 * <span class="notranslate">[Attributions](/dashboard/#attributions)</span>
-* <span class="notranslate">[Notifications](/features/#notifications)</span>
+* <span class="notranslate">[Notifications](/dashboard/#notifications)</span>
 
 ### General
 
@@ -2234,3 +2235,16 @@ It is possible to enable the Service Status checker for Imunify360. Perform the
 If succeeded, the status of the Imunify360 service will be displayed at the Service Status section of Server Status.
 
 ![](/images/service_status.jpg)
+
+### Notifications
+
+Click <span class="notranslate">_Settings_</span> and choose the <span class="notranslate">_Notifications_</span>
+tab to configure who is told about scan and <span class="notranslate">Proactive Defense</span> events on
+this server, and which security emails the hosting panel delivers.
+
+![](/images/notifications-settings-i360.png)
+
+The tab controls two separate things:
+
+* <span class="notranslate">**Event notifications**</span> — an email and/or a script hook per event, fired by the server itself. Every event is disabled by default, except the malware hook the agent enables on Plesk. See [Notifications](/features/#notifications) for the event reference, the delivery mechanics and troubleshooting, or [`notifications-config`](/command_line_interface/#notifications-config) to configure the same settings from the command line.
+* <span class="notranslate">**Panel notifications**</span> — the security digests that the Imunify cloud generates and the hosting panel delivers. The <span class="notranslate">_Manage panel notifications_</span> button opens a dialog with a switch per message type; all of them are enabled by default. See [Panel notifications (iContact)](/features/panel_notifications/). The row is shown only on cPanel and Plesk.