Add WAF defines and events

defines.rst

@@ -14,6 +14,7 @@
    defines/remote-ips
    defines/plugin
    defines/site-health
+   defines/waf
    defines/misc
    defines/development
    defines/reserved

defines/constants/WP_FAIL2BAN_EX_WAF.rst

@@ -0,0 +1,34 @@
+.. _WP_FAIL2BAN_EX_WAF:
+
+.. role:: php(code)
+  :language: php
+
+WP_FAIL2BAN_EX_WAF
+------------------
+
+.. rubric:: Control the state of the WAF.
+.. include:: default-disabled.rst
+.. rubric:: Premium Only
+
+.. versionadded:: 5.1.0
+
+----
+
+The state can be one of:
+
+on
+  Enabled; blocks detected threats.
+
+off
+  Disabled.
+
+logging
+  Detects and logs threats.
+
+.. code-block:: php
+   :caption: Example: Enabling logging only
+
+   /**
+    * WAF state.
+    */
+   define('WP_FAIL2BAN_EX_WAF', 'logging');

defines/constants/WP_FAIL2BAN_EX_WAF_LOG.rst

@@ -0,0 +1,20 @@
+.. _WP_FAIL2BAN_EX_WAF_LOG:
+
+WP_FAIL2BAN_EX_WAF_LOG
+----------------------
+
+.. rubric:: Facility for :ref:`WAF class <events_WAF>` events.
+.. include:: default-log_user.rst
+.. rubric:: Premium Only
+
+.. versionadded:: 5.1.0
+
+----
+
+.. code-block:: php
+   :caption: Example: Using LOG_LOCAL5
+
+   /**
+    * Facility for WAF events.
+    */
+   define('WP_FAIL2BAN_EX_WAF_LOG', LOG_LOCAL5);

defines/constants/WP_FAIL2BAN_EX_WAF_SQLI_PLUGINS.rst

@@ -0,0 +1,24 @@
+.. _WP_FAIL2BAN_EX_WAF_SQLI_PLUGINS:
+
+.. role:: php(code)
+  :language: php
+
+WP_FAIL2BAN_EX_WAF_SQLI_PLUGINS
+-------------------------------
+
+.. rubric:: Check plugin queries for SQLi.
+.. include:: default-disabled.rst
+.. rubric:: Premium Only
+
+.. versionadded:: 5.1.0
+
+----
+
+
+.. code-block:: php
+   :caption: Example: Enabling SQLi detection for plugins
+
+   /**
+    * WAF: check plugin queries for SQLi.
+    */
+   define('WP_FAIL2BAN_EX_WAF_SQLI_PLUGINS', true);

defines/constants/WP_FAIL2BAN_EX_WAF_SQLI_WORDPRESS.rst

@@ -0,0 +1,29 @@
+.. _WP_FAIL2BAN_EX_WAF_SQLI_WORDPRESS:
+
+.. role:: php(code)
+  :language: php
+
+WP_FAIL2BAN_EX_WAF_SQLI_WORDPRESS
+---------------------------------
+
+.. rubric:: Check WordPress core queries for SQLi.
+.. include:: default-disabled.rst
+.. rubric:: Premium Only
+
+.. versionadded:: 5.1.0
+
+----
+
+.. note::
+   This setting exists for testing; it is published for completeness.
+
+.. code-block:: php
+   :caption: Example: Enabling SQLi detection for WordPress core
+
+   /**
+    * WAF: check WordPress core queries for SQLi.
+    */
+   define('WP_FAIL2BAN_EX_WAF_SQLI_WORDPRESS', true);
+
+.. warning::
+   Do not enable this in normal operation without good technical justification.

defines/constants/WP_FAIL2BAN_EX_WAF_UPDATE_OPTION.rst

@@ -0,0 +1,25 @@
+.. _WP_FAIL2BAN_EX_WAF_UPDATE_OPTION:
+
+.. role:: php(code)
+  :language: php
+
+WP_FAIL2BAN_EX_WAF_UPDATE_OPTION
+--------------------------------
+
+.. rubric:: Check that current user may update core WordPress options.
+.. include:: default-disabled.rst
+.. rubric:: Premium Only
+
+.. versionadded:: 5.1.0
+
+----
+
+When a plugin tries to update a core WordPress option, check the current user has ``update_options`` or ``update_network_options`` capabilities.
+
+.. code-block:: php
+   :caption: Example: Enabling caps checking for update_option() on core WordPress options.
+
+   /**
+    * WAF: check caps for update_option().
+    */
+   define('WP_FAIL2BAN_EX_WAF_UPDATE_OPTION', true);

defines/logging.rst

@@ -43,6 +43,7 @@ Premium
 
    constants/WP_FAIL2BAN_EX_BLOCK_COUNTRIES_LOG
    constants/WP_FAIL2BAN_EX_XMLRPC_LOG
+   constants/WP_FAIL2BAN_EX_WAF_LOG
 
 Deprecated
 ^^^^^^^^^^

defines/waf.rst

@@ -0,0 +1,19 @@
+.. _waf:
+
+WAF
+---
+
+Premium
+^^^^^^^
+
+.. toctree::
+   :caption: State
+
+   constants/WP_FAIL2BAN_EX_WAF
+
+.. toctree::
+   :caption: SQLi
+
+   constants/WP_FAIL2BAN_EX_WAF_SQLI_PLUGINS
+   constants/WP_FAIL2BAN_EX_WAF_SQLI_WORDPRESS
+   constants/WP_FAIL2BAN_EX_WAF_UPDATE_OPTION

events.rst

@@ -123,3 +123,15 @@ XML-RPC events, including Pingbacks.
    events/xmlrpc/WPF2B_EVENT_XMLRPC_PINGBACK
    events/xmlrpc/WPF2B_EVENT_XMLRPC_PINGBACK_BOGUS
    events/xmlrpc/WPF2B_EVENT_XMLRPC_PINGBACK_ERROR
+
+.. _events_WAF:
+
+WAF Events
+----------
+
+Web Application Firewall (WAF) events.
+
+.. toctree::
+
+   events/waf/WPF2B_EVENT_WAF_SQLI
+   events/waf/WPF2B_EVENT_WAF_UPDATE_OPTION

events/waf/WPF2B_EVENT_WAF_SQLI.rst

@@ -0,0 +1,19 @@
+.. _WPF2B_EVENT_WAF_SQLI:
+
+WPF2B_EVENT_WAF_SQLI
+--------------------
+
+.. rubric:: SQLi detected.
+.. rubric:: *Premium only*
+
++----------+----------+------------------------------------------------+
+| syslog   | Facility | :ref:`WP_FAIL2BAN_EX_WAF_LOG`                  |
+|          +----------+------------------------------------------------+
+|          | Level    | WARNING if enabled, NOTICE if logging only     |
++----------+----------+------------------------------------------------+
+| fail2ban | Filter   | :ref:`wordpress-hard_conf`                     |
+|          +----------+------------------------------------------------+
+|          | Rule     | ``SQLi blocked from <HOST>``                   |
++----------+----------+------------------------------------------------+
+
+.. versionadded:: 5.1.0

events/waf/WPF2B_EVENT_WAF_UPDATE_OPTION.rst

@@ -0,0 +1,29 @@
+.. _WPF2B_EVENT_WAF_UPDATE_OPTION:
+
+WPF2B_EVENT_WAF_UPDATE_OPTION
+-----------------------------
+
+.. rubric:: Unauthorised call to ``update_option()`` detected.
+.. rubric:: *Premium only*
+
++----------+----------+----------------------------------------------------------------------------------+
+| syslog   | Facility | :ref:`WP_FAIL2BAN_EX_WAF_LOG`                                                    |
++----------+----------+----------------------------------------------------------------------------------+
+|          | Level    | WARNING if enabled, NOTICE if logging only                                       |
++----------+----------+----------------------------------------------------------------------------------+
+| fail2ban | Filter   | :ref:`wordpress-hard_conf`                                                       |
++----------+----------+----------------------------------------------------------------------------------+
+|          | Rule     | ``WAF: update_option(<option_name>)="<option_value>" from <HOST>``               |
+|          |          |                                                                                  |
+|          |          | <option_name>                                                                    |
+|          |          |   Name of the core WordPress option being updated.                               |
+|          |          | <option_value>                                                                   |
+|          |          |   The JSON-encoded value being set. The following options are used for encoding: |
+|          |          |                                                                                  |
+|          |          |   * JSON_NUMERIC_CHECK                                                           |
+|          |          |   * JSON_UNESCAPED_SLASHES                                                       |
+|          |          |   * JSON_PRESERVE_ZERO_FRACTION                                                  |
+|          |          |   * JSON_INVALID_UTF8_SUBSTITUTE                                                 |
++----------+----------+----------------------------------------------------------------------------------+
+
+.. versionadded:: 5.1.0

facilities.rst

@@ -127,18 +127,5 @@ Premium
 +----------+-------------------------------------------+
 |          | :ref:`WP_FAIL2BAN_EX_XMLRPC_LOG`          |
 +----------+-------------------------------------------+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+|          | :ref:`WP_FAIL2BAN_EX_WAF_LOG`             |
++----------+-------------------------------------------+