[PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[Lincoln Wallace]

The LSM usage document (Documentation/admin-guide/LSM/index.rst) has
not kept up with the LSM stacking infrastructure. It still describes
CONFIG_DEFAULT_SECURITY, which no longer exists, and its description
of the module ordering in /sys/kernel/security/lsm does not match
what the framework actually does.

Patch 1 updates the selection mechanism description to CONFIG_LSM and
the "lsm=" parameter, keeping "security=" documented as the deprecated
legacy option. This revisits an earlier attempt by Randy Dunlap [1]
that was rejected for treating the two parameters as equivalent; the
new text keeps them distinct.

Patch 2 fixes the ordering description: lockdown precedes capability
when CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, the integrity
modules are always placed at the end of the list, and the remaining
modules follow the order given by CONFIG_LSM or "lsm=".

[1] https://lore.kernel.org/r/20250114225156.10458-1-rdunlap@infradead.org

Lincoln Wallace (2):
  doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
  doc: LSM: fix module ordering description for /sys/kernel/security/lsm

 Documentation/admin-guide/LSM/index.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

-- 
2.53.0

[PATCH 1/2] doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism

[Lincoln Wallace]

The LSM usage document states that security modules are selectable at
build time via CONFIG_DEFAULT_SECURITY and can be overridden at boot
time via the "security=..." kernel command line argument.

CONFIG_DEFAULT_SECURITY no longer exists: LSMs are enabled via
CONFIG_LSM, an ordered list of the LSMs to initialize, which can be
overridden at boot time with the "lsm=" parameter. The "security="
parameter remains as a deprecated way to choose a legacy "major"
security module, and is ignored when "lsm=" is specified; see commit
89a9684ea158 ("LSM: Ignore "security=" when "lsm=" is specified").

A previous attempt replaced "security=" with "lsm=" in place [1],
which was rejected because the parameters are not equivalent:
"security=" selects a single major module while the built-in
CONFIG_LSM list otherwise remains active, whereas "lsm=" must list
every LSM to enable.

Update the paragraph to describe CONFIG_LSM and "lsm=" as the current
selection mechanism, keeping "security=" documented as the deprecated
legacy option, matching the wording in kernel-parameters.txt.

Link: https://lore.kernel.org/r/20250114225156.10458-1-rdunlap@infradead.org [1]

Signed-off-by: Lincoln Wallace <locnnil0@gmail.com>
---
 Documentation/admin-guide/LSM/index.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index b44ef68f6e4d..c24310c709dc 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -6,9 +6,11 @@ The Linux Security Module (LSM) framework provides a mechanism for
 various security checks to be hooked by new kernel extensions. The name
 "module" is a bit of a misnomer since these extensions are not actually
 loadable kernel modules. Instead, they are selectable at build-time via
-CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
-``"security=..."`` kernel command line argument, in the case where multiple
-LSMs were built into a given kernel.
+CONFIG_LSM, an ordered list of the LSMs to enable, and can be
+overridden at boot-time via the ``"lsm=..."`` kernel command line
+argument. The ``"security=..."`` kernel command line argument remains
+available to choose a legacy "major" security module, but has been
+deprecated by the ``"lsm=..."`` parameter.
 
 The primary users of the LSM interface are Mandatory Access Control
 (MAC) extensions which provide a comprehensive security policy. Examples
-- 
2.53.0

[PATCH 2/2] doc: LSM: fix module ordering description for /sys/kernel/security/lsm

[Lincoln Wallace]

The LSM usage document states that the capability module will always
be first in /sys/kernel/security/lsm, followed by any "minor" modules
and then the one "major" module.

This does not match the current LSM infrastructure:

 - When CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, lockdown is
   initialized as an early LSM, before all other modules including
   capability, and appears first in the list.

 - The integrity modules (e.g. IMA and EVM) register with
   LSM_ORDER_LAST and are always placed at the end of the list,
   regardless of the position of the major module.

 - The relative order of the remaining modules is not fixed by the
   framework; it follows CONFIG_LSM or the "lsm=" kernel command
   line parameter.

Rewrite the paragraph to describe the actual ordering: lockdown
first when early lockdown is enabled, capability otherwise,
integrity modules at the end, and the remaining modules in the
configured order.

Signed-off-by: Lincoln Wallace <locnnil0@gmail.com>
---
 Documentation/admin-guide/LSM/index.rst | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst
index c24310c709dc..9518495edfbc 100644
--- a/Documentation/admin-guide/LSM/index.rst
+++ b/Documentation/admin-guide/LSM/index.rst
@@ -27,9 +27,15 @@ man-pages project.
 A list of the active security modules can be found by reading
 ``/sys/kernel/security/lsm``. This is a comma separated list, and
 will always include the capability module. The list reflects the
-order in which checks are made. The capability module will always
-be first, followed by any "minor" modules (e.g. Yama) and then
-the one "major" module (e.g. SELinux) if there is one configured.
+order in which checks are made. The capability module will be
+first, unless CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, in
+which case the lockdown module will precede it. The integrity
+modules (e.g. IMA and EVM), if enabled in the kernel
+configuration, are always placed at the end of the list. Any
+other "minor" modules (e.g. Yama) and the one "major" module
+(e.g. SELinux), if there is one configured, appear in between,
+in the order given by CONFIG_LSM or the ``"lsm=..."`` kernel
+command line parameter.
 
 Process attributes associated with "major" security modules should
 be accessed and maintained using the special files in ``/proc/.../attr``.
-- 
2.53.0

Re: [PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[Casey Schaufler]

On 7/13/2026 6:38 PM, Lincoln Wallace wrote:
> The LSM usage document (Documentation/admin-guide/LSM/index.rst) has
> not kept up with the LSM stacking infrastructure. It still describes
> CONFIG_DEFAULT_SECURITY, which no longer exists, and its description
> of the module ordering in /sys/kernel/security/lsm does not match
> what the framework actually does.

I've been stewing on this since it came up. We should probably
remove the somewhat complicated logic from the Kconfig files if
it's not adding value.

>
> Patch 1 updates the selection mechanism description to CONFIG_LSM and
> the "lsm=" parameter, keeping "security=" documented as the deprecated
> legacy option. This revisits an earlier attempt by Randy Dunlap [1]
> that was rejected for treating the two parameters as equivalent; the
> new text keeps them distinct.
>
> Patch 2 fixes the ordering description: lockdown precedes capability
> when CONFIG_SECURITY_LOCKDOWN_LSM_EARLY is enabled, the integrity
> modules are always placed at the end of the list, and the remaining
> modules follow the order given by CONFIG_LSM or "lsm=".
>
> [1] https://lore.kernel.org/r/20250114225156.10458-1-rdunlap@infradead.org
>
> Lincoln Wallace (2):
>   doc: LSM: describe CONFIG_LSM and lsm= as the selection mechanism
>   doc: LSM: fix module ordering description for /sys/kernel/security/lsm
>
>  Documentation/admin-guide/LSM/index.rst | 20 ++++++++++++++------
>  1 file changed, 14 insertions(+), 6 deletions(-)
>

Re: [PATCH 0/2] doc: LSM: update usage document for current LSM stacking

[Lincoln Wallace]

On Thu, Jul 23, 2026 at 10:47:12AM -0700, Casey Schaufler wrote:
> I've been stewing on this since it came up. We should probably
> remove the somewhat complicated logic from the Kconfig files if
> it's not adding value.

That seems worth doing, but it looks like a separate change to me.
The document currently describes behaviour the code does not have,
and that's worth correcting either way. If the Kconfig is simplified
later, updating these paragraphs again should be a small part of that
series.

Happy to help with the Kconfig cleanup if that would be useful.

Do you see anything in the two patches that needs adjusting as they
stand?