Hi--

On 5/31/25 6:07 PM, ℰ𝓃𝓏ℴ ℱ𝓊𝓀ℯ wrote:

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