Hi-- On 5/31/25 6:07 PM, ℰ𝓃𝓏ℴ ℱ𝓊𝓀ℯ wrote: > From 23d323f793b888bb2ad0d2a7a1ca095d5d64d0b8 Mon Sep 17 00:00:00 2001 > From: Enzo Fuke <milesonerd@xxxxxxxxxxx> > 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 > +------------------ Underline must be at least as long as the heading text. > + > +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: > + [snip] > +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: I think that the path should be `/sys/kernel/security/lilium/` to match the other LSMs. Same for below: > + > +.. 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 [snip] > +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 > +---------------------- Underline needs to be longer... Did you 'make htmldocs' to test this? > + > +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: [snip] > +Troubleshooting > +============== Longer underline... > + > +Common Issues > +------------ ditto. > + > +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 > +-------- ditto. > + > +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 > +====================== ditto. > + > +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 > +------------- ditto. > + > +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 > +================= ditto. > + > +Planned Features > +--------------- ditto. > + > +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 > +----------- ditto. > + > +Contributions to Lilium are welcome. Please follow the standard Linux kernel > +development process for submitting patches. -- ~Randy
