Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   John Wood <john.wood@gmx.com>
To:     Kees Cook <keescook@chromium.org>, Jann Horn <jannh@google.com>
Cc:     John Wood <john.wood@gmx.com>, Jonathan Corbet <corbet@lwn.net>,
        James Morris <jmorris@namei.org>,
        "Serge E. Hallyn" <serge@hallyn.com>, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        linux-security-module@vger.kernel.org,
        kernel-hardening@lists.openwall.com
Subject: [PATCH v2 7/8] Documentation: Add documentation for the Brute LSM
Date:   Sun, 25 Oct 2020 14:45:39 +0100
Message-Id: <20201025134540.3770-8-john.wood@gmx.com>
In-Reply-To: <20201025134540.3770-1-john.wood@gmx.com>
References: <20201025134540.3770-1-john.wood@gmx.com>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

Add some info detailing what is the Brute LSM, its motivation, weak
points of existing implementations, proposed solutions, enabling,
disabling and fine tuning.

Signed-off-by: John Wood <john.wood@gmx.com>
=2D--
 Documentation/admin-guide/LSM/Brute.rst | 118 ++++++++++++++++++++++++
 Documentation/admin-guide/LSM/index.rst |   1 +
 security/brute/Kconfig                  |   3 +-
 3 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/LSM/Brute.rst

diff --git a/Documentation/admin-guide/LSM/Brute.rst b/Documentation/admin=
-guide/LSM/Brute.rst
new file mode 100644
index 000000000000..20c6ccbd625d
=2D-- /dev/null
+++ b/Documentation/admin-guide/LSM/Brute.rst
@@ -0,0 +1,118 @@
+.. SPDX-License-Identifier: GPL-2.0
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+Brute: Fork brute force attack detection and mitigation LSM
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+
+Attacks against vulnerable userspace applications with the purpose to bre=
ak ASLR
+or bypass canaries traditionaly use some level of brute force with the he=
lp of
+the fork system call. This is possible since when creating a new process =
using
+fork its memory contents are the same as those of the parent process (the
+process that called the fork system call). So, the attacker can test the =
memory
+infinite times to find the correct memory values or the correct memory ad=
dresses
+without worrying about crashing the application.
+
+Based on the above scenario it would be nice to have this detected and
+mitigated, and this is the goal of this implementation.
+
+
+Other implementations
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+
+The public version of grsecurity, as a summary, is based on the idea of d=
elay
+the fork system call if a child died due to a fatal error. This has some =
issues:
+
+Bad practices
+-------------
+
+Add delays to the kernel is, in general, a bad idea.
+
+Weak points
+-----------
+
+This protection can be bypassed using two different methods since it acts=
 only
+when the fork is called after a child has crashed.
+
+Bypass 1
+~~~~~~~~
+
+So, it would still be possible for an attacker to fork a big amount of ch=
ildren
+(in the order of thousands), then probe all of them, and finally wait the
+protection time before repeat the steps.
+
+Bypass 2
+~~~~~~~~
+
+This method is based on the idea that the protection doesn't act if the p=
arent
+crashes. So, it would still be possible for an attacker to fork a process=
 and
+probe itself. Then, fork the child process and probe itself again. This w=
ay,
+these steps can be repeated infinite times without any mitigation.
+
+
+This implementation
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+
+The main idea behind this implementation is to improve the existing ones
+focusing on the weak points annotated before. The solution for the first =
bypass
+method is to detect a fast crash rate instead of only one simple crash. F=
or the
+second bypass method the solution is to detect both the crash of parent a=
nd
+child processes. Moreover, as a mitigation method it is better to kill al=
l the
+offending tasks involve in the attack instead of use delays.
+
+So, the solution to the two bypass methods previously commented is to use=
 some
+statistical data shared across all the processes that can have the same m=
emory
+contents. Or in other words, a statistical data shared between all the fo=
rk
+hierarchy processes after an execve system call.
+
+The purpose of these statistics is to compute the application crash perio=
d in
+order to detect an attack. This crash period is the time between the exec=
ve
+system call and the first fault or the time between two consecutives faul=
ts, but
+this has a drawback. If an application crashes once quickly from the exec=
ve
+system call or crashes twice in a short period of time for some reason, a=
 false
+positive attack will be triggered. To avoid this scenario the shared stat=
istical
+data holds a list of the i last crashes timestamps and the application cr=
ash
+period is computed as follows:
+
+crash_period =3D (n_last_timestamp - n_minus_i_timestamp) / i;
+
+This ways, the size of the last crashes timestamps list allows to fine tu=
ning
+the detection sensibility.
+
+When this crash period falls under a certain threshold there is a clear s=
ignal
+that something malicious is happening. Once detected, the mitigation only=
 kills
+the processes that share the same statistical data and so, all the tasks =
that
+can have the same memory contents. This way, an attack is rejected.
+
+Per system enabling
+-------------------
+
+This feature can be enabled at build time using the CONFIG_SECURITY_FORK_=
BRUTE
+option or using the visual config application under the following menu:
+
+Security options  --->  Fork brute force attack detection and mitigation
+
+Per process enabling/disabling
+------------------------------
+
+To allow that specific applications can turn off or turn on the detection=
 and
+mitigation of a fork brute force attack when required, there are two new =
prctls.
+
+prctl(PR_SECURITY_FORK_BRUTE_ENABLE, 0, 0, 0, 0)  -> To enable the featur=
e
+prctl(PR_SECURITY_FORK_BRUTE_DISABLE, 0, 0, 0, 0) -> To disable the featu=
re
+
+Fine tuning
+-----------
+
+To customize the detection's sensibility there are two new sysctl attribu=
tes
+that allow to set the last crashes timestamps list size and the applicati=
on
+crash period threshold (in milliseconds). Both are accessible through the
+following files respectively.
+
+/proc/sys/kernel/brute/timestamps_list_size
+/proc/sys/kernel/brute/crash_period_threshold
+
+The list size allows to avoid false positives due to crashes unrelated wi=
th a
+real attack. The period threshold sets the time limit to detect an attack=
. And,
+since a fork brute force attack will be detected if the application crash=
 period
+falls under this threshold, the higher this value, the more sensitive the
+detection will be.
+
diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin=
-guide/LSM/index.rst
index a6ba95fbaa9f..1f68982bb330 100644
=2D-- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -41,6 +41,7 @@ subdirectories.
    :maxdepth: 1

    apparmor
+   Brute
    LoadPin
    SELinux
    Smack
diff --git a/security/brute/Kconfig b/security/brute/Kconfig
index 1bd2df1e2dec..334d7e88d27f 100644
=2D-- a/security/brute/Kconfig
+++ b/security/brute/Kconfig
@@ -7,6 +7,7 @@ config SECURITY_FORK_BRUTE
 	  vulnerable userspace processes. The detection method is based on
 	  the application crash period and as a mitigation procedure all the
 	  offending tasks are killed. Like capabilities, this security module
-	  stacks with other LSMs.
+	  stacks with other LSMs. Further information can be found in
+	  Documentation/admin-guide/LSM/Brute.rst.

 	  If you are unsure how to answer this question, answer N.
=2D-
2.25.1