Message-ID: <3bb7279f-066a-48df-ac8d-cd8e15120aa2@infradead.org>
Date: Sat, 31 May 2025 20:30:20 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: ℰ𝓃𝓏ℴ ℱ𝓊𝓀ℯ
 <milesonerd@...look.com>, "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: Re: PATCH 2/3] security: add Lilium - Linux Integrity Lock-In User
 Module - Documentation

Hi--

On 5/31/25 6:07 PM, ℰ𝓃𝓏ℴ ℱ𝓊𝓀ℯ wrote:
> 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
> +------------------

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

Powered by blists - more mailing lists