Re: [PATCH v6 7/8] Documentation: Add documentation for the Brute LSM

On Sun, Mar 21, 2021 at 12:50:47PM -0600, Jonathan Corbet wrote:

John Wood [off-list ref] writes:

quoted

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

Signed-off-by: John Wood <redacted>
---
 Documentation/admin-guide/LSM/Brute.rst | 278 ++++++++++++++++++++++++
 Documentation/admin-guide/LSM/index.rst |   1 +
 security/brute/Kconfig                  |   3 +-
 3 files changed, 281 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/LSM/Brute.rst

Thanks for including documentation with the patch!

As you get closer to merging this, though, you'll want to take a minute
(OK, a few minutes) to build the docs and look at the result; there are

Thanks, I will do it.

a number of places where you're not going to get what you expect.  Just
as an example:

[...]

quoted

+Based on the above scenario it would be nice to have this detected and
+mitigated, and this is the goal of this implementation. Specifically the
+following attacks are expected to be detected:
+
+1.- Launching (fork()/exec()) a setuid/setgid process repeatedly until a
+    desirable memory layout is got (e.g. Stack Clash).
+2.- Connecting to an exec()ing network daemon (e.g. xinetd) repeatedly until a
+    desirable memory layout is got (e.g. what CTFs do for simple network
+    service).
+3.- Launching processes without exec() (e.g. Android Zygote) and exposing state
+    to attack a sibling.
+4.- Connecting to a fork()ing network daemon (e.g. apache) repeatedly until the
+    previously shared memory layout of all the other children is exposed (e.g.
+    kind of related to HeartBleed).

Sphinx will try to recognize your enumerated list, but that may be a bit
more punctuation than it is prepared to deal with; I'd take the hyphens
out, if nothing else.

Thanks. I will fix this for the next version.

quoted

+These statistics are hold by the brute_stats struct.
+
+struct brute_cred {
+	kuid_t uid;
+	kgid_t gid;
+	kuid_t suid;
+	kgid_t sgid;
+	kuid_t euid;
+	kgid_t egid;
+	kuid_t fsuid;
+	kgid_t fsgid;
+};

That will certainly not render the way you want.  What you need here is
a literal block:

These statistics are hold by the brute_stats struct::

    struct brute_cred {
	kuid_t uid;
	kgid_t gid;
	kuid_t suid;
	kgid_t sgid;
	kuid_t euid;
	kgid_t egid;
	kuid_t fsuid;
	kgid_t fsgid;
    };

The "::" causes all of the indented text following to be formatted
literally.

Thanks a lot for your comments and guidance. I will build the docs and
check if the output is as I want.

Thanks,

jon

Regards,
John Wood