--- Â 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
