From ebf9ee33374e59920da6977f7b7e6b3a5d9a4ce5 Mon Sep 17 00:00:00 2001
From: Ben Fuhrmannek
Date: Wed, 18 Aug 2021 15:13:55 +0200
Subject: documentation for the ini protection feature

---
 doc/source/config.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

(limited to 'doc')

diff --git a/doc/source/config.rst b/doc/source/config.rst
index 9e9fb83..10b0afd 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -189,6 +189,70 @@ Cookies-related mitigations
 Since snuffleupagus is providing several hardening features for cookies,
 there is a dedicated web page :ref:`here <cookie-encryption-page>` about them.
 
+INI Settings Protection
+^^^^^^^^^^^^^^^^^^^^^^^
+INI settings can be forced to a value, limited by min/max value or regular expression and set read-only mode.
+
+First, this feature can be enabled or disabled:
+
+::
+
+  sp.ini_protection.enable();
+  sp.ini_protection.disable();
+
+The INI protection feature can be set to simulation mode, where violations are only reported, but rules are not enforced:
+
+::
+
+  sp.ini_protection.simulation();
+
+Rule violations can be set to drop as a global policy, or alternatively be set on individual rules using ``.drop()``.
+
+::
+
+  sp.ini_protection.policy_drop();
+
+Rules can be set to fail silently without logging anything:
+
+::
+
+  sp.ini_protection.policy_silent_fail();
+  ## or write sp.ini_protection.policy_no_log(); as an alias
+
+Read-only settings are implemented in a way that the PHP system itself can block the setting, which is very efficient. If you do not need to log read-only violations, these can be set to silent separately:
+
+::
+
+  sp.ini_protection.policy_silent_ro();
+
+A global access policy can be set to either read-only or read-write. Individual entries can be set to read-only/read-write as well using ``.ro()``/``.rw()``.
+
+::
+
+  sp.ini_protection.policy_readonly();
+  sp.ini_protection.policy_readwrite();
+
+Individual rules are specified using ``sp.ini``. These entries can have the following attributes:
+
+- ``.key("...")``: mandatory ini name.
+- ``.set("...")``: set the initial value. This overrides php.ini. checks are not performed for this initial value.
+- ``.min("...")`` / ``.max("...")``: value must be an integer between .min and .max. shorthand notation (e.g. 1k = 1024) is allowed
+- ``.regexp("...")``: value must match the regular expression
+- ``.allow_null()``: allow setting a NULL-value
+- ``.msg("...")``: message is shown in logs on rule violation instead of default message
+- ``.readonly()`` / ``.ro()`` / .readwrite() / .rw(): set entry to read-only or read-write respectively. If no access keyword is provided, the entry inherits the default policy set by ``sp.ini_protection.policy_*``-rules.
+- ``.drop()``: drop request on rule violation for this entry
+- ``.simulation()``: only log rule violation for this entry
+
+Examples:
+
+::
+
+  sp.ini.key("display_errors").set("0").ro();
+  sp.ini.key("default_socket_timeout").min("1").max("300").rw();
+  sp.ini.key("highlight.comment").regexp("^#[0-9a-fA-F]{6}$");
+
+For more examples, check out the ``config`` directory.
 
 readonly_exec
 ^^^^^^^^^^^^^
-- 
cgit v1.3