Skip to content

PED-15908: yama-lsm #667

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Amrita42 wants to merge 8 commits into
base: main
Choose a base branch
from
Open

PED-15908: yama-lsm #667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a52c4e6
toc-structure
Amrita42 Apr 7, 2026
081a4fe
yama
Amrita42 Apr 7, 2026
25f217b
yama-intro
Amrita42 Apr 8, 2026
a5e3d97
steps
Amrita42 Apr 8, 2026
6c3135d
steps
Amrita42 Apr 9, 2026
a3cac27
structure
Amrita42 Apr 9, 2026
fff9ac9
adds troubleshooting
Amrita42 Apr 9, 2026
b94bf71
ref module
Amrita42 Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions DC-SAP-lsm
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
15 changes: 15 additions & 0 deletions DC-SLES-lsm
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
135 changes: 135 additions & 0 deletions articles/lsm.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
34 changes: 34 additions & 0 deletions concepts/intro-lsm-yama.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<?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>
</topic>
99 changes: 99 additions & 0 deletions concepts/intro-lsm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<?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>
<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>
<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>
</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>
27 changes: 27 additions & 0 deletions glues/lsm-more-info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Loading