[RFC PATCH 9/9] Loadpol LSM: add a minimal documentation

[Simon Thoby]

On 5/21/25 18:26, Randy Dunlap wrote:
> Hi--
> 
> On 5/21/25 7:01 AM, Simon THOBY wrote:
>> Introduce a minimal documentation for Loadpol, presenting the policy
>> format and the two user interfaces: the securityfs policy file and the
>> sysctl.
>>
>> Signed-off-by: Simon THOBY <git at nightmared.fr>
>> ---
>>  Documentation/admin-guide/LSM/Loadpol.rst | 81 +++++++++++++++++++++++
>>  Documentation/admin-guide/LSM/index.rst   |  1 +
>>  2 files changed, 82 insertions(+)
>>  create mode 100644 Documentation/admin-guide/LSM/Loadpol.rst
>>
>> diff --git a/Documentation/admin-guide/LSM/Loadpol.rst b/Documentation/admin-guide/LSM/Loadpol.rst
>> new file mode 100644
>> index 000000000000..0aa24a8d393c
>> --- /dev/null
>> +++ b/Documentation/admin-guide/LSM/Loadpol.rst
>> @@ -0,0 +1,81 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +=======
>> +Loadpol
>> +=======
>> +
>> +Loadpol is a Linux Security Module that enforces a user-provided policy
>> +when decided whether a dynamic module can be loaded or not.
>> +
>> +The policy can be read and rewritten at ``/sys/kernel/security/loadpol/policy``.
>> +
>> +A default policy is created that contains the current list of blacklisted modules,
> 
> Where does the current list of blacklisted modules come from?
> Is it from the kernel command line parameter "module_blacklist=" or
> somewhere else?
> 

Correct, it comes from that command line argument.
It is actually not really necessary to include it in the policy (the kernel blacklist is applied
prior to the LSM hook, so it will always apply anyway), but I thought it nice to have a "bird view"
of all the policies that apply that can prevent the load of a kernel module.

>> +and a catch-all entry that allow loading any module.
>> +
>> +Policy format
>> +=============
>> +
>> +The policy is defined as a set of line-separated entries.
>> +Each entry define the conditions for a match (the origin of the load request and
>> +the name of the kernel module), and the action to take when the load request
>> +matches the entry.
>> +
>> +
>> +Entry syntax: ``[origin=(userspace|kernel|kernel,userspace)] [module=<module_name>] action=(allow|deny)``
>> +
>> +There are two matching conditions:
>> +
>> +``origin``:
>> +    Load Requests can come from two origins:
>> +
>> +    * ``userspace`` (ie. a program in userspace called modprobe/insmod)
>                        (i.e.,
> 
>> +    * ``kernel`` (the kernel requested the module directly by calling
>> +      ``request_module(...)``, e.g. loading a filesystem when performing a
>> +      ``-o loop`` mount).
>> +
>> +    When unspecified, the condition defaults to ``kernel,userspace`` (which means
>> +    that both origins match).
>> +
>> +``module``:
>> +    Name of the kernel module being matched. The name can contain wilcards.
> 
>                                                                      wildcards.
> 
>> +    Beware, module aliases do not work!
>> +
> 
> 

Thanks for the typos, will fix.