SUSE · Amrita42 · Apr 7, 2026 · Apr 7, 2026 · Apr 8, 2026 · Apr 8, 2026
diff --git a/DC-SAP-lsm b/DC-SAP-lsm
@@ -0,0 +1,15 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="lsm.asm.xml"
+# Point to the ID of the <structure> of your assembly
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+PROFOS="sles4sap"
+PROFCONDITION="16.0"
+#PROFCONDITION="suse-product;beta"
+#PROFCONDITION="community-project"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
diff --git a/DC-SLES-lsm b/DC-SLES-lsm
@@ -0,0 +1,15 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="lsm.asm.xml"
+# Point to the ID of the <structure> of your assembly
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+PROFOS="sles"
+PROFCONDITION="16.0"
+#PROFCONDITION="suse-product;beta"
+#PROFCONDITION="community-project"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
diff --git a/articles/lsm.asm.xml b/articles/lsm.asm.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
+            type="application/relax-ng-compact-syntax"?>
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns="http://docbook.org/ns/docbook">
+<!-- R E S O U R C E S -->
+  <resources>
+    <resource href="../concepts/intro-lsm.xml" xml:id="_intro-lsm"/>
+    <resource href="../concepts/intro-lsm-yama.xml" xml:id="_intro-lsm-yama"/>
+    <resource href="../tasks/enable-yama-lsm.xml" xml:id="_enable-yama-lsm"/>
+    <resource href="../tasks/yama-troubleshooting.xml" xml:id="_yama-troubleshooting"/>
+    <resource href="../glues/lsm-more-info.xml" xml:id="_lsm-more-info"/>
+            <resource href="../common/legal.xml" xml:id="_legal"/>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl"/>
+  </resources>
+<!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="lsm" xml:lang="en">
+    <merge>
+      <title>Introduction to the Linux Security Module Framework </title>
+      <revhistory xml:id="rh-lsm">
+        <revision><date>2026-04-07</date>
+          <revdescription>
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>
+      </revhistory>
+
+      <!-- Maintainer-->
+      <meta name="maintainer" content="amrita.sathivel@suse.com" its:translate="no"/>
+
+      <!-- Series-->
+      <meta name="series" its:translate="no">Smart Docs</meta>
+
+      <!-- Task -->
+      <meta name="task" its:translate="no">
+        <phrase>Administration</phrase>
+        <phrase>Configuration</phrase>
+        <phrase>Security</phrase>
+      </meta>
+
+      <!-- Docmanager -->
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Documentation</dm:component>
+          <dm:product os="sles">SUSE Linux Enterprise Server 16.0</dm:product>
+          <dm:product os="sles4sap">SUSE Linux Enterprise Server 16.0</dm:product>
+          <dm:assignee>amrita.sakthivel@suse.com</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+
+      <!-- Architecture -->
+      <meta name="architecture" its:translate="no">
+        <phrase>&x86-64;</phrase>
+        <phrase>&power;</phrase>
+        <phrase>&zseries;</phrase>
+        <phrase>&aarch64;</phrase>
+      </meta>
+
+      <!-- Productname & Version -->
+      <meta name="productname" its:translate="no">
+        <productname version="16.0" os="sles;sles4sap">&productname;</productname>
+      </meta>
+
+      <!-- Social Media -->
+      <meta name="title" its:translate="yes">Introduction to the Yama Linux Security Module</meta>
+      <meta name="social-descr" its:translate="yes">Understanding the Yama LSM is vital because it provides a foundational layer of defense-in-depth by restricting ptrace capabilities</meta>
+
+      <!-- Search -->
+      <meta name="description" its:translate="yes">The Linux Security Module (LSM) framework is a critical component of the kernel because it allows the system to enforce Mandatory Access Control (MAC) policies that go beyond standard user permissions</meta>
+
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>WHAT?</term>
+            <listitem>
+              <para>
+                The LSM functions as a secondary, mandatory validation layer that intercepting system calls only after DAC has granted permission, ensuring that security policies are strictly enforced even if a user or process possesses ownership of a resource.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>WHY?</term>
+            <listitem>
+              <para>
+                Learn how to use and configure LSMs like Yama, as it enables you to transition from basic user-level security to a robust, hardened system capable of neutralizing zero-day exploits.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+The average reading time of this article is approximately 40 minutes.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>REQUIREMENTS</term>
+            <listitem>
+              <itemizedlist>
+                <listitem>
+                  <para>
+<emphasis>Linux fundamentals:</emphasis> Understanding basic Linux commands, file permissions, directory structures
+and use of the command line.
+                  </para>
+                </listitem>
+                       </itemizedlist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <module resourceref="_intro-lsm"></module>
+    <module resourceref="_intro-lsm-yama"></module>
+    <module resourceref="_enable-yama-lsm"></module>
+    <module resourceref="_yama-troubleshooting"></module>
+    <module resourceref="_lsm-more-info"></module>
+    <module resourceref="_legal"/>
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
+  </structure>
+</assembly>
diff --git a/concepts/intro-lsm-yama.xml b/concepts/intro-lsm-yama.xml
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="intro-lsm-yama"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Introduction to the YAMA security module</title>
+    <meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
+    <abstract>
+      <para>
+Yama is a Linux security module designed to enhance system-wide security by implementing DAC (Discretionary Access Control) for certain kernel functionalities.
+It focuses on restricting the use of the <literal>ptrace</literal> system call, which is commonly used for debugging but can also be exploited for malicious purposes.
+<literal>ptrace</literal> is a short form of process call, which is a powerful system call that allows one process to observe, control, and manipulate another process.
+</para>
+    </abstract>
+  </info>
+    <para>
+The Yama module is vital because it addresses a fundamental weakness in the traditional Linux process model, where any process could freely peek and poke into the memory of any other process owned by the same user.
+By introducing configurable scopes, most notably the restriction that a process can only trace its own descendants Yama prevents lateral movement by attackers. This means a compromised low-privilege application, like a Web browser or a chat client, cannot easily reach out to steal sensitive data from an SSH agent or a password manager running in the same session.
+You can implement Yama which is selectable at build-time with <literal>CONFIG_SECURITY_YAMA</literal> and can be controlled at run-time through <literal>sysctls</literal> in <filename>/proc/sys/kernel/yama</filename>.
+  </para>
+  <para>sysctl is a powerful interface used to examine and modify kernel parameters at runtime. However, because these settings can fundamentally change how the OS behaves, they are guarded by specific permissions.
+    When a setting is writable only with <literal>CAP_SYS_PTRACE</literal>, it means the kernel requires the process attempting the change to possess a specific capability.
+    The sysctl settings writable only with <literal>CAP_SYS_PTRACE</literal> are: </para>
+    <table>
+    <title>sysctl settings explained </title>
+    <tgroup cols="3">
+      <thead>
+        <row>
+          <entry>Level</entry>
+          <entry>Name</entry>
+          <entry>Description</entry>
+           </row>
+      </thead>
+      <tbody>
+        <row>
+          <entry>0</entry>
+          <entry>Classic</entry>
+          <entry>Regular Linux ptrace permissions (owner can attach).</entry>
+        </row>
+        <row>
+          <entry>1</entry>
+          <entry>Restricted</entry>
+          <entry>Only a parent process can ptrace its descendants.</entry>
+        </row>
+        <row>
+          <entry>2</entry>
+          <entry>Admin-only</entry>
+          <entry>Only processes with <literal>CAP_SYS_PTRACE</literal> can ptrace (usually root).</entry>
+        </row>
+        <row>
+          <entry>3</entry>
+          <entry>No-attach</entry>
+          <entry>Ptrace is disabled globally. Cannot be changed until reboot. </entry>
+        </row>
+        </tbody>
+    </tgroup>
+    </table>
+<warning><title>Disabling Yama <literal>ptrace</literal> scope restrictions</title>
+<para>This setting is a security feature in the Linux kernel, specifically the Yama Linux Security Module. This setting restricts which processes can use <literal>ptrace</literal>.
+When set to <literal>1</literal>, a process only attaches to its own direct children.
+You can choose either workarounds: </para>
+<para><emphasis role="bold">Permanent persistent system-wide disable</emphasis></para>
+<orderedlist>
+<listitem><para>(Preferred) Install the pre-configured package to handle the sysctl setup for you:</para>
+<screen>&prompt.sudo; zypper install aaa_base-yama-enable-ptrace</screen></listitem>
+<listitem><para>Create a configuration file and add the following line:</para>
+  <screen>/etc/sysctl.d/90-disable-yama.conf</screen>
+  <para><literal>kernel.yama.ptrace_scope = 0</literal></para></listitem>
+<listitem><para>Assign the <literal>CAP_SYS_PTRACE </literal> capability to the debugger via the <literal>setcap</literal>utility from the <package>libcap-progs</package> package:</para>
+  <screen>&prompt.sudo; setcap cap_sys_ptrace+ep /usr/bin/gdb </screen>
+  </listitem>
+</orderedlist>
+<para><emphasis role="bold">Temporary disablement of Yama</emphasis></para>
+<orderedlist>
+<listitem><para>During runtime, set sysctl to <literal>0</literal>:</para>
+<screen>sysctl -w kernel.yama.ptrace_scope=0</screen>
+</listitem>
+<listitem><para>Run the respective debugger as <literal>root</literal>.</para>
+  </listitem>
+</orderedlist>
+<para>For more information, refer to <literal>man 2 ptrace</literal>.</para>
+</warning>
+ </topic>
diff --git a/concepts/intro-lsm.xml b/concepts/intro-lsm.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="intro-lsm"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>About the Linux Security Module Framework</title>
+    <meta name="maintainer" content="amrita.sakthivel@suse.com" its:translate="no"/>
+    <abstract>
+      <para>
+The LSM (Linux Security Module) framework is a modular architecture within the Linux kernel that allows for the implementation of various security models, primarily MAC (Mandatory Access Control).
+   </para>
+    </abstract>
+  </info>
+    <para>
+Rather than hard-coding a specific security policy into the kernel, LSM provides a set of hooks at every critical system call,such as opening files, creating sockets, or starting processes that allow security modules like &selnx;, AppArmor, or Yama to verify actions.
+When a process attempts a sensitive operation, the kernel triggers these hooks to ask the loaded security module for permission; if the module's specific policy denies the request, the action is blocked even if the user has root privileges.
+This framework ensures that Linux remains flexible, allowing users to choose or stack different security layers based on their specific needs for system hardening.
+  </para>
+<para> The Linux security module framework includes the following modules:</para>
+<itemizedlist>
+<listitem><para><emphasis role="bold">Lockdown:</emphasis> The Lockdown module is a LSM, designed to strengthen the boundary between user-space processes and the kernel by restricting access to features that could allow even a root user to modify the running kernel image.
+ It operates in two primary modes:</para>
+ <itemizedlist>
+  <listitem><para><emphasis>integrity:</emphasis> which blocks features that allow user-space to modify the kernel such as, unsigned module loading or direct memory access via <filename>/dev/mem</filename>.</para></listitem>
+  <listitem><para><emphasis>confidentiality:</emphasis> which extends these restrictions to prevent users from extracting sensitive information from kernel memory such as RSA private keys.</para></listitem>
+</itemizedlist>
+  </listitem>
+  <listitem><para><emphasis role="bold">Landlock:</emphasis>The Landlock module empowers unprivileged processes to restrict their own access rights, effectively creating a tailored sandbox without requiring administrative or root privileges.
+    Unlike traditional security modules that enforce system-wide policies, Landlock allows an application developer to define a safe subset of the file system that the program is permitted to access, blocking any unauthorized file reads, writes, or executions outside of that scope.</para></listitem>
+    <listitem><para><emphasis role="bold">Capability:</emphasis> breaks down the traditionally all-or-nothing power of the root user into distinct and granular privileges. Instead of granting a process full administrative control, Linux assigns specific capabilities such as <literal>CAP_NET_BIND_SERVICE</literal> to open low-numbered ports.</para></listitem>
+    <listitem><para><emphasis role="bold">&selnx;:</emphasis> is a robust LSM module that implements a MAC (Mandatory Access Control) architecture, moving beyond the traditional user-owner permission model. It works by assigning security labels (contexts) to every process, file, and network port on the system, and then enforces a central policy that dictates exactly how these entities can interact.</para></listitem>
+  </itemizedlist>
+  <section xml:id="how-does-lsm-work">
+    <title>How LSM works? </title>
+    <para>Whenever a process tries to access an object like opening a file, sending a network packet, or creating a directory, the kernel first performs its standard  DAC (Discretionary Access Control). This is the basic root versus user or <literal>read/write/execute</literal> permission check.
+If the DAC allows it, the LSM framework then steps in:</para>
+<itemizedlist>
+<listitem>
+<para>The kernel calls a hook which is a redirection point.</para>
+</listitem>
+<listitem>
+  <para>The Security Module, for example &selnx; checks its own specific policy.</para>
+  </listitem>
+  <listitem>
+    <para>The security module then returns a decision; <literal>Allowed</literal> or <literal>Denied</literal>.</para>
+    </listitem>
+</itemizedlist>
+<para>You can check which security modules are currently initialized on your Linux system:</para>
+<screen>cat /sys/kernel/security/lsm
+lockdown,capability,landlock,yama,selinux,bpf,ima,evm
+</screen>
+    </section>
+    <section xml:id="imp-lsm">
+      <title>Why is LSM important? </title>
+      <para>Before LSM was introduced, users who want to add a new security feature to Linux had to hack the kernel code directly.
+    LSM solved this by:</para>
+    <itemizedlist>
+ <listitem><para><emphasis role="bold">Standardization:</emphasis> It created a stable interface so security developers did not have to rewrite their code every time the kernel updated.</para></listitem>
+ <listitem><para><emphasis role="bold">Modularity:</emphasis> It allows users to choose the security model that fits their needs, for example, AppArmor for ease of use or &selnx; for high-security environments.</para></listitem>
+ <listitem><para><emphasis role="bold">Stacking:</emphasis> Modern kernels allow you to stack multiple modules, so you can run something like Yama to protect against <literal>ptrace</literal> attacks alongside AppArmor.</para></listitem>
+</itemizedlist>
+     </section>
+ </topic>
diff --git a/glues/lsm-more-info.xml b/glues/lsm-more-info.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<topic xml:id="lsm-more-info"
+ role="glue" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>For more information</title>
+    <!--add author's e-mail address-->
+    <meta name="maintainer" content="amrita.sakthivel@suse.com"/>
+  </info>
+  <itemizedlist>
+    <listitem> <para>
+       To learn more about the Linux Security Module usage:
+        <link xlink:href="https://docs.kernel.org/admin-guide/LSM/index.html"/>.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+</topic>