diff --git a/DC-SAP-lsm b/DC-SAP-lsm new file mode 100644 index 000000000..370b2885e --- /dev/null +++ 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 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" \ No newline at end of file diff --git a/DC-SLES-lsm b/DC-SLES-lsm new file mode 100644 index 000000000..708968e04 --- /dev/null +++ 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 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" \ No newline at end of file diff --git a/articles/lsm.asm.xml b/articles/lsm.asm.xml new file mode 100644 index 000000000..ef33879f0 --- /dev/null +++ b/articles/lsm.asm.xml @@ -0,0 +1,135 @@ + + + + %entities; +]> + + + + + + + + + + + + + + + Introduction to the Linux Security Module Framework + + 2026-04-07 + + + Initial version + + + + + + + + + + Smart Docs + + + + Administration + Configuration + Security + + + + + + https://bugzilla.suse.com/enter_bug.cgi + Documentation + SUSE Linux Enterprise Server 16.0 + SUSE Linux Enterprise Server 16.0 + amrita.sakthivel@suse.com + + yes + + + + + &x86-64; + &power; + &zseries; + &aarch64; + + + + + &productname; + + + + Introduction to the Yama Linux Security Module + Understanding the Yama LSM is vital because it provides a foundational layer of defense-in-depth by restricting ptrace capabilities + + + 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 + + + + + WHAT? + + + 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. + + + + + WHY? + + + 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. + + + + + EFFORT + + +The average reading time of this article is approximately 40 minutes. + + + + + REQUIREMENTS + + + + +Linux fundamentals: Understanding basic Linux commands, file permissions, directory structures +and use of the command line. + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/concepts/intro-lsm-yama.xml b/concepts/intro-lsm-yama.xml new file mode 100644 index 000000000..cecc0be10 --- /dev/null +++ b/concepts/intro-lsm-yama.xml @@ -0,0 +1,34 @@ + + + %entities; +]> + + + + + + + Introduction to the YAMA security module + + + +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 ptrace system call, which is commonly used for debugging but can also be exploited for malicious purposes. +ptrace is a short form of process call, which is a powerful system call that allows one process to observe, control, and manipulate another process. + + + + +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 CONFIG_SECURITY_YAMA and can be controlled at run-time through sysctls in /proc/sys/kernel/yama. + + \ No newline at end of file diff --git a/concepts/intro-lsm.xml b/concepts/intro-lsm.xml new file mode 100644 index 000000000..846fadeee --- /dev/null +++ b/concepts/intro-lsm.xml @@ -0,0 +1,99 @@ + + + %entities; +]> + + + + + + + About the Linux Security Module Framework + + + +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). + + + + +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. + +
+ How LSM works? + 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 read/write/execute permission check. +If the DAC allows it, the LSM framework then steps in: + + +The kernel calls a hook which is a redirection point. + + + The Security Module, for example &selnx; checks its own specific policy. + + + The security module then returns a decision; Allowed or Denied. + + +You can check which security modules are currently initialized on your Linux system: +cat /sys/kernel/security/lsm +lockdown,capability,landlock,yama,selinux,bpf,ima,evm + +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 CAP_SYS_PTRACE, it means the kernel requires the process attempting the change to possess a specific capability. +The sysctl settings writable only with CAP_SYS_PTRACE are: + +sysctl settings explained + + + + Level + Name + Description + + + + + 0 + Classic + Regular Linux ptrace permissions (owner can attach). + + + 1 + Restricted + Only a parent process can ptrace its descendants. + + + 2 + Admin-only + Only processes with CAP_SYS_PTRACE can ptrace (usually root). + + + 3 + No-attach + Ptrace is disabled globally. Cannot be changed until reboot. + + + +
+
+
+ Why is LSM important? + 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: + + Standardization: It created a stable interface so security developers did not have to rewrite their code every time the kernel updated. + Modularity: 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. + Stacking: Modern kernels allow you to stack multiple modules, so you can run something like Yama to protect against ptrace attacks alongside AppArmor. + +
+ \ No newline at end of file diff --git a/glues/lsm-more-info.xml b/glues/lsm-more-info.xml new file mode 100644 index 000000000..7f21b2a92 --- /dev/null +++ b/glues/lsm-more-info.xml @@ -0,0 +1,27 @@ + + + %entities; +]> + + + For more information + + + + + + To learn more about the Linux Security Module usage: + . + + + + + \ No newline at end of file diff --git a/tasks/enable-yama-lsm.xml b/tasks/enable-yama-lsm.xml new file mode 100644 index 000000000..c105fbb14 --- /dev/null +++ b/tasks/enable-yama-lsm.xml @@ -0,0 +1,68 @@ + + + + + %entities; +]> + + + + + + + Enabling the Yama Linux Security module + + + + + Using the Yama LSM is primarily an administrative task that involves interacting with the Linux kernel's sysctl interface. Since Yama is built into most modern kernels , you don't run it like a program; instead, you configure its ptrace_scope . + + + + + Setting Yama security levels + Verify that your kernel was compiled with Yama support. check for the existence of the Yama configuration file: + +ls /proc/sys/kernel/yama/ptrace_scope +If this file exists, Yama is active. If you get a No such file or directory error, Yama is likely not compiled into your kernel or not enabled as a security module at boot. + + +To see which mode your system is currently using, read the value of the ptrace_scope file: + +cat /proc/sys/kernel/yama/ptrace_scope + +0: Classic permissions (Least secure). +1: Restricted (Default on most systems; can only trace children). +2: Admin-only (Requires root). +3: Disabled (Highest security; cannot be changed without reboot). + + +You can change the security level temporarily to see how it affects your tools, for example, strace: +&prompt.sudo; sh -c 'echo 2 /proc/sys/kernel/yama/ptrace_scope' + If the level is already set to 3, you cannot lower it using this method. Level 3 is a lockdown mode that persists until the next system reboot. + +sleep 100 & +Note the PID. +Open a separate terminal and try to attach to it; strace -p PID_NO. +If Yama level 1 is active, you will see: attach: ptrace: Operation not permitted. + + + Edit the sysctl configuration to make the Yama level permanent: +&prompt.sudo; vi /etc/sysctl.d/10-ptrace.conf +If the file does not exist, you can create it or edit /etc/sysctl.conf. +Add the following line and apply the change: +kernel.yama.ptrace_scope = 1 +&prompt.sudo; sysctl -p /etc/sysctl.d/10-ptrace.conf +Optional: If you want to ensure Yama is at level 3 (disabled) from the moment the system turns on, add yama.ptrace_scope=3 to your GRUB kernel boot parameters. + + + \ No newline at end of file diff --git a/tasks/yama-troubleshooting.xml b/tasks/yama-troubleshooting.xml new file mode 100644 index 000000000..c1071f698 --- /dev/null +++ b/tasks/yama-troubleshooting.xml @@ -0,0 +1,33 @@ + + + + + + %entities; +]> + + + + Troubleshooting Yama + + + Troubleshooting Yama is essential because an overly restrictive ptrace_scope can silently break critical system operations, such as debugging with GDB or generating crash reports, directly impacting a developer's ability to diagnose software failures. + + Common troubleshooting scenarios include: + + + xx + xx + + + + \ No newline at end of file