Linux Security Module kernel repository

Clone this repo:
  1. 7dfa394 lsm: add a LSM specific README.md and SECURITY.md by Paul Moore · 1 year, 3 months ago main
  2. 2dde18c Linux 6.5 by Linus Torvalds · 4 weeks ago v6.5
  3. 85eb043 Merge tag 'scsi-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi by Linus Torvalds · 4 weeks ago
  4. 28f20a1 Merge tag 'x86-urgent-2023-08-26' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip by Linus Torvalds · 4 weeks ago
  5. 3b35375 Merge tag 'irq-urgent-2023-08-26' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip by Linus Torvalds · 4 weeks ago

Linux Security Module Subsystem

https://git.kernel.org/pub/scm/linux/kernel/git/pcmoore/lsm.git
https://github.com/LinuxSecurityModule/kernel

The Linux Security Module (LSM) subsystem is a modular access control framework design to allow multiple security models to be implemented inside of the Linux kernel; popular LSMs include SELinux, AppArmor, and Smack.

The main Linux kernel README can be found at Documentation/admin-guide/README.rst

Online Resources

The canonical LSM kernel repository is hosted by kernel.org:

There is also an officially maintained GitHub mirror:

The LSM mailing list can be found at the link below:

The official LSM mailing list archive can be found at the link below:

Kernel Tree Process

After the merge window closes upstream, a decision will be made regarding the need to rebase the next branch on top of the current Linux -rc1 release. If there have been a number of subsystem related changes outside of the subsystem‘s next branch, or if the branch’s base is too far behind linux/master, it may be necessary to rebase the next branch. If a rebase is needed, it should be done before any patches are merged, and rebasing the next branch during the remaining -rcX releases should only be done in extreme cases.

Patches will be merged into the subsystem's next branch during the development cycle which extends from merge window close up until the merge window reopens. However, it is important to note that large, complicated, or invasive patches sent late in the development cycle may be deferred until the next cycle. As a general rule, only small patches or critical fixes will be merged after -rc5/-rc6.

Any patches deemed necessary for the current Linux -rcX releases will be merged into the current stable-X.Y branch, marked with a signed tag, and a pull request sent against linux/master as soon as it is reasonable to do so.

During the development cycle Fedora Rawhide test kernels will be generated using the next and most recent stable-X.Y branches on a weekly basis, if not more often. These kernels will be tested against the SELinux test suite and audit test suite as well as being made available to everyone for additional testing.

Once the merge window opens, the next branch will be copied to a new branch, stable-X.Y, and the branch will be marked with a signed tag in the format lsm-pr-YYYYMMDD. A pull request will be sent against the linux/master branch using the signed tag.

New LSM Hook Guidelines

While LSM hooks are considered outside of the Linux kernel's stable API promise, in order to limit unnecessary churn within the kernel we do try to minimize changes to the set of LSM hooks. With that in mind, we have the following requirements for new LSM hooks:

  • Hooks should be designed to be LSM agnostic. While it is possible that only one LSM might implement the hook at the time of submission, the hook's behavior should be generic enough that other LSMs could provide a meaningful implementation.

  • The hook must be documented with a function header block that conforms to the kernel documentation style. At a minimum the documentation should explain the parameters, return values, a brief overall description, any special considerations for the callers, and any special considerations for the LSM implementations.

  • New LSM hooks must demonstrate their usefulness by providing a meaningful implementation for at least one in-kernel LSM. The goal is to demonstrate the purpose and expected semantics of the hooks. Out of tree kernel code, and pass through implementations, such as the BPF LSM, are not eligible for LSM hook reference implementations.

It is important to note that these requirements are not complete, due to the ever changing nature of the Linux kernel and the unique nature of each LSM hook. Ultimately, new LSM hooks are added to the kernel at the discretion of the maintainers and reviewers.

New LSM Guidelines

Historically we have had few requirements around new LSM additions, with Arjan van de Ven being the first to describe a basic protocol for accepting new LSMs into the Linux kernel^1. In an attempt to document Arjan's basic ideas and update them for modern Linux kernel development, here are a list of requirements for new LSM submissions:

  • The new LSM‘s author(s) must commit to maintain and support the new LSM for an extended period of time; this applies both to authors that are employed to develop and maintain a LSM as well as those that develop and maintain a LSM on their own time. If the authors are currently supporting a LSM as part of their employment, there is an expectation upstream that support will continue beyond the authors’ tenure at their current company. In either case, if the authors are unable to commit to supporting the LSM for an extended period of time, a reasonable succession plan must be submitted along with the LSM.

  • The new LSM must be sufficiently unique to justify the additional work involved in reviewing, maintaining, and supporting the LSM. It is reasonable for there to be a level of overlap between LSMs, but either the security model or the admin/user experience must be significantly unique.

  • New LSMs must include documentation providing a clear explanation of the LSM's requirements, goals, and expected uses. The documentation does not need to rise to the level of a formal security model, but it should include a basic threat model with a description of the mitigations provided by the LSM. Both the threat model and the LSM mitigations must be considered “reasonable” by the LSM community as a whole.

  • Any user visible interfaces provided by the LSM must be well documented. It is important to remember the user visible APIs are considered to be “forever APIs” by the Linux kernel community; do not add an API that cannot be supported for the next 20+ years.

  • New LSMs must be accompanied by a test suite to verify basic functionality and help identify regressions. The test suite must be publicly available without download restrictions requiring accounts, subscriptions, etc. Test coverage does not need to reach a specific percentage, but core functionality and any user interfaces should be well covered by the test suite. Maintaining the test suite in a public git repository is preferable over tarball snapshots. Integrating the test suite with existing automated Linux kernel testing services is encouraged.

  • The LSM implementation must follow general Linux kernel coding practices, faithfully implement the security model and APIs described in the documentation, and be free of any known defects at the time of submission.

  • If new userspace tools, or patches to existing tools, are necessary to configure, operate, or otherwise manage the LSM, these tools or patches must be publicly available without download restrictions requiring accounts, subscriptions, etc. Maintaining these tools or patches in a public git repository is preferable over tarball snapshots.

It is important to note that these requirements are not complete, due to the ever changing nature of the Linux kernel and the unique nature of each LSM. Ultimately, new LSMs are added to the kernel at the discretion of the maintainers and reviewers.