Message-ID:
 <SCYP152MB62612944AD5E282EE26871DDB063A@SCYP152MB6261.LAMP152.PROD.OUTLOOK.COM>
Date: Sun, 1 Jun 2025 01:07:44 +0000
From: ℰ𝓃𝓏ℴ ℱ𝓊𝓀ℯ
	<milesonerd@...look.com>
To: "serge@...lyn.com" <serge@...lyn.com>
CC: "linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	"linux-security-module@...r.kernel.org"
	<linux-security-module@...r.kernel.org>, "linux-doc@...r.kernel.org"
	<linux-doc@...r.kernel.org>
Subject: PATCH 2/3] security: add Lilium - Linux Integrity Lock-In User Module
 - Documentation

From 23d323f793b888bb2ad0d2a7a1ca095d5d64d0b8 Mon Sep 17 00:00:00 2001
From: Enzo Fuke <milesonerd@...look.com>
Date: Sun, 1 Jun 2025 00:11:36 +0000
Subject: [PATCH] Lilium Documentation

---
 Documentation/security/lilium.rst | 402 ++++++++++++++++++++++++++++++
 1 file changed, 402 insertions(+)
 create mode 100644 Documentation/security/lilium.rst

diff --git a/Documentation/security/lilium.rst b/Documentation/security/lilium.rst
new file mode 100644
index 0000000..bd25ff6
--- /dev/null
+++ b/Documentation/security/lilium.rst
@@ -0,0 +1,402 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==============================================
+Lilium (Linux Integrity Lock-In User Module)
+==============================================
+
+:Author: Enzo Fuke
+:Date: May 2025
+:Version: 1.0
+
+Introduction
+============
+
+Lilium (Linux Integrity Lock-In User Module) is a Linux Security Module (LSM)
+designed to enhance system security by providing fine-grained control over
+critical system operations. It implements a modular approach to security,
+allowing administrators to selectively enable specific security mechanisms
+based on their requirements.
+
+The name "Lilium" is an acronym for "Linux Integrity Lock-In User Module",
+reflecting its purpose of locking down various system operations to maintain
+system integrity and security.
+
+Security Philosophy
+------------------
+
+Lilium follows the principle of "secure by default but configurable". All
+security mechanisms are disabled by default to ensure compatibility with
+existing systems, but can be easily enabled individually through the sysfs
+interface. This approach allows administrators to gradually implement security
+measures without disrupting system functionality.
+
+The module is designed with the following principles in mind:
+
+1. **Modularity**: Each security mechanism can be enabled independently.
+2. **Contextual Logic**: Security decisions consider the context of operations.
+3. **Least Privilege**: Restrictions follow the principle of least privilege.
+4. **Compatibility**: Works alongside other LSMs in the Linux security stack.
+
+Features
+========
+
+Lilium provides the following security mechanisms, each addressing specific
+security concerns:
+
+1. **ptrace restrictions**
+  
+   Controls which processes can trace other processes using the ptrace system
+   call. This helps prevent unauthorized debugging and memory inspection of
+   running processes, which could be used to extract sensitive information or
+   modify process behavior.
+  
+   When enabled, only processes with CAP_SYS_PTRACE capability can attach to
+   other processes using ptrace, preventing unprivileged users from debugging
+   or inspecting other users' processes.
+
+2. **mmap/mprotect restrictions**
+  
+   Prevents creating executable memory mappings or changing non-executable
+   memory to executable. This is a critical defense against many exploit
+   techniques that rely on executing code from writable memory regions.
+  
+   When enabled, attempts to create anonymous executable mappings or change
+   existing mappings to be executable will be denied unless the process has
+   CAP_SYS_ADMIN capability. This helps prevent code injection attacks and
+   limits the impact of buffer overflow vulnerabilities.
+
+3. **kexec_load restrictions**
+  
+   Prevents loading alternative kernels via the kexec_load system call. This
+   restricts the ability to replace the running kernel, which could be used
+   to bypass security mechanisms or install a compromised kernel.
+  
+   When enabled, only processes with CAP_SYS_BOOT capability can use kexec_load,
+   ensuring that only authorized administrators can replace the running kernel.
+
+4. **clone/unshare restrictions**
+  
+   Controls the creation of new namespaces using clone and unshare system calls.
+   This limits the ability to create isolated environments that could be used
+   to escape container boundaries or manipulate system resources.
+  
+   When enabled, unprivileged processes are prevented from creating certain
+   types of namespaces, reducing the risk of container escape vulnerabilities.
+
+5. **module management restrictions**
+  
+   Prevents loading or unloading kernel modules. This restricts the ability to
+   extend or modify kernel functionality, which could be used to bypass security
+   mechanisms or introduce malicious code into the kernel.
+  
+   When enabled, only processes with CAP_SYS_MODULE capability can load or
+   unload kernel modules, ensuring that only authorized administrators can
+   modify kernel functionality.
+
+6. **file open restrictions**
+  
+   Controls access to specific files using the open and openat system calls.
+   This allows for fine-grained control over file access beyond traditional
+   discretionary access controls.
+  
+   When enabled, Lilium can restrict access to sensitive files based on
+   contextual information, providing an additional layer of protection for
+   critical system files.
+
+7. **ioctl restrictions**
+  
+   Controls specific ioctl operations. This limits the ability to perform
+   potentially dangerous device control operations that could be used to
+   manipulate hardware or bypass security mechanisms.
+  
+   When enabled, Lilium can restrict specific ioctl commands based on
+   contextual information, preventing unauthorized device manipulation.
+
+Use Cases
+---------
+
+Lilium is particularly useful in the following scenarios:
+
+1. **Server Hardening**: Restrict system operations on production servers to
+   reduce the attack surface and limit the impact of potential compromises.
+
+2. **Container Security**: Enhance container isolation by restricting operations
+   that could be used to escape container boundaries.
+
+3. **Multi-tenant Environments**: Provide additional security boundaries between
+   users in shared computing environments.
+
+4. **Compliance Requirements**: Help meet security compliance requirements by
+   implementing additional security controls.
+
+5. **Critical Infrastructure**: Protect systems in critical infrastructure by
+   restricting potentially dangerous operations.
+
+Configuration
+============
+
+Lilium can be configured both at compile time and runtime, providing flexibility
+for different deployment scenarios.
+
+Kernel Configuration
+-------------------
+
+To use Lilium, it must be enabled in the kernel configuration. This can be done
+using the kernel configuration menu (make menuconfig) under:
+
+    Security options ---> Lilium (Linux Integrity Lock-In User Module) Support
+
+Each security mechanism can be individually enabled at compile time:
+
+- **CONFIG_SECURITY_LILIUM**: Main Lilium support
+- **CONFIG_SECURITY_LILIUM_PTRACE**: Lilium ptrace restrictions
+- **CONFIG_SECURITY_LILIUM_MPROTECT**: Lilium mmap/mprotect restrictions
+- **CONFIG_SECURITY_LILIUM_KEXEC**: Lilium kexec_load restrictions
+- **CONFIG_SECURITY_LILIUM_CLONE**: Lilium clone/unshare restrictions
+- **CONFIG_SECURITY_LILIUM_MODULE**: Lilium module management restrictions
+- **CONFIG_SECURITY_LILIUM_OPEN**: Lilium file open restrictions
+- **CONFIG_SECURITY_LILIUM_IOCTL**: Lilium ioctl restrictions
+
+All options default to 'n' (disabled) and can be selectively enabled based on
+security requirements.
+
+Kernel Boot Parameters
+---------------------
+
+To activate Lilium at boot time, it must be added to the list of enabled LSMs
+in the kernel boot parameters. This can be done by adding "lilium" to the "lsm"
+parameter:
+
+.. code-block:: none
+
+    lsm=capability,landlock,lockdown,yama,integrity,apparmor,lilium
+
+The exact list will depend on which other LSMs are enabled in your kernel.
+Lilium is designed to work alongside other LSMs in the Linux security stack.
+
+Runtime Configuration
+--------------------
+
+Lilium features can be enabled or disabled at runtime through the sysfs
+interface. This allows for dynamic configuration without rebooting the system.
+
+The sysfs interface is located at `/sys/kernel/lilium/` and provides the
+following control files:
+
+.. code-block:: bash
+
+    # Enable ptrace restrictions
+    echo 1 > /sys/kernel/lilium/ptrace_enabled
+
+    # Disable ptrace restrictions
+    echo 0 > /sys/kernel/lilium/ptrace_enabled
+
+Available sysfs controls:
+
+- **/sys/kernel/lilium/ptrace_enabled**: Controls ptrace restrictions
+- **/sys/kernel/lilium/mprotect_enabled**: Controls mmap/mprotect restrictions
+- **/sys/kernel/lilium/kexec_enabled**: Controls kexec_load restrictions
+- **/sys/kernel/lilium/clone_enabled**: Controls clone/unshare restrictions
+- **/sys/kernel/lilium/module_enabled**: Controls module management restrictions
+- **/sys/kernel/lilium/open_enabled**: Controls file open restrictions
+- **/sys/kernel/lilium/ioctl_enabled**: Controls ioctl restrictions
+
+Each control file accepts the following values:
+
+- **0**: Disable the feature (default)
+- **1**: Enable the feature
+
+Changes take effect immediately and apply to all subsequent operations.
+
+Example Configuration
+--------------------
+
+Here's an example of a common security configuration using Lilium:
+
+.. code-block:: bash
+
+    # Enable ptrace restrictions to prevent unauthorized debugging
+    echo 1 > /sys/kernel/lilium/ptrace_enabled
+
+    # Enable mprotect restrictions to prevent code injection
+    echo 1 > /sys/kernel/lilium/mprotect_enabled
+
+    # Enable module management restrictions to prevent kernel module tampering
+    echo 1 > /sys/kernel/lilium/module_enabled
+
+This configuration provides a good balance between security and usability for
+many server environments.
+
+Implementation Details
+=====================
+
+Hook Registration
+----------------
+
+Lilium registers security hooks for various kernel operations using the LSM
+framework. These hooks are called by the kernel before performing the
+corresponding operations, allowing Lilium to make security decisions.
+
+The hooks are registered in the `lilium_init` function using the
+`security_add_hooks` function provided by the LSM framework.
+
+Security Decision Logic
+----------------------
+
+Lilium implements contextual logic for each security hook to determine whether
+an operation should be allowed or denied. The decision logic follows these
+general principles:
+
+1. If the corresponding feature is disabled, the operation is allowed.
+2. If the process has the appropriate capability, the operation is allowed.
+3. Otherwise, the operation is evaluated based on contextual information.
+
+By default, all operations are allowed unless the corresponding feature is
+enabled. When a feature is enabled, Lilium applies restrictions based on
+the context of the operation, such as the credentials of the calling process.
+
+Interaction with Other LSMs
+--------------------------
+
+Lilium is designed to work alongside other LSMs in the Linux security stack.
+It follows the LSM stacking model, where multiple LSMs can be active
+simultaneously, and an operation is allowed only if all active LSMs allow it.
+
+This allows Lilium to complement other LSMs like SELinux, AppArmor, or SMACK,
+providing additional security controls without interfering with their operation.
+
+Performance Considerations
+-------------------------
+
+Lilium is designed to have minimal performance impact when features are
+disabled. When features are enabled, the performance impact depends on the
+specific features and the workload of the system.
+
+In general, the performance overhead is negligible for most workloads, as
+the security checks are lightweight and only performed for specific operations.
+
+Troubleshooting
+==============
+
+Common Issues
+------------
+
+1. **Operation Denied Unexpectedly**
+
+   If an operation is denied unexpectedly, check which Lilium features are
+   enabled:
+
+   .. code-block:: bash
+
+       cat /sys/kernel/lilium/*/
+
+   Disable the relevant feature temporarily to confirm if Lilium is causing
+   the issue:
+
+   .. code-block:: bash
+
+       echo 0 > /sys/kernel/lilium/feature_enabled
+
+2. **Lilium Not Appearing in sysfs**
+
+   If the Lilium sysfs interface is not available, check if Lilium is enabled
+   in the kernel:
+
+   .. code-block:: bash
+
+       cat /proc/cmdline | grep lsm
+
+   Ensure that "lilium" is included in the lsm parameter.
+
+3. **Conflicts with Other Security Modules**
+
+   If you experience conflicts with other security modules, check the kernel
+   log for any error messages:
+
+   .. code-block:: bash
+
+       dmesg | grep lilium
+
+Debugging
+--------
+
+Lilium logs important events and errors to the kernel log. You can view these
+messages using dmesg:
+
+.. code-block:: bash
+
+    dmesg | grep lilium
+
+For more detailed debugging, you can enable kernel debug options for LSMs
+during kernel compilation.
+
+Security Considerations
+======================
+
+While Lilium provides additional security controls, it should be considered
+as part of a defense-in-depth strategy, not a complete security solution.
+
+Best Practices
+-------------
+
+1. **Start with Minimal Restrictions**: Enable only the features you need to
+   minimize potential compatibility issues.
+
+2. **Test Thoroughly**: Test your configuration in a non-production environment
+   before deploying to production.
+
+3. **Combine with Other Security Measures**: Use Lilium alongside other security
+   measures like SELinux, AppArmor, seccomp, and regular system updates.
+
+4. **Monitor System Logs**: Regularly monitor system logs for any security
+   events or denied operations.
+
+5. **Keep Documentation**: Document your security configuration for future
+   reference and auditing purposes.
+
+Limitations
+----------
+
+1. Lilium cannot protect against all types of attacks or vulnerabilities.
+
+2. Some applications may not function correctly with certain restrictions
+   enabled.
+
+3. Lilium operates at the kernel level and cannot protect against user-level
+   threats without appropriate configuration.
+
+Future Development
+=================
+
+Planned Features
+---------------
+
+1. **Enhanced Logging**: More detailed logging of security events and decisions.
+
+2. **Fine-grained Controls**: More granular control over security restrictions.
+
+3. **Policy Language**: A simple policy language for configuring Lilium.
+
+4. **Integration with Audit**: Better integration with the Linux audit system.
+
+Contributing
+-----------
+
+Contributions to Lilium are welcome. Please follow the standard Linux kernel
+development process for submitting patches.
+
+References
+==========
+
+1. Linux Security Modules (LSM) Framework:
+   https://www.kernel.org/doc/html/latest/security/lsm.html
+
+2. Linux Capabilities:
+   https://www.kernel.org/doc/html/latest/security/credentials.html
+
+3. Linux Namespaces:
+   https://www.kernel.org/doc/html/latest/admin-guide/namespaces/index.html
+
+4. Linux Kernel Documentation:
+   https://www.kernel.org/doc/html/latest/
+
--
2.49.0

Powered by blists - more mailing lists