[PATCH v3] Documentation: Document the Linux Kernel CVE process

[PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

The Linux kernel project now has the ability to assign CVEs to fixed
issues, so document the process and how individual developers can get a
CVE if one is not automatically assigned for their fixes.

Reviewed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Sasha Levin <sashal@kernel.org>
Signed-off-by: Lee Jones <lee@kernel.org>
---
v3: fix up wording in security-bugs.rst based on the changes to the cve
    assignment process from v1, thanks to a private reviewer for
    pointing that out.
v2: Grammer fixes based on review from Randy
    Updated paragraph about how CVE identifiers will be assigned
    (automatically when added to stable trees, or ask us for one
    directly before that happens if so desired)

 Documentation/process/cve.rst           | 120 ++++++++++++++++++++++++
 Documentation/process/index.rst         |   1 +
 Documentation/process/security-bugs.rst |   5 +-
 3 files changed, 123 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/process/cve.rst

diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst
new file mode 100644
index 000000000000..6465e6a79c18
--- /dev/null
+++ b/Documentation/process/cve.rst
@@ -0,0 +1,120 @@
+CVEs
+====
+
+Common Vulnerabilities and Exposure (CVE®) numbers were developed as an
+unambiguous way to identify, define, and catalog publicly disclosed
+security vulnerabilities.  Over time, their usefulness has declined with
+regards to the kernel project, and CVE numbers were very often assigned
+in inappropriate ways and for inappropriate reasons.  Because of this,
+the kernel development community has tended to avoid them.  However, the
+combination of continuing pressure to assign CVEs and other forms of
+security identifiers, and ongoing abuses by community members outside of
+the kernel community has made it clear that the kernel community should
+have control over those assignments.
+
+The Linux kernel developer team does have the ability to assign CVEs for
+potential Linux kernel security issues.  This assignment is independent
+of the :doc:`normal Linux kernel security bug reporting
+process<../process/security_bugs>`.
+
+A list of all assigned CVEs for the Linux kernel can be found in the
+archives of the linux-cve mailing list, as seen on
+https://lore.kernel.org/linux-cve-announce/.  To get notice of the
+assigned CVEs, please subscribe to that mailing list.
+
+Process
+-------
+
+As part of the normal stable release process, kernel changes that are
+potentially security issues are identified by the developers responsible
+for CVE number assignments and have CVE numbers automatically assigned
+to them.  These assignments are published on the linux-cve-announce
+mailing list as announcements on a frequent basis.
+
+Note, due to the layer at which the Linux kernel is in a system, almost
+any bug might be exploitable to compromise the security of the kernel,
+but the possibility of exploitation is often not evident when the bug is
+fixed.  Because of this, the CVE assignment team is overly cautious and
+assign CVE numbers to any bugfix that they identify.  This
+explains the seemingly large number of CVEs that are issued by the Linux
+kernel team.
+
+If the CVE assignment team misses a specific fix that any user feels
+should have a CVE assigned to it, please email them at <cve@kernel.org>
+and the team there will work with you on it.  Note that no potential
+security issues should be sent to this alias, it is ONLY for assignment
+of CVEs for fixes that are already in released kernel trees.  If you
+feel you have found an unfixed security issue, please follow the
+:doc:`normal Linux kernel security bug reporting
+process<../process/security_bugs>`.
+
+No CVEs will be automatically assigned for unfixed security issues in
+the Linux kernel; assignment will only automatically happen after a fix
+is available and applied to a stable kernel tree, and it will be tracked
+that way by the git commit id of the original fix.  If anyone wishes to
+have a CVE assigned before an issue is resolved with a commit, please
+contact the kernel CVE assignment team at <cve@kernel.org> to get an
+identifier assigned from their batch of reserved identifiers.
+
+No CVEs will be assigned for any issue found in a version of the kernel
+that is not currently being actively supported by the Stable/LTS kernel
+team.  A list of the currently supported kernel branches can be found at
+https://kernel.org/category/releases.html
+
+Disputes of assigned CVEs
+-------------------------
+
+The authority to dispute or modify an assigned CVE for a specific kernel
+change lies solely with the maintainers of the relevant subsystem
+affected.  This principle ensures a high degree of accuracy and
+accountability in vulnerability reporting.  Only those individuals with
+deep expertise and intimate knowledge of the subsystem can effectively
+assess the validity and scope of a reported vulnerability and determine
+its appropriate CVE designation.  Any attempt to modify or dispute a CVE
+outside of this designated authority could lead to confusion, inaccurate
+reporting, and ultimately, compromised systems.
+
+Invalid CVEs
+------------
+
+If a security issue is found in a Linux kernel that is only supported by
+a Linux distribution due to the changes that have been made by that
+distribution, or due to the distribution supporting a kernel version
+that is no longer one of the kernel.org supported releases, then a CVE
+can not be assigned by the Linux kernel CVE team, and must be asked for
+from that Linux distribution itself.
+
+Any CVE that is assigned against the Linux kernel for an actively
+supported kernel version, by any group other than the kernel assignment
+CVE team should not be treated as a valid CVE.  Please notify the
+kernel CVE assignment team at <cve@kernel.org> so that they can work to
+invalidate such entries through the CNA remediation process.
+
+Applicability of specific CVEs
+------------------------------
+
+As the Linux kernel can be used in many different ways, with many
+different ways of accessing it by external users, or no access at all,
+the applicability of any specific CVE is up to the user of Linux to
+determine, it is not up to the CVE assignment team.  Please do not
+contact us to attempt to determine the applicability of any specific
+CVE.
+
+Also, as the source tree is so large, and any one system only uses a
+small subset of the source tree, any users of Linux should be aware that
+large numbers of assigned CVEs are not relevant for their systems.
+
+In short, we do not know your use case, and we do not know what portions
+of the kernel that you use, so there is no way for us to determine if a
+specific CVE is relevant for your system.
+
+As always, it is best to take all released kernel changes, as they are
+tested together in a unified whole by many community members, and not as
+individual cherry-picked changes.  Also note that for many bugs, the
+solution to the overall problem is not found in a single change, but by
+the sum of many fixes on top of each other.  Ideally CVEs will be
+assigned to all fixes for all issues, but sometimes we do not notice
+fixes in released kernels, so do not assume that because a specific
+change does not have a CVE assigned to it, that it is not relevant to
+take.
+
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 6cb732dfcc72..de9cbb7bd7eb 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -81,6 +81,7 @@ of special classes of bugs: regressions and security problems.
 
    handling-regressions
    security-bugs
+   cve
    embargoed-hardware-issues
 
 Maintainer information
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 692a3ba56cca..56c560a00b37 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -99,9 +99,8 @@ CVE assignment
 The security team does not assign CVEs, nor do we require them for
 reports or fixes, as this can needlessly complicate the process and may
 delay the bug handling.  If a reporter wishes to have a CVE identifier
-assigned, they should find one by themselves, for example by contacting
-MITRE directly.  However under no circumstances will a patch inclusion
-be delayed to wait for a CVE identifier to arrive.
+assigned for a confirmed issue, they can contact the :doc:`kernel CVE
+assignment team<../process/cve>` to obtain one.
 
 Non-disclosure agreements
 -------------------------
-- 
2.43.1

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Lukas Bulwahn]

On Wed, Feb 14, 2024 at 9:01 AM Greg Kroah-Hartman
<gregkh@linuxfoundation.org> wrote:
>
> The Linux kernel project now has the ability to assign CVEs to fixed
> issues, so document the process and how individual developers can get a
> CVE if one is not automatically assigned for their fixes.
>
> Reviewed-by: Kees Cook <keescook@chromium.org>
> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> Signed-off-by: Lee Jones <lee@kernel.org>
> ---
> v3: fix up wording in security-bugs.rst based on the changes to the cve
>     assignment process from v1, thanks to a private reviewer for
>     pointing that out.
> v2: Grammer fixes based on review from Randy
>     Updated paragraph about how CVE identifiers will be assigned
>     (automatically when added to stable trees, or ask us for one
>     directly before that happens if so desired)
>

Hi Greg, Sasha, Lee,

Generally, I think this is a great step forward on the whole "security
vulnerability mess" and this will certainly help me and others in the
embedded space to argue to update to recent stable kernel versions.
This can then finally put the practice of shipping multiple-year-old
kernel versions to an end. Often this was just done with the argument
that there is not a recent CVE and fix assigned to some recent stable
kernel version---and integrators think updates to recent kernel stable
versions are not needed and not recommended.

I am looking forward to seeing what and how many stable commits are
going to get CVEs assigned. If Greg's policy from the Kernel Recipes
2019 presentation comes into play, every git kernel hash (GKH)---at
least in the stable tree---could get a CVE identifier (just to be on
the safe side). But I assume you are going to use some expert
knowledge, heuristics or some machine-learning AI to make some commits
in the stable tree carrying a CVE identifier and some others not.

Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>

Below, there is just some nitpicking on some wording:

>  Documentation/process/cve.rst           | 120 ++++++++++++++++++++++++
>  Documentation/process/index.rst         |   1 +
>  Documentation/process/security-bugs.rst |   5 +-
>  3 files changed, 123 insertions(+), 3 deletions(-)
>  create mode 100644 Documentation/process/cve.rst
>
> diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst
> new file mode 100644
> index 000000000000..6465e6a79c18
> --- /dev/null
> +++ b/Documentation/process/cve.rst
> @@ -0,0 +1,120 @@
> +CVEs
> +====
> +
> +Common Vulnerabilities and Exposure (CVE®) numbers were developed as an
> +unambiguous way to identify, define, and catalog publicly disclosed
> +security vulnerabilities.  Over time, their usefulness has declined with
> +regards to the kernel project, and CVE numbers were very often assigned
> +in inappropriate ways and for inappropriate reasons.  Because of this,
> +the kernel development community has tended to avoid them.  However, the
> +combination of continuing pressure to assign CVEs and other forms of
> +security identifiers, and ongoing abuses by community members outside of
> +the kernel community has made it clear that the kernel community should
> +have control over those assignments.
> +

Though, I get what is meant with "the community members outside of the
kernel community", it still feels strange when reading.

Here are some alternatives I could come up with:

"reporters outside the kernel community"
"reporters beyond the actively contributing/engaged kernel community members"
"individuals not engaged with the kernel community"

> +The Linux kernel developer team does have the ability to assign CVEs for
> +potential Linux kernel security issues.  This assignment is independent
> +of the :doc:`normal Linux kernel security bug reporting
> +process<../process/security_bugs>`.
> +
> +A list of all assigned CVEs for the Linux kernel can be found in the
> +archives of the linux-cve mailing list, as seen on
> +https://lore.kernel.org/linux-cve-announce/.  To get notice of the
> +assigned CVEs, please subscribe to that mailing list.
> +
> +Process
> +-------
> +
> +As part of the normal stable release process, kernel changes that are
> +potentially security issues are identified by the developers responsible
> +for CVE number assignments and have CVE numbers automatically assigned
> +to them.  These assignments are published on the linux-cve-announce
> +mailing list as announcements on a frequent basis.
> +
> +Note, due to the layer at which the Linux kernel is in a system, almost
> +any bug might be exploitable to compromise the security of the kernel,

Just a nit: but I would say: a kernel bug is compromising the
"security of the system"; the kernel bug just happens to allow anyone
to run any code on their hardware... in some systems that is a
security issue, but in my previous MSDOS system that was the default
behaviour ;)

> +but the possibility of exploitation is often not evident when the bug is
> +fixed.  Because of this, the CVE assignment team is overly cautious and
> +assign CVE numbers to any bugfix that they identify.  This
> +explains the seemingly large number of CVEs that are issued by the Linux
> +kernel team.
> +
> +If the CVE assignment team misses a specific fix that any user feels
> +should have a CVE assigned to it, please email them at <cve@kernel.org>
> +and the team there will work with you on it.  Note that no potential
> +security issues should be sent to this alias, it is ONLY for assignment
> +of CVEs for fixes that are already in released kernel trees.  If you
> +feel you have found an unfixed security issue, please follow the
> +:doc:`normal Linux kernel security bug reporting
> +process<../process/security_bugs>`.
> +
> +No CVEs will be automatically assigned for unfixed security issues in
> +the Linux kernel; assignment will only automatically happen after a fix
> +is available and applied to a stable kernel tree, and it will be tracked
> +that way by the git commit id of the original fix.  If anyone wishes to
> +have a CVE assigned before an issue is resolved with a commit, please
> +contact the kernel CVE assignment team at <cve@kernel.org> to get an
> +identifier assigned from their batch of reserved identifiers.
> +
> +No CVEs will be assigned for any issue found in a version of the kernel
> +that is not currently being actively supported by the Stable/LTS kernel
> +team.  A list of the currently supported kernel branches can be found at
> +https://kernel.org/category/releases.html
> +
> +Disputes of assigned CVEs
> +-------------------------
> +
> +The authority to dispute or modify an assigned CVE for a specific kernel
> +change lies solely with the maintainers of the relevant subsystem
> +affected.  This principle ensures a high degree of accuracy and
> +accountability in vulnerability reporting.  Only those individuals with
> +deep expertise and intimate knowledge of the subsystem can effectively
> +assess the validity and scope of a reported vulnerability and determine
> +its appropriate CVE designation.  Any attempt to modify or dispute a CVE
> +outside of this designated authority could lead to confusion, inaccurate
> +reporting, and ultimately, compromised systems.
> +
> +Invalid CVEs
> +------------
> +
> +If a security issue is found in a Linux kernel that is only supported by
> +a Linux distribution due to the changes that have been made by that
> +distribution, or due to the distribution supporting a kernel version
> +that is no longer one of the kernel.org supported releases, then a CVE
> +can not be assigned by the Linux kernel CVE team, and must be asked for
> +from that Linux distribution itself.
> +
> +Any CVE that is assigned against the Linux kernel for an actively
> +supported kernel version, by any group other than the kernel assignment
> +CVE team should not be treated as a valid CVE.  Please notify the
> +kernel CVE assignment team at <cve@kernel.org> so that they can work to
> +invalidate such entries through the CNA remediation process.
> +
> +Applicability of specific CVEs
> +------------------------------
> +
> +As the Linux kernel can be used in many different ways, with many
> +different ways of accessing it by external users, or no access at all,
> +the applicability of any specific CVE is up to the user of Linux to
> +determine, it is not up to the CVE assignment team.  Please do not
> +contact us to attempt to determine the applicability of any specific
> +CVE.
> +
> +Also, as the source tree is so large, and any one system only uses a
> +small subset of the source tree, any users of Linux should be aware that
> +large numbers of assigned CVEs are not relevant for their systems.
> +
> +In short, we do not know your use case, and we do not know what portions
> +of the kernel that you use, so there is no way for us to determine if a
> +specific CVE is relevant for your system.
> +
> +As always, it is best to take all released kernel changes, as they are
> +tested together in a unified whole by many community members, and not as
> +individual cherry-picked changes.  Also note that for many bugs, the
> +solution to the overall problem is not found in a single change, but by
> +the sum of many fixes on top of each other.  Ideally CVEs will be
> +assigned to all fixes for all issues, but sometimes we do not notice
> +fixes in released kernels, so do not assume that because a specific
> +change does not have a CVE assigned to it, that it is not relevant to
> +take.
> +
> diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
> index 6cb732dfcc72..de9cbb7bd7eb 100644
> --- a/Documentation/process/index.rst
> +++ b/Documentation/process/index.rst
> @@ -81,6 +81,7 @@ of special classes of bugs: regressions and security problems.
>
>     handling-regressions
>     security-bugs
> +   cve
>     embargoed-hardware-issues
>
>  Maintainer information
> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> index 692a3ba56cca..56c560a00b37 100644
> --- a/Documentation/process/security-bugs.rst
> +++ b/Documentation/process/security-bugs.rst
> @@ -99,9 +99,8 @@ CVE assignment
>  The security team does not assign CVEs, nor do we require them for
>  reports or fixes, as this can needlessly complicate the process and may
>  delay the bug handling.  If a reporter wishes to have a CVE identifier
> -assigned, they should find one by themselves, for example by contacting
> -MITRE directly.  However under no circumstances will a patch inclusion
> -be delayed to wait for a CVE identifier to arrive.
> +assigned for a confirmed issue, they can contact the :doc:`kernel CVE
> +assignment team<../process/cve>` to obtain one.
>
>  Non-disclosure agreements
>  -------------------------
> --
> 2.43.1
>
>

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Vegard Nossum]

On 14/02/2024 09:00, Greg Kroah-Hartman wrote:
> diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst
> new file mode 100644
> index 000000000000..6465e6a79c18
> --- /dev/null
> +++ b/Documentation/process/cve.rst
> @@ -0,0 +1,120 @@
> +CVEs
> +====

Document titles should have ==== above them as well, and then you would
need to shift all the other headings in this document (i.e. all the ---
should become ===).

Info here: 
https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

> +The Linux kernel developer team does have the ability to assign CVEs for
> +potential Linux kernel security issues.  This assignment is independent
> +of the :doc:`normal Linux kernel security bug reporting
> +process<../process/security_bugs>`.

These documents are both under process/ so it should be enough to say:

:doc:`[...] <security-bugs>`

In fact, when building the docs with your patch applied, I see:

Documentation/process/cve.rst:15: WARNING: unknown document: 
../process/security_bugs
Documentation/process/cve.rst:42: WARNING: unknown document: 
../process/security_bugs

Note the hyphen vs. underscore (it should have a hyphen like my line above).

> +Process
> +-------
> +
> +As part of the normal stable release process, kernel changes that are
> +potentially security issues are identified by the developers responsible
> +for CVE number assignments and have CVE numbers automatically assigned
> +to them.  These assignments are published on the linux-cve-announce
> +mailing list as announcements on a frequent basis.
> +
> +Note, due to the layer at which the Linux kernel is in a system, almost
> +any bug might be exploitable to compromise the security of the kernel,
> +but the possibility of exploitation is often not evident when the bug is
> +fixed.  Because of this, the CVE assignment team is overly cautious and

What is the composition of the CVE assignment team, or is that secret?
Should this be a MAINTAINERS entry? (s@k.org is one.)

> +If the CVE assignment team misses a specific fix that any user feels
> +should have a CVE assigned to it, please email them at <cve@kernel.org>
> +and the team there will work with you on it.  Note that no potential
> +security issues should be sent to this alias, it is ONLY for assignment
> +of CVEs for fixes that are already in released kernel trees.  If you
> +feel you have found an unfixed security issue, please follow the
> +:doc:`normal Linux kernel security bug reporting
> +process<../process/security_bugs>`.

Same

> +Disputes of assigned CVEs
> +-------------------------
> +
> +The authority to dispute or modify an assigned CVE for a specific kernel
> +change lies solely with the maintainers of the relevant subsystem
> +affected.  This principle ensures a high degree of accuracy and
> +accountability in vulnerability reporting.  Only those individuals with
> +deep expertise and intimate knowledge of the subsystem can effectively
> +assess the validity and scope of a reported vulnerability and determine
> +its appropriate CVE designation.  Any attempt to modify or dispute a CVE
> +outside of this designated authority could lead to confusion, inaccurate
> +reporting, and ultimately, compromised systems.

Just to clarify, I think "dispute" here is used in the
Mitre/CVE-technical meaning of the word, correct? I assume people will
still have the right to say "hey, this doesn't look like a real issue
[because of X/Y/Z]" on a mailing list.

> --- a/Documentation/process/security-bugs.rst
> +++ b/Documentation/process/security-bugs.rst
> @@ -99,9 +99,8 @@ CVE assignment
>   The security team does not assign CVEs, nor do we require them for
>   reports or fixes, as this can needlessly complicate the process and may
>   delay the bug handling.  If a reporter wishes to have a CVE identifier
> -assigned, they should find one by themselves, for example by contacting
> -MITRE directly.  However under no circumstances will a patch inclusion
> -be delayed to wait for a CVE identifier to arrive.
> +assigned for a confirmed issue, they can contact the :doc:`kernel CVE
> +assignment team<../process/cve>` to obtain one.

Same here, this could be just <cve>.


Vegard

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Krzysztof Kozlowski]

On 14/02/2024 09:00, Greg Kroah-Hartman wrote:
> The Linux kernel project now has the ability to assign CVEs to fixed
> issues, so document the process and how individual developers can get a
> CVE if one is not automatically assigned for their fixes.
> 
> Reviewed-by: Kees Cook <keescook@chromium.org>
> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> Signed-off-by: Lee Jones <lee@kernel.org>
> ---
> v3: fix up wording in security-bugs.rst based on the changes to the cve
>     assignment process from v1, thanks to a private reviewer for
>     pointing that out.
> v2: Grammer fixes based on review from Randy
>     Updated paragraph about how CVE identifiers will be assigned
>     (automatically when added to stable trees, or ask us for one
>     directly before that happens if so desired)
> 
>  Documentation/process/cve.rst           | 120 ++++++++++++++++++++++++
>  Documentation/process/index.rst         |   1 +
>  Documentation/process/security-bugs.rst |   5 +-

Great direction! Finally all these bugs we are fixing every release
(thus in stable trees) will get proper attention via assigned CVEs.

Reviewed-by: Krzysztof Kozlowski <krzk@kernel.org>

Best regards,
Krzysztof

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Konstantin Ryabitsev]

On Wed, Feb 14, 2024 at 09:00:30AM +0100, Greg Kroah-Hartman wrote:
> +A list of all assigned CVEs for the Linux kernel can be found in the
> +archives of the linux-cve mailing list, as seen on
> +https://lore.kernel.org/linux-cve-announce/.  To get notice of the
> +assigned CVEs, please subscribe to that mailing list.

Since the archives page doesn't carry any instructions on how to subscribe,
I think you should link to https://subspace.kernel.org/subscribing.html here,
e.g.:

... please `subscribe <https://subspace.kernel.org/subscribing.html>`_ to that
mailing list.

> +No CVEs will be assigned for any issue found in a version of the kernel
> +that is not currently being actively supported by the Stable/LTS kernel
> +team.  A list of the currently supported kernel branches can be found at
> +https://kernel.org/category/releases.html

Can just be https://kernel.org/releases.html

Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

-K

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jiri Kosina]

On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:

> +No CVEs will be automatically assigned for unfixed security issues in
> +the Linux kernel; assignment will only automatically happen after a fix
> +is available and applied to a stable kernel tree, and it will be tracked
> +that way by the git commit id of the original fix. 

I think this needs way more clarification .. how exactly is this going to 
work?

Do I read this correctly that *everything* that lands in -stable will 
automatically get CVE assigned? If so, that's just plain crazy. Just took 
a random peek on the topmost -stable changelog ...

	ASoC: codecs: wsa883x: fix PA volume control
	ASoC: codecs: lpass-wsa-macro: fix compander volume hack
	ASoC: codecs: wcd938x: fix headphones volume controls
	ASoC: qcom: sc8280xp: limit speaker volumes
	drm/amdgpu: Fix missing error code in 'gmc_v6/7/8/9_0_hw_init()'

Only the last one can *potentially* be considered a CVE candidate, but 
someone would actually have to take a *deep* look. Most likely it'll be a 
functional issue, but not a security issue by any measures.

So I hope it's not the case, and someone will actually be doing some 
triage. If that's the case -- is this process described anywhere?

Also, how are the CVSS-like scores going to be assigned? There are no 
details whatsoever about that in the document.

In any case, by making this change we are going to make security theathre 
industry super-happy (they will have a lot of expensive nothing going on), 
and all the distros not basing on -stable very unhappy (we're already 
drowning because everybody and his grandma wants to become famous by 
publishing a CVE for something completely irrelevant). If this is the 
intention, it should be spelled out loud and clear.

Thanks,

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 1579 bytes --]

On Wed, Feb 14, 2024 at 02:43:48PM +0100, Jiri Kosina wrote:
> On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:

> > +No CVEs will be automatically assigned for unfixed security issues in
> > +the Linux kernel; assignment will only automatically happen after a fix
> > +is available and applied to a stable kernel tree, and it will be tracked
> > +that way by the git commit id of the original fix. 

> I think this needs way more clarification .. how exactly is this going to 
> work?

> Do I read this correctly that *everything* that lands in -stable will 
> automatically get CVE assigned? If so, that's just plain crazy. Just took 
> a random peek on the topmost -stable changelog ...

> 	ASoC: codecs: wsa883x: fix PA volume control
> 	ASoC: codecs: lpass-wsa-macro: fix compander volume hack
> 	ASoC: codecs: wcd938x: fix headphones volume controls
> 	ASoC: qcom: sc8280xp: limit speaker volumes
> 	drm/amdgpu: Fix missing error code in 'gmc_v6/7/8/9_0_hw_init()'

> Only the last one can *potentially* be considered a CVE candidate, but 
> someone would actually have to take a *deep* look. Most likely it'll be a 
> functional issue, but not a security issue by any measures.

Not addressing your point in general but the speaker volume limiting is
security relevant, that change prevents physical damage to the system.
There's an argument for many headphone volume related fixes too since
excessively large volumes can cause substantial distress and potential
injury to users (I can't remember if that fix would be relevant to that
issue).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 02:43:48PM +0100, Jiri Kosina wrote:
> On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:
> 
> > +No CVEs will be automatically assigned for unfixed security issues in
> > +the Linux kernel; assignment will only automatically happen after a fix
> > +is available and applied to a stable kernel tree, and it will be tracked
> > +that way by the git commit id of the original fix. 
> 
> I think this needs way more clarification .. how exactly is this going to 
> work?
> 
> Do I read this correctly that *everything* that lands in -stable will 
> automatically get CVE assigned? If so, that's just plain crazy. Just took 
> a random peek on the topmost -stable changelog ...
> 
> 	ASoC: codecs: wsa883x: fix PA volume control
> 	ASoC: codecs: lpass-wsa-macro: fix compander volume hack
> 	ASoC: codecs: wcd938x: fix headphones volume controls
> 	ASoC: qcom: sc8280xp: limit speaker volumes
> 	drm/amdgpu: Fix missing error code in 'gmc_v6/7/8/9_0_hw_init()'
> 
> Only the last one can *potentially* be considered a CVE candidate, but 
> someone would actually have to take a *deep* look. Most likely it'll be a 
> functional issue, but not a security issue by any measures.
> 
> So I hope it's not the case, and someone will actually be doing some 
> triage. If that's the case -- is this process described anywhere?

It's described as "we know it when we see it" :)

Seriously, this is something that Sasha has already been doing
successfully for 3+ years now with the GSD project, so look at the
commits that have been assigned there for an example of what will be
picked.  Also we will probably go back in time for a few years and use
that data to populate the CVE database for older releases as long as
they are still in currently supported releases as this is something that
the CVE group has asked us to do already.

As for your list above, I doubt any of those would be a CVE, give us
some credit here.  Let's see how it goes and if people complain we are
picking things that we shouldn't be picking, OR if we aren't picking
enough, they will then be asked to join the team doing the work :)

The people that make up the current team, Lee, Sasha, and I, have a LONG
history of fixing and triaging and managing security bugs for the
kernel, in the community and in corporate environments.  We know how to
do this as we have been doing it for decades already.  If you or anyone
else wishes to help us out with this classification, we can gladly use
the help.

> Also, how are the CVSS-like scores going to be assigned? There are no 
> details whatsoever about that in the document.

We will not be doing any CVSS scoring as that is outside the scope of a
CVE entry and not required at all, and the CVE board agrees with this
decision.  As you well know, doing something like this for the kernel
where we have no idea what your use case is, is almost impossible on the
best days.

There are external groups that suck in the CVE entries and attempt to
assign CVSS-like scores to issues.  It will be "interesting" to see how
they classify things, but if the history of how well they have done this
in the past is any indication, their tools need a lot of work and
hopefully people stop relying on them and do the evaluation of their own
use cases instead.

> In any case, by making this change we are going to make security theathre 
> industry super-happy (they will have a lot of expensive nothing going on), 
> and all the distros not basing on -stable very unhappy (we're already 
> drowning because everybody and his grandma wants to become famous by 
> publishing a CVE for something completely irrelevant). If this is the 
> intention, it should be spelled out loud and clear.

As we are not allowed to credit anyone in the publication of a CVE, I
doubt the "I want a CVE!" group will get any louder than they currently
are.  And if it generates these people to actually submit bug fixes with
their reports, all the better for us!

I can't speak to the "security theatre industry" but right now, we have
a real problem of external groups assigning random CVEs to the kernel
with absolutely no input from us and no accountability, which is causing
a lot of us real problems.  This will take away the ability for those
groups to continue to abuse our project just because of their broken
engineering rules, and properly integrate them into our development
process if they so desire to join in.

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 01:55:43PM +0000, Mark Brown wrote:
> On Wed, Feb 14, 2024 at 02:43:48PM +0100, Jiri Kosina wrote:
> > On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:
> 
> > > +No CVEs will be automatically assigned for unfixed security issues in
> > > +the Linux kernel; assignment will only automatically happen after a fix
> > > +is available and applied to a stable kernel tree, and it will be tracked
> > > +that way by the git commit id of the original fix. 
> 
> > I think this needs way more clarification .. how exactly is this going to 
> > work?
> 
> > Do I read this correctly that *everything* that lands in -stable will 
> > automatically get CVE assigned? If so, that's just plain crazy. Just took 
> > a random peek on the topmost -stable changelog ...
> 
> > 	ASoC: codecs: wsa883x: fix PA volume control
> > 	ASoC: codecs: lpass-wsa-macro: fix compander volume hack
> > 	ASoC: codecs: wcd938x: fix headphones volume controls
> > 	ASoC: qcom: sc8280xp: limit speaker volumes
> > 	drm/amdgpu: Fix missing error code in 'gmc_v6/7/8/9_0_hw_init()'
> 
> > Only the last one can *potentially* be considered a CVE candidate, but 
> > someone would actually have to take a *deep* look. Most likely it'll be a 
> > functional issue, but not a security issue by any measures.
> 
> Not addressing your point in general but the speaker volume limiting is
> security relevant, that change prevents physical damage to the system.
> There's an argument for many headphone volume related fixes too since
> excessively large volumes can cause substantial distress and potential
> injury to users (I can't remember if that fix would be relevant to that
> issue).

And this points to the fact that we now have a way, if a
maintainer/developer says "hey, that commit could be a potential issue,
I want to call that out to others!" they now have a path to do so.  Just
email cve@kernel.org "can you assign a cve to git id XXXX because of
YYY" and we will do so.

thanks!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jiri Kosina]

On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:

> The people that make up the current team, Lee, Sasha, and I, have a LONG
> history of fixing and triaging and managing security bugs for the
> kernel, in the community and in corporate environments.  We know how to
> do this as we have been doing it for decades already.  

Thanks for clarifying. Maybe the wording could use some more verbosity 
then; one of my potential readings of it was "everything that gets picked 
for -stable will get a CVE assigned".

> If you or anyone else wishes to help us out with this classification, we 
> can gladly use the help.

Thanks, but no, thanks, I want to stay away from the CVE tragedy as far as 
possible :)

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jiri Kosina]

On Wed, 14 Feb 2024, Mark Brown wrote:

> Not addressing your point in general but the speaker volume limiting is
> security relevant, that change prevents physical damage to the system.
> There's an argument for many headphone volume related fixes too since
> excessively large volumes can cause substantial distress and potential
> injury to users (I can't remember if that fix would be relevant to that
> issue).

Thanks, I guess you are actually supporting my point, and that is -- there 
is no consensus whatsoever of what assigning a CVE actually means, at all.

To me -- physical damage to the system, fair enough, that might really 
easily be security relevant.

Something being too loud, causing distress ... that's really a grey zone 
(to put it mildly) for me. How about e.g. a bug in GPU driver, leading to 
a flickering screen? Many people are very sensitive to that (both 
physically and mentally) for various reasons.

Bug worth fixing? Absolutely, as soon as possible. Security-relevant? Not 
in my book.

To me, kernel is in no way special, in this respect, actually. With each 
and every coding error in software of your choice, given anough fantasy, 
you'll come up with a scenario where this will cause some real issues to 
some living human.

That's not what CVE is about at all, at least in my understaing.

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 03:38:52PM +0100, Jiri Kosina wrote:
> On Wed, 14 Feb 2024, Greg Kroah-Hartman wrote:
> 
> > The people that make up the current team, Lee, Sasha, and I, have a LONG
> > history of fixing and triaging and managing security bugs for the
> > kernel, in the community and in corporate environments.  We know how to
> > do this as we have been doing it for decades already.  
> 
> Thanks for clarifying. Maybe the wording could use some more verbosity 
> then; one of my potential readings of it was "everything that gets picked 
> for -stable will get a CVE assigned".

CVE has a very specific definition already, as per cve.org:

	 CVE Record is the descriptive data about a vulnerability
	 associated with a CVE ID, provided by a CVE Numbering Authority
	 (CNA). This data is provided in multiple human and
	 machine-readable formats.

And they define "vulnerability" as:

	An instance of one or more weaknesses in a Product that can be
	exploited, causing a negative impact to confidentiality,
	integrity, or availability; a set of conditions or behaviors
	that allows the violation of an explicit or implicit security
	policy.

and as a CNA we must follow that definition.  No need to restate the CVE
rules in our own document, I am sure that if we don't follow them, lots
of people will be quick to point it out and we will revoke those ids
that we mess up on.

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 1048 bytes --]

On Wed, Feb 14, 2024 at 03:46:12PM +0100, Jiri Kosina wrote:
> On Wed, 14 Feb 2024, Mark Brown wrote:

> > There's an argument for many headphone volume related fixes too since
> > excessively large volumes can cause substantial distress and potential
> > injury to users (I can't remember if that fix would be relevant to that
> > issue).

> Something being too loud, causing distress ... that's really a grey zone 
> (to put it mildly) for me. How about e.g. a bug in GPU driver, leading to 
> a flickering screen? Many people are very sensitive to that (both 
> physically and mentally) for various reasons.

> Bug worth fixing? Absolutely, as soon as possible. Security-relevant? Not 
> in my book.

To be clear, most headphone drivers can easily generate output levels
which will cause temporary or permanent hearing loss after very brief
exposure.  The distress is the urgent and instinctive need to remove the
headphones as fast as possible that tends to result, much as it would
for any other ongoing source of injury.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Thorsten Leemhuis]

On 14.02.24 09:00, Greg Kroah-Hartman wrote:
> The Linux kernel project now has the ability to assign CVEs to fixed
> issues, so document the process and how individual developers can get a
> CVE if one is not automatically assigned for their fixes.
> [...]

This following is just nitpicking, hence feel free to ignore.

> +As always, it is best to take all released kernel changes, as they are
> +tested together in a unified whole by many community members, and not as
> +individual cherry-picked changes.  Also note that for many bugs, the
> +solution to the overall problem is not found in a single change, but by
> +the sum of many fixes on top of each other.  Ideally CVEs will be
> +assigned to all fixes for all issues, but sometimes we do not notice
> +fixes in released kernels, so do not assume that because a specific
> +change does not have a CVE assigned to it, that it is not relevant to
> +take.

There are a four "not" in the last pretty long sentence which makes it
kinda hard to parse. Avoiding that could look like this:

Ideally CVEs will be assigned to all fixes for all issues -- but
sometimes we will fail to notice fixes, therefore assume that some
changes without an assigned CVE might still be relevant to take.

Or like this:

Ideally CVEs will be assigned to all fixes for all issues, but sometimes
we will overlook fixes -- therefore assume that some changes that lack
an assigned CVE might still be relevant to take.

Not sure if that really makes it better, I guess you as a native speaker
are a better judge here.

Ciao, Thorsten (who also wondered what "to all fixes for all issues"
exactly means, but whatever)

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Thu, Feb 15, 2024 at 09:17:59AM +0100, Thorsten Leemhuis wrote:
> On 14.02.24 09:00, Greg Kroah-Hartman wrote:
> > The Linux kernel project now has the ability to assign CVEs to fixed
> > issues, so document the process and how individual developers can get a
> > CVE if one is not automatically assigned for their fixes.
> > [...]
> 
> This following is just nitpicking, hence feel free to ignore.
> 
> > +As always, it is best to take all released kernel changes, as they are
> > +tested together in a unified whole by many community members, and not as
> > +individual cherry-picked changes.  Also note that for many bugs, the
> > +solution to the overall problem is not found in a single change, but by
> > +the sum of many fixes on top of each other.  Ideally CVEs will be
> > +assigned to all fixes for all issues, but sometimes we do not notice
> > +fixes in released kernels, so do not assume that because a specific
> > +change does not have a CVE assigned to it, that it is not relevant to
> > +take.
> 
> There are a four "not" in the last pretty long sentence which makes it
> kinda hard to parse. Avoiding that could look like this:
> 
> Ideally CVEs will be assigned to all fixes for all issues -- but
> sometimes we will fail to notice fixes, therefore assume that some
> changes without an assigned CVE might still be relevant to take.
> 
> Or like this:
> 
> Ideally CVEs will be assigned to all fixes for all issues, but sometimes
> we will overlook fixes -- therefore assume that some changes that lack
> an assigned CVE might still be relevant to take.
> 
> Not sure if that really makes it better, I guess you as a native speaker
> are a better judge here.

I like the wording change here, thanks, I'll take it for the next
revision.  It is ackward as I wrote it and your update makes it simpler
and more obvious.

> Ciao, Thorsten (who also wondered what "to all fixes for all issues"
> exactly means, but whatever)

Meaning "we will miss things" so don't assume that because we don't call
it out here, it's not important to take.  Yeah, again, ackward wording,
language is "fun"...

thanks for the review!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 09:37:31AM +0100, Vegard Nossum wrote:
> 
> On 14/02/2024 09:00, Greg Kroah-Hartman wrote:
> > diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst
> > new file mode 100644
> > index 000000000000..6465e6a79c18
> > --- /dev/null
> > +++ b/Documentation/process/cve.rst
> > @@ -0,0 +1,120 @@
> > +CVEs
> > +====
> 
> Document titles should have ==== above them as well, and then you would
> need to shift all the other headings in this document (i.e. all the ---
> should become ===).
> 
> Info here: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation

Really?  I copied this directly from
Documentation/process/security-bugs.rst which is in the format that I
used here.  Which one is incorrect, I'm confused.

> > +The Linux kernel developer team does have the ability to assign CVEs for
> > +potential Linux kernel security issues.  This assignment is independent
> > +of the :doc:`normal Linux kernel security bug reporting
> > +process<../process/security_bugs>`.
> 
> These documents are both under process/ so it should be enough to say:
> 
> :doc:`[...] <security-bugs>`
> 
> In fact, when building the docs with your patch applied, I see:
> 
> Documentation/process/cve.rst:15: WARNING: unknown document:
> ./process/security_bugs
> Documentation/process/cve.rst:42: WARNING: unknown document:
> ./process/security_bugs


Odd, I would have thought that going back a directory and then into it
would work, as that's how filesystems normally are handled :)

In fact, again, security-bugs.rst has this very format, which is why I
used it, is it throwing that same warning?

> Note the hyphen vs. underscore (it should have a hyphen like my line above).

Ah, ick, nevermind, my fault, I thought I built this with it added, I'll
go fix this up and use the hyphen.

> 
> > +Process
> > +-------
> > +
> > +As part of the normal stable release process, kernel changes that are
> > +potentially security issues are identified by the developers responsible
> > +for CVE number assignments and have CVE numbers automatically assigned
> > +to them.  These assignments are published on the linux-cve-announce
> > +mailing list as announcements on a frequent basis.
> > +
> > +Note, due to the layer at which the Linux kernel is in a system, almost
> > +any bug might be exploitable to compromise the security of the kernel,
> > +but the possibility of exploitation is often not evident when the bug is
> > +fixed.  Because of this, the CVE assignment team is overly cautious and
> 
> What is the composition of the CVE assignment team, or is that secret?
> Should this be a MAINTAINERS entry? (s@k.org is one.)

Yeah, it should be a MAINTAINERS entry, I'll add that as part of the
next version of this patch.

As for the composition, it's not a "secret", but I'd prefer not to list
it individually here.  As per the signed-off-by on this patch it's Lee,
Sasha, and I for now, but I anticipate it will change over time, much
like s@k.o has.

> > +If the CVE assignment team misses a specific fix that any user feels
> > +should have a CVE assigned to it, please email them at <cve@kernel.org>
> > +and the team there will work with you on it.  Note that no potential
> > +security issues should be sent to this alias, it is ONLY for assignment
> > +of CVEs for fixes that are already in released kernel trees.  If you
> > +feel you have found an unfixed security issue, please follow the
> > +:doc:`normal Linux kernel security bug reporting
> > +process<../process/security_bugs>`.
> 
> Same

Thanks, will fix.

> > +Disputes of assigned CVEs
> > +-------------------------
> > +
> > +The authority to dispute or modify an assigned CVE for a specific kernel
> > +change lies solely with the maintainers of the relevant subsystem
> > +affected.  This principle ensures a high degree of accuracy and
> > +accountability in vulnerability reporting.  Only those individuals with
> > +deep expertise and intimate knowledge of the subsystem can effectively
> > +assess the validity and scope of a reported vulnerability and determine
> > +its appropriate CVE designation.  Any attempt to modify or dispute a CVE
> > +outside of this designated authority could lead to confusion, inaccurate
> > +reporting, and ultimately, compromised systems.
> 
> Just to clarify, I think "dispute" here is used in the
> Mitre/CVE-technical meaning of the word, correct? I assume people will
> still have the right to say "hey, this doesn't look like a real issue
> [because of X/Y/Z]" on a mailing list.

Yes, mailing list discussion is always good and encouraged and is what
is covered here as well.  There is the MITRE use of "dispute" as well,
and that too is allowed if needed, so this covers both paths.

> 
> > --- a/Documentation/process/security-bugs.rst
> > +++ b/Documentation/process/security-bugs.rst
> > @@ -99,9 +99,8 @@ CVE assignment
> >   The security team does not assign CVEs, nor do we require them for
> >   reports or fixes, as this can needlessly complicate the process and may
> >   delay the bug handling.  If a reporter wishes to have a CVE identifier
> > -assigned, they should find one by themselves, for example by contacting
> > -MITRE directly.  However under no circumstances will a patch inclusion
> > -be delayed to wait for a CVE identifier to arrive.
> > +assigned for a confirmed issue, they can contact the :doc:`kernel CVE
> > +assignment team<../process/cve>` to obtain one.
> 
> Same here, this could be just <cve>.

I'll keep it to match the other references in this file :)

many thanks for the review!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 08:41:26AM -0500, Konstantin Ryabitsev wrote:
> On Wed, Feb 14, 2024 at 09:00:30AM +0100, Greg Kroah-Hartman wrote:
> > +A list of all assigned CVEs for the Linux kernel can be found in the
> > +archives of the linux-cve mailing list, as seen on
> > +https://lore.kernel.org/linux-cve-announce/.  To get notice of the
> > +assigned CVEs, please subscribe to that mailing list.
> 
> Since the archives page doesn't carry any instructions on how to subscribe,
> I think you should link to https://subspace.kernel.org/subscribing.html here,
> e.g.:
> 
> .. please `subscribe <https://subspace.kernel.org/subscribing.html>`_ to that
> mailing list.
> 
> > +No CVEs will be assigned for any issue found in a version of the kernel
> > +that is not currently being actively supported by the Stable/LTS kernel
> > +team.  A list of the currently supported kernel branches can be found at
> > +https://kernel.org/category/releases.html
> 
> Can just be https://kernel.org/releases.html

Many thanks for the changes, now made!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 02:10:07PM +0100, Krzysztof Kozlowski wrote:
> On 14/02/2024 09:00, Greg Kroah-Hartman wrote:
> > The Linux kernel project now has the ability to assign CVEs to fixed
> > issues, so document the process and how individual developers can get a
> > CVE if one is not automatically assigned for their fixes.
> > 
> > Reviewed-by: Kees Cook <keescook@chromium.org>
> > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > Signed-off-by: Lee Jones <lee@kernel.org>
> > ---
> > v3: fix up wording in security-bugs.rst based on the changes to the cve
> >     assignment process from v1, thanks to a private reviewer for
> >     pointing that out.
> > v2: Grammer fixes based on review from Randy
> >     Updated paragraph about how CVE identifiers will be assigned
> >     (automatically when added to stable trees, or ask us for one
> >     directly before that happens if so desired)
> > 
> >  Documentation/process/cve.rst           | 120 ++++++++++++++++++++++++
> >  Documentation/process/index.rst         |   1 +
> >  Documentation/process/security-bugs.rst |   5 +-
> 
> Great direction! Finally all these bugs we are fixing every release
> (thus in stable trees) will get proper attention via assigned CVEs.
> 
> Reviewed-by: Krzysztof Kozlowski <krzk@kernel.org>

Thanks for the review!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Wed, Feb 14, 2024 at 09:34:38AM +0100, Lukas Bulwahn wrote:
> On Wed, Feb 14, 2024 at 9:01 AM Greg Kroah-Hartman
> <gregkh@linuxfoundation.org> wrote:
> >
> > The Linux kernel project now has the ability to assign CVEs to fixed
> > issues, so document the process and how individual developers can get a
> > CVE if one is not automatically assigned for their fixes.
> >
> > Reviewed-by: Kees Cook <keescook@chromium.org>
> > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > Signed-off-by: Lee Jones <lee@kernel.org>
> > ---
> > v3: fix up wording in security-bugs.rst based on the changes to the cve
> >     assignment process from v1, thanks to a private reviewer for
> >     pointing that out.
> > v2: Grammer fixes based on review from Randy
> >     Updated paragraph about how CVE identifiers will be assigned
> >     (automatically when added to stable trees, or ask us for one
> >     directly before that happens if so desired)
> >
> 
> Hi Greg, Sasha, Lee,
> 
> Generally, I think this is a great step forward on the whole "security
> vulnerability mess" and this will certainly help me and others in the
> embedded space to argue to update to recent stable kernel versions.
> This can then finally put the practice of shipping multiple-year-old
> kernel versions to an end. Often this was just done with the argument
> that there is not a recent CVE and fix assigned to some recent stable
> kernel version---and integrators think updates to recent kernel stable
> versions are not needed and not recommended.
> 
> I am looking forward to seeing what and how many stable commits are
> going to get CVEs assigned. If Greg's policy from the Kernel Recipes
> 2019 presentation comes into play, every git kernel hash (GKH)---at
> least in the stable tree---could get a CVE identifier (just to be on
> the safe side). But I assume you are going to use some expert
> knowledge, heuristics or some machine-learning AI to make some commits
> in the stable tree carrying a CVE identifier and some others not.

Yes, that "expert knowledge" will be "review all patches by hand" just
like we do today for all that are included in the stable trees.

> Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>

Thanks for the review.

> > +Common Vulnerabilities and Exposure (CVE®) numbers were developed as an
> > +unambiguous way to identify, define, and catalog publicly disclosed
> > +security vulnerabilities.  Over time, their usefulness has declined with
> > +regards to the kernel project, and CVE numbers were very often assigned
> > +in inappropriate ways and for inappropriate reasons.  Because of this,
> > +the kernel development community has tended to avoid them.  However, the
> > +combination of continuing pressure to assign CVEs and other forms of
> > +security identifiers, and ongoing abuses by community members outside of
> > +the kernel community has made it clear that the kernel community should
> > +have control over those assignments.
> > +
> 
> Though, I get what is meant with "the community members outside of the
> kernel community", it still feels strange when reading.
> 
> Here are some alternatives I could come up with:
> 
> "reporters outside the kernel community"
> "reporters beyond the actively contributing/engaged kernel community members"
> "individuals not engaged with the kernel community"

"community members" is a strange wording, you are right, I've replaced
it with "individuals and companies" as it has been both abusing the
system (and "individuals at companies", but that's just nit-picking...)

> > +The Linux kernel developer team does have the ability to assign CVEs for
> > +potential Linux kernel security issues.  This assignment is independent
> > +of the :doc:`normal Linux kernel security bug reporting
> > +process<../process/security_bugs>`.
> > +
> > +A list of all assigned CVEs for the Linux kernel can be found in the
> > +archives of the linux-cve mailing list, as seen on
> > +https://lore.kernel.org/linux-cve-announce/.  To get notice of the
> > +assigned CVEs, please subscribe to that mailing list.
> > +
> > +Process
> > +-------
> > +
> > +As part of the normal stable release process, kernel changes that are
> > +potentially security issues are identified by the developers responsible
> > +for CVE number assignments and have CVE numbers automatically assigned
> > +to them.  These assignments are published on the linux-cve-announce
> > +mailing list as announcements on a frequent basis.
> > +
> > +Note, due to the layer at which the Linux kernel is in a system, almost
> > +any bug might be exploitable to compromise the security of the kernel,
> 
> Just a nit: but I would say: a kernel bug is compromising the
> "security of the system"; the kernel bug just happens to allow anyone
> to run any code on their hardware... in some systems that is a
> security issue, but in my previous MSDOS system that was the default
> behaviour ;)

Good change, made, thanks!

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Vegard Nossum]

On 15/02/2024 12:50, Greg Kroah-Hartman wrote:
> On Wed, Feb 14, 2024 at 09:37:31AM +0100, Vegard Nossum wrote:
>>
>> On 14/02/2024 09:00, Greg Kroah-Hartman wrote:
>>> diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst
>>> new file mode 100644
>>> index 000000000000..6465e6a79c18
>>> --- /dev/null
>>> +++ b/Documentation/process/cve.rst
>>> @@ -0,0 +1,120 @@
>>> +CVEs
>>> +====
>>
>> Document titles should have ==== above them as well, and then you would
>> need to shift all the other headings in this document (i.e. all the ---
>> should become ===).
>>
>> Info here: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
> 
> Really?  I copied this directly from
> Documentation/process/security-bugs.rst which is in the format that I
> used here.  Which one is incorrect, I'm confused.

Documentation/ currently has a mix of both formats and they both work,
but the guidelines linked above is the gold standard and what we should
aim for in new documents.

The "correct" format would thus be:

====
CVEs
====

...

Process
=======

...

At least this is my understanding; I'm happy to be corrected (and in
this case, we should also update the documentation).

Thanks for your other clarifications.


Vegard

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Oleksandr Natalenko]

[-- Attachment #1: Type: text/plain, Size: 5735 bytes --]

Hello.

On čtvrtek 15. února 2024 13:04:56 CET Greg Kroah-Hartman wrote:
> On Wed, Feb 14, 2024 at 09:34:38AM +0100, Lukas Bulwahn wrote:
> > On Wed, Feb 14, 2024 at 9:01 AM Greg Kroah-Hartman
> > <gregkh@linuxfoundation.org> wrote:
> > >
> > > The Linux kernel project now has the ability to assign CVEs to fixed
> > > issues, so document the process and how individual developers can get a
> > > CVE if one is not automatically assigned for their fixes.
> > >
> > > Reviewed-by: Kees Cook <keescook@chromium.org>
> > > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > > Signed-off-by: Lee Jones <lee@kernel.org>
> > > ---
> > > v3: fix up wording in security-bugs.rst based on the changes to the cve
> > >     assignment process from v1, thanks to a private reviewer for
> > >     pointing that out.
> > > v2: Grammer fixes based on review from Randy
> > >     Updated paragraph about how CVE identifiers will be assigned
> > >     (automatically when added to stable trees, or ask us for one
> > >     directly before that happens if so desired)
> > >
> > 
> > Hi Greg, Sasha, Lee,
> > 
> > Generally, I think this is a great step forward on the whole "security
> > vulnerability mess" and this will certainly help me and others in the
> > embedded space to argue to update to recent stable kernel versions.
> > This can then finally put the practice of shipping multiple-year-old
> > kernel versions to an end. Often this was just done with the argument
> > that there is not a recent CVE and fix assigned to some recent stable
> > kernel version---and integrators think updates to recent kernel stable
> > versions are not needed and not recommended.
> > 
> > I am looking forward to seeing what and how many stable commits are
> > going to get CVEs assigned. If Greg's policy from the Kernel Recipes
> > 2019 presentation comes into play, every git kernel hash (GKH)---at
> > least in the stable tree---could get a CVE identifier (just to be on
> > the safe side). But I assume you are going to use some expert
> > knowledge, heuristics or some machine-learning AI to make some commits
> > in the stable tree carrying a CVE identifier and some others not.
> 
> Yes, that "expert knowledge" will be "review all patches by hand" just
> like we do today for all that are included in the stable trees.

Not undermining your efforts in any way, but I'd like to get an honest answer: is this really true? For instance,

$ git log --oneline v6.7.1..v6.7.2 | wc -l
641

Is it physically possible to actually review all these backports in just five days?

Thank you.

> 
> > Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> 
> Thanks for the review.
> 
> > > +Common Vulnerabilities and Exposure (CVE®) numbers were developed as an
> > > +unambiguous way to identify, define, and catalog publicly disclosed
> > > +security vulnerabilities.  Over time, their usefulness has declined with
> > > +regards to the kernel project, and CVE numbers were very often assigned
> > > +in inappropriate ways and for inappropriate reasons.  Because of this,
> > > +the kernel development community has tended to avoid them.  However, the
> > > +combination of continuing pressure to assign CVEs and other forms of
> > > +security identifiers, and ongoing abuses by community members outside of
> > > +the kernel community has made it clear that the kernel community should
> > > +have control over those assignments.
> > > +
> > 
> > Though, I get what is meant with "the community members outside of the
> > kernel community", it still feels strange when reading.
> > 
> > Here are some alternatives I could come up with:
> > 
> > "reporters outside the kernel community"
> > "reporters beyond the actively contributing/engaged kernel community members"
> > "individuals not engaged with the kernel community"
> 
> "community members" is a strange wording, you are right, I've replaced
> it with "individuals and companies" as it has been both abusing the
> system (and "individuals at companies", but that's just nit-picking...)
> 
> > > +The Linux kernel developer team does have the ability to assign CVEs for
> > > +potential Linux kernel security issues.  This assignment is independent
> > > +of the :doc:`normal Linux kernel security bug reporting
> > > +process<../process/security_bugs>`.
> > > +
> > > +A list of all assigned CVEs for the Linux kernel can be found in the
> > > +archives of the linux-cve mailing list, as seen on
> > > +https://lore.kernel.org/linux-cve-announce/.  To get notice of the
> > > +assigned CVEs, please subscribe to that mailing list.
> > > +
> > > +Process
> > > +-------
> > > +
> > > +As part of the normal stable release process, kernel changes that are
> > > +potentially security issues are identified by the developers responsible
> > > +for CVE number assignments and have CVE numbers automatically assigned
> > > +to them.  These assignments are published on the linux-cve-announce
> > > +mailing list as announcements on a frequent basis.
> > > +
> > > +Note, due to the layer at which the Linux kernel is in a system, almost
> > > +any bug might be exploitable to compromise the security of the kernel,
> > 
> > Just a nit: but I would say: a kernel bug is compromising the
> > "security of the system"; the kernel bug just happens to allow anyone
> > to run any code on their hardware... in some systems that is a
> > security issue, but in my previous MSDOS system that was the default
> > behaviour ;)
> 
> Good change, made, thanks!
> 
> greg k-h
> 
> 


-- 
Oleksandr Natalenko (post-factum)

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Thu, Feb 15, 2024 at 05:10:50PM +0100, Oleksandr Natalenko wrote:
> Hello.
> 
> On čtvrtek 15. února 2024 13:04:56 CET Greg Kroah-Hartman wrote:
> > On Wed, Feb 14, 2024 at 09:34:38AM +0100, Lukas Bulwahn wrote:
> > > On Wed, Feb 14, 2024 at 9:01 AM Greg Kroah-Hartman
> > > <gregkh@linuxfoundation.org> wrote:
> > > >
> > > > The Linux kernel project now has the ability to assign CVEs to fixed
> > > > issues, so document the process and how individual developers can get a
> > > > CVE if one is not automatically assigned for their fixes.
> > > >
> > > > Reviewed-by: Kees Cook <keescook@chromium.org>
> > > > Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > > Signed-off-by: Sasha Levin <sashal@kernel.org>
> > > > Signed-off-by: Lee Jones <lee@kernel.org>
> > > > ---
> > > > v3: fix up wording in security-bugs.rst based on the changes to the cve
> > > >     assignment process from v1, thanks to a private reviewer for
> > > >     pointing that out.
> > > > v2: Grammer fixes based on review from Randy
> > > >     Updated paragraph about how CVE identifiers will be assigned
> > > >     (automatically when added to stable trees, or ask us for one
> > > >     directly before that happens if so desired)
> > > >
> > > 
> > > Hi Greg, Sasha, Lee,
> > > 
> > > Generally, I think this is a great step forward on the whole "security
> > > vulnerability mess" and this will certainly help me and others in the
> > > embedded space to argue to update to recent stable kernel versions.
> > > This can then finally put the practice of shipping multiple-year-old
> > > kernel versions to an end. Often this was just done with the argument
> > > that there is not a recent CVE and fix assigned to some recent stable
> > > kernel version---and integrators think updates to recent kernel stable
> > > versions are not needed and not recommended.
> > > 
> > > I am looking forward to seeing what and how many stable commits are
> > > going to get CVEs assigned. If Greg's policy from the Kernel Recipes
> > > 2019 presentation comes into play, every git kernel hash (GKH)---at
> > > least in the stable tree---could get a CVE identifier (just to be on
> > > the safe side). But I assume you are going to use some expert
> > > knowledge, heuristics or some machine-learning AI to make some commits
> > > in the stable tree carrying a CVE identifier and some others not.
> > 
> > Yes, that "expert knowledge" will be "review all patches by hand" just
> > like we do today for all that are included in the stable trees.
> 
> Not undermining your efforts in any way, but I'd like to get an honest answer: is this really true? For instance,
> 
> $ git log --oneline v6.7.1..v6.7.2 | wc -l
> 641
> 
> Is it physically possible to actually review all these backports in just five days?

I did, yes.  And have been doing so for 15+ years, practice makes it
easier :)

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Michal Hocko]

On Wed 14-02-24 09:00:30, Greg KH wrote:
[...]
> +Process
> +-------
> +
> +As part of the normal stable release process, kernel changes that are
> +potentially security issues are identified by the developers responsible
> +for CVE number assignments and have CVE numbers automatically assigned
> +to them.  These assignments are published on the linux-cve-announce
> +mailing list as announcements on a frequent basis.
> +
> +Note, due to the layer at which the Linux kernel is in a system, almost
> +any bug might be exploitable to compromise the security of the kernel,
> +but the possibility of exploitation is often not evident when the bug is
> +fixed.  Because of this, the CVE assignment team is overly cautious and
> +assign CVE numbers to any bugfix that they identify.  This
> +explains the seemingly large number of CVEs that are issued by the Linux
> +kernel team.

Does the process focus only on assigning CVE numbers to a given upstream
commit(s) withou any specifics of the actual security threat covered by
the said CVE?
-- 
Michal Hocko
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Thu, Feb 15, 2024 at 06:54:17PM +0100, Michal Hocko wrote:
> On Wed 14-02-24 09:00:30, Greg KH wrote:
> [...]
> > +Process
> > +-------
> > +
> > +As part of the normal stable release process, kernel changes that are
> > +potentially security issues are identified by the developers responsible
> > +for CVE number assignments and have CVE numbers automatically assigned
> > +to them.  These assignments are published on the linux-cve-announce
> > +mailing list as announcements on a frequent basis.
> > +
> > +Note, due to the layer at which the Linux kernel is in a system, almost
> > +any bug might be exploitable to compromise the security of the kernel,
> > +but the possibility of exploitation is often not evident when the bug is
> > +fixed.  Because of this, the CVE assignment team is overly cautious and
> > +assign CVE numbers to any bugfix that they identify.  This
> > +explains the seemingly large number of CVEs that are issued by the Linux
> > +kernel team.
> 
> Does the process focus only on assigning CVE numbers to a given upstream
> commit(s) withou any specifics of the actual security threat covered by
> the said CVE?

Outside of the git commit text, no, we are not going to be adding
anything additional to the report, UNLESS someone wants to add
additional text to it, and then we will be glad to update a CVE entry
with the additional information.

Here's an example of what the CVE announcement is going to look like for
a "test" that we have been doing for our scripts
	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u

Note, I am NOT saying this is a valid CVE-like commit, I only chose it
because it is a type of entry that our tools need to handle properly
(one where the fix was for a commit that was only in a stable tree, and
mainline never saw the problem.)  There are many different "styles" of
fixes that we need to handle when it comes to version information.

It will also be in JSON format on the cve.org site if you wish to parse
it automatically with tools.  We are still working out the proper format
of the JSON entries of the version information and should hopefully have
an agreement of how to do this early next week, as the logic there isn't
exactly "simple".

If the announcement format needs additional work, please let us know.

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Michal Hocko]

On Thu 15-02-24 19:20:09, Greg KH wrote:
> On Thu, Feb 15, 2024 at 06:54:17PM +0100, Michal Hocko wrote:
> > On Wed 14-02-24 09:00:30, Greg KH wrote:
> > [...]
> > > +Process
> > > +-------
> > > +
> > > +As part of the normal stable release process, kernel changes that are
> > > +potentially security issues are identified by the developers responsible
> > > +for CVE number assignments and have CVE numbers automatically assigned
> > > +to them.  These assignments are published on the linux-cve-announce
> > > +mailing list as announcements on a frequent basis.
> > > +
> > > +Note, due to the layer at which the Linux kernel is in a system, almost
> > > +any bug might be exploitable to compromise the security of the kernel,
> > > +but the possibility of exploitation is often not evident when the bug is
> > > +fixed.  Because of this, the CVE assignment team is overly cautious and
> > > +assign CVE numbers to any bugfix that they identify.  This
> > > +explains the seemingly large number of CVEs that are issued by the Linux
> > > +kernel team.
> > 
> > Does the process focus only on assigning CVE numbers to a given upstream
> > commit(s) withou any specifics of the actual security threat covered by
> > the said CVE?
> 
> Outside of the git commit text, no, we are not going to be adding
> anything additional to the report, UNLESS someone wants to add
> additional text to it, and then we will be glad to update a CVE entry
> with the additional information.

OK, so what is the point of having CVE assigned to such a commit without
any addional information which is already referenced by the kernel sha?
What is the actual added value of that CVE?

> Here's an example of what the CVE announcement is going to look like for
> a "test" that we have been doing for our scripts
> 	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u

Thanks this gave me some idea. One worrying part is
: Please note that only supported kernel versions have fixes applied to
: them.  For a full list of currently supported kernel versions, please
: see https://www.kernel.org/

From the above it is not really clear "supported by _whom_". Because I
am pretty sure there are _fully_ supported kernels outside of that list
which are actively maintained.
-- 
Michal Hocko
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Kees Cook]

On Thu, Feb 15, 2024 at 07:20:09PM +0100, Greg Kroah-Hartman wrote:
> Here's an example of what the CVE announcement is going to look like for
> a "test" that we have been doing for our scripts
> 	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u
> ...
> the latest release is impossible, the individual change to resolve this
> issue can be found at:
> 	https://git.kernel.org/stable/linux/c/f08adf5add9a071160c68bb2a61d697f39ab0758

This is the "original fix", a v5.16 commit, which was backported to all
the stables. For this case, that seems fine (it's pretty easy to grep
the stable trees for the SHA).

In the case of a fix only being in -stable, what will be listed for
SHAs here? Each stable SHA? Something else?

-- 
Kees Cook

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Thu, Feb 15, 2024 at 11:40:43AM -0800, Kees Cook wrote:
> On Thu, Feb 15, 2024 at 07:20:09PM +0100, Greg Kroah-Hartman wrote:
> > Here's an example of what the CVE announcement is going to look like for
> > a "test" that we have been doing for our scripts
> > 	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u
> > ...
> > the latest release is impossible, the individual change to resolve this
> > issue can be found at:
> > 	https://git.kernel.org/stable/linux/c/f08adf5add9a071160c68bb2a61d697f39ab0758
> 
> This is the "original fix", a v5.16 commit, which was backported to all
> the stables. For this case, that seems fine (it's pretty easy to grep
> the stable trees for the SHA).
> 
> In the case of a fix only being in -stable, what will be listed for
> SHAs here? Each stable SHA? Something else?

I think listing all of the SHA values, stable and mainline, would be
best, right?  No need for everyone to try to grep the trees, and bonus,
the json format has a specific field just for this as well.  That's on
my todo list for today...

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jani Nikula]

On Thu, 15 Feb 2024, Vegard Nossum <vegard.nossum@oracle.com> wrote:
> On 15/02/2024 12:50, Greg Kroah-Hartman wrote:
>> On Wed, Feb 14, 2024 at 09:37:31AM +0100, Vegard Nossum wrote:
>>> Document titles should have ==== above them as well, and then you would
>>> need to shift all the other headings in this document (i.e. all the ---
>>> should become ===).
>>>
>>> Info here: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
>> 
>> Really?  I copied this directly from
>> Documentation/process/security-bugs.rst which is in the format that I
>> used here.  Which one is incorrect, I'm confused.
>
> Documentation/ currently has a mix of both formats and they both work,
> but the guidelines linked above is the gold standard and what we should
> aim for in new documents.
>
> The "correct" format would thus be:
>
> ====
> CVEs
> ====
>
> ...
>
> Process
> =======
>
> ...
>
> At least this is my understanding; I'm happy to be corrected (and in
> this case, we should also update the documentation).

rst basically allows any order of the heading underlines, and their
relative hierarchy is determined by how they show up in each document,
it's not specified by rst. However, it would be much easier for everyone
if all the kernel documents followed the same style.

BR,
Jani.


-- 
Jani Nikula, Intel

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
> On Thu, 15 Feb 2024, Vegard Nossum <vegard.nossum@oracle.com> wrote:
> > On 15/02/2024 12:50, Greg Kroah-Hartman wrote:
> >> On Wed, Feb 14, 2024 at 09:37:31AM +0100, Vegard Nossum wrote:
> >>> Document titles should have ==== above them as well, and then you would
> >>> need to shift all the other headings in this document (i.e. all the ---
> >>> should become ===).
> >>>
> >>> Info here: https://docs.kernel.org/doc-guide/sphinx.html#specific-guidelines-for-the-kernel-documentation
> >> 
> >> Really?  I copied this directly from
> >> Documentation/process/security-bugs.rst which is in the format that I
> >> used here.  Which one is incorrect, I'm confused.
> >
> > Documentation/ currently has a mix of both formats and they both work,
> > but the guidelines linked above is the gold standard and what we should
> > aim for in new documents.
> >
> > The "correct" format would thus be:
> >
> > ====
> > CVEs
> > ====
> >
> > ...
> >
> > Process
> > =======
> >
> > ...
> >
> > At least this is my understanding; I'm happy to be corrected (and in
> > this case, we should also update the documentation).
> 
> rst basically allows any order of the heading underlines, and their
> relative hierarchy is determined by how they show up in each document,
> it's not specified by rst. However, it would be much easier for everyone
> if all the kernel documents followed the same style.

Agreed, someone should pick a style and sweep the whole directory and
sync them up to the agreed formatting. :)

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Thu, Feb 15, 2024 at 07:36:20PM +0100, Michal Hocko wrote:
> On Thu 15-02-24 19:20:09, Greg KH wrote:
> > On Thu, Feb 15, 2024 at 06:54:17PM +0100, Michal Hocko wrote:
> > > On Wed 14-02-24 09:00:30, Greg KH wrote:
> > > [...]
> > > > +Process
> > > > +-------
> > > > +
> > > > +As part of the normal stable release process, kernel changes that are
> > > > +potentially security issues are identified by the developers responsible
> > > > +for CVE number assignments and have CVE numbers automatically assigned
> > > > +to them.  These assignments are published on the linux-cve-announce
> > > > +mailing list as announcements on a frequent basis.
> > > > +
> > > > +Note, due to the layer at which the Linux kernel is in a system, almost
> > > > +any bug might be exploitable to compromise the security of the kernel,
> > > > +but the possibility of exploitation is often not evident when the bug is
> > > > +fixed.  Because of this, the CVE assignment team is overly cautious and
> > > > +assign CVE numbers to any bugfix that they identify.  This
> > > > +explains the seemingly large number of CVEs that are issued by the Linux
> > > > +kernel team.
> > > 
> > > Does the process focus only on assigning CVE numbers to a given upstream
> > > commit(s) withou any specifics of the actual security threat covered by
> > > the said CVE?
> > 
> > Outside of the git commit text, no, we are not going to be adding
> > anything additional to the report, UNLESS someone wants to add
> > additional text to it, and then we will be glad to update a CVE entry
> > with the additional information.
> 
> OK, so what is the point of having CVE assigned to such a commit without
> any addional information which is already referenced by the kernel sha?
> What is the actual added value of that CVE?

It provides the proper signal to others that "hey, this is a
vulnerability that you might want to take if it affects you".  Right now
we are fixing lots and lots of things and no one notices as their
"traditional" path of only looking at CVEs for the kernel is totally
incorrect.

> > Here's an example of what the CVE announcement is going to look like for
> > a "test" that we have been doing for our scripts
> > 	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u
> 
> Thanks this gave me some idea. One worrying part is
> : Please note that only supported kernel versions have fixes applied to
> : them.  For a full list of currently supported kernel versions, please
> : see https://www.kernel.org/
> 
> >From the above it is not really clear "supported by _whom_". Because I
> am pretty sure there are _fully_ supported kernels outside of that list
> which are actively maintained.

Very true, how about this wording change:
	For a full list of currently supported kernel versions by the
	kernel developer community, please see https://www.kernel.org/

I added "by the kernel developer community", is that ok?

And as you're here, I have no objection to adding the vulnerable/fixes
info from various distros that are curently based on these same
kernel.org versions if you wish to provide them to me.  Give us a few
more days to nail down the version reporting format and then take a look
at it to see if you all can tie into that.

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Michal Hocko]

On Fri 16-02-24 12:25:46, Greg KH wrote:
> On Thu, Feb 15, 2024 at 07:36:20PM +0100, Michal Hocko wrote:
> > On Thu 15-02-24 19:20:09, Greg KH wrote:
> > > On Thu, Feb 15, 2024 at 06:54:17PM +0100, Michal Hocko wrote:
> > > > On Wed 14-02-24 09:00:30, Greg KH wrote:
> > > > [...]
> > > > > +Process
> > > > > +-------
> > > > > +
> > > > > +As part of the normal stable release process, kernel changes that are
> > > > > +potentially security issues are identified by the developers responsible
> > > > > +for CVE number assignments and have CVE numbers automatically assigned
> > > > > +to them.  These assignments are published on the linux-cve-announce
> > > > > +mailing list as announcements on a frequent basis.
> > > > > +
> > > > > +Note, due to the layer at which the Linux kernel is in a system, almost
> > > > > +any bug might be exploitable to compromise the security of the kernel,
> > > > > +but the possibility of exploitation is often not evident when the bug is
> > > > > +fixed.  Because of this, the CVE assignment team is overly cautious and
> > > > > +assign CVE numbers to any bugfix that they identify.  This
> > > > > +explains the seemingly large number of CVEs that are issued by the Linux
> > > > > +kernel team.
> > > > 
> > > > Does the process focus only on assigning CVE numbers to a given upstream
> > > > commit(s) withou any specifics of the actual security threat covered by
> > > > the said CVE?
> > > 
> > > Outside of the git commit text, no, we are not going to be adding
> > > anything additional to the report, UNLESS someone wants to add
> > > additional text to it, and then we will be glad to update a CVE entry
> > > with the additional information.
> > 
> > OK, so what is the point of having CVE assigned to such a commit without
> > any addional information which is already referenced by the kernel sha?
> > What is the actual added value of that CVE?
> 
> It provides the proper signal to others that "hey, this is a
> vulnerability that you might want to take if it affects you".

OK, but stating that something is a vulnerability fix requires a proper
analysis and this is a non trivial work. The wording here indicates that
most of the fixes will gain their CVE. The existing process really sucks
because there are just too many CVEs which really do not have any
security implications but it seems that the new process is not going to
address that because it will likely generate even more CVEs.

> Right now
> we are fixing lots and lots of things and no one notices as their
> "traditional" path of only looking at CVEs for the kernel is totally
> incorrect.

Right, there are quite a lot of people who consider CVE fixes much more
important than regular fixes. Their reasoning might be completely
misleading but there might be very good reasons to stick to minimalistic
approach, e.g. to reduce risk of regressions.

I believe it is perfectly fair to say that whoever relies on stable
kernels support needs to update to the latest stable kernel version to
be covered by security and functional fixes. On the other hand I do not
think it is an improvement to the process to swamp CVE database with any
random fixes without a proper evaluation. If the kernel community
doesn't believe in the CVE process then fair enough, just do not assign
them unless you want to explicitly call out fixes with a high impact
security implications. Having fewer good quality CVEs would definitely
improve the process.

> > > Here's an example of what the CVE announcement is going to look like for
> > > a "test" that we have been doing for our scripts
> > > 	https://lore.kernel.org/linux-cve-announce/2024021353-drainage-unstuffed-a7c0@gregkh/T/#u
> > 
> > Thanks this gave me some idea. One worrying part is
> > : Please note that only supported kernel versions have fixes applied to
> > : them.  For a full list of currently supported kernel versions, please
> > : see https://www.kernel.org/
> > 
> > >From the above it is not really clear "supported by _whom_". Because I
> > am pretty sure there are _fully_ supported kernels outside of that list
> > which are actively maintained.
> 
> Very true, how about this wording change:
> 	For a full list of currently supported kernel versions by the
> 	kernel developer community, please see https://www.kernel.org/
> 
> I added "by the kernel developer community", is that ok?

That sound much better!
 
> And as you're here, I have no objection to adding the vulnerable/fixes
> info from various distros that are curently based on these same
> kernel.org versions if you wish to provide them to me.

I cannot speak for distro kernels in general. I can tell you that we at
Suse do not base our product kernels on stable trees and we
carefully evaluate backports we commit to support. 
-- 
Michal Hocko
SUSE Labs

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Jonathan Corbet]

Greg Kroah-Hartman <gregkh@linuxfoundation.org> writes:

> On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
>> rst basically allows any order of the heading underlines, and their
>> relative hierarchy is determined by how they show up in each document,
>> it's not specified by rst. However, it would be much easier for everyone
>> if all the kernel documents followed the same style.
>
> Agreed, someone should pick a style and sweep the whole directory and
> sync them up to the agreed formatting. :)

Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)

jon

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Fri, Feb 16, 2024 at 02:20:04PM +0100, Michal Hocko wrote:
> > Right now
> > we are fixing lots and lots of things and no one notices as their
> > "traditional" path of only looking at CVEs for the kernel is totally
> > incorrect.
> 
> Right, there are quite a lot of people who consider CVE fixes much more
> important than regular fixes. Their reasoning might be completely
> misleading but there might be very good reasons to stick to minimalistic
> approach, e.g. to reduce risk of regressions.
> 
> I believe it is perfectly fair to say that whoever relies on stable
> kernels support needs to update to the latest stable kernel version to
> be covered by security and functional fixes. On the other hand I do not
> think it is an improvement to the process to swamp CVE database with any
> random fixes without a proper evaluation. If the kernel community
> doesn't believe in the CVE process then fair enough, just do not assign
> them unless you want to explicitly call out fixes with a high impact
> security implications. Having fewer good quality CVEs would definitely
> improve the process.

As you know, it's almost impossible to determine if a fix is "high
impact" or not, given that we have no idea what anyone's use case is for
the kernel.  We have documented proof of single-byte-buffer-overflows
resulting in complete system takeovers, and the same for very tiny
use-after-free issues, and the same for tiny "overflow a USB string
buffer" issues, and so on.

So as always, we need to treat "a bug is a bug is a bug" and when
looking at the bug fix, if it resolves something that is known to be
a vulnerability (again, as defined by CVE themselves), then we need to
mark it as such.

If you find that we are marking things as a CVE thatt you do not feel
should be marked as such, please let us know and we will be glad to
discuss it on a case-by-case basis.

But note, this type of classification has been happening for the kernel
stable commits for 2+ years now, by Sasha, in the GSD records, so this
isn't something new that we have been doing, it's just that only a very
small group were noticing that, and now a larger one might notice this.

thanks,

greg k-h

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Michal Hocko]

On Fri 16-02-24 16:34:57, Greg KH wrote:
> On Fri, Feb 16, 2024 at 02:20:04PM +0100, Michal Hocko wrote:
> > > Right now
> > > we are fixing lots and lots of things and no one notices as their
> > > "traditional" path of only looking at CVEs for the kernel is totally
> > > incorrect.
> > 
> > Right, there are quite a lot of people who consider CVE fixes much more
> > important than regular fixes. Their reasoning might be completely
> > misleading but there might be very good reasons to stick to minimalistic
> > approach, e.g. to reduce risk of regressions.
> > 
> > I believe it is perfectly fair to say that whoever relies on stable
> > kernels support needs to update to the latest stable kernel version to
> > be covered by security and functional fixes. On the other hand I do not
> > think it is an improvement to the process to swamp CVE database with any
> > random fixes without a proper evaluation. If the kernel community
> > doesn't believe in the CVE process then fair enough, just do not assign
> > them unless you want to explicitly call out fixes with a high impact
> > security implications. Having fewer good quality CVEs would definitely
> > improve the process.
> 
> As you know, it's almost impossible to determine if a fix is "high
> impact" or not, given that we have no idea what anyone's use case is for
> the kernel.  We have documented proof of single-byte-buffer-overflows
> resulting in complete system takeovers, and the same for very tiny
> use-after-free issues, and the same for tiny "overflow a USB string
> buffer" issues, and so on.

Right, generally speaking this is not an easy task. It requires a lot of
diligence actually. Sometimes there is no clear cut and that is _fine_.
The CVE system cannot ever be bullet proof and mark every single
security related fix (really you can be creating new security problems
just by backporting upstream fixes into stable trees).

But that is not really all that important, the main thing/question is
whether it can be _useful_. If you simply assign CVE to any fix in
stable you end up with thousands of CVEs and I really fail to see any
practical benefit from that. Well, unless you want to DoS the system and
its consumers. Who do you expect to be the user/consumer of those CVE
numbers? You have already said that community supported stable kernels
mandate the latest version to be used. Those users do not need to know
there is $BIG_NUMBER of CVEs in them.

If you want to mark a specific class of fixes with CVE because they are
known to be used for exploits then fine! That is something actually
useful. If you allow users to explicitly mark a fix as security relevant
because of XYZ argument then really great!

> So as always, we need to treat "a bug is a bug is a bug" and when
> looking at the bug fix, if it resolves something that is known to be
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> a vulnerability (again, as defined by CVE themselves), then we need to
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> mark it as such.

I am completely with you on that! That is quite far away from what the
documentation says AFAICS.
 
> If you find that we are marking things as a CVE thatt you do not feel
> should be marked as such, please let us know and we will be glad to
> discuss it on a case-by-case basis.

I've been through that exercise with the CVE process over years many
times. It has always been a pain because you were not talking to domain
experts who could evaluate the reasoning behind the dispute. I consider
the new process of a clearly defined dispute process a big improvement!
But if the real practice would be thousands of CVEs created for any
stable backport then this will DoS many existing CVE consumers.

All that being said. I do agree that taking control of CVEs and making
that kernel community thing is a good thing! But I really fail to
understand how increasing the number of CVEs by nominating all/most
stable fixes is going to help anybody or improve the existing process.

Thanks!
-- 
Michal Hocko
SUSE Labs

[RFC] doc headings sweep

[Vegard Nossum]

[-- Attachment #1: Type: text/plain, Size: 1626 bytes --]

On 16/02/2024 15:58, Jonathan Corbet wrote:
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> writes:
> 
>> On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
>>> rst basically allows any order of the heading underlines, and their
>>> relative hierarchy is determined by how they show up in each document,
>>> it's not specified by rst. However, it would be much easier for everyone
>>> if all the kernel documents followed the same style.
>>
>> Agreed, someone should pick a style and sweep the whole directory and
>> sync them up to the agreed formatting. :)
> 
> Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)

I have a (very long and ugly) script that can fix these up to a
consistent style, the attached patch is the result of running it on
Documentation/process/ only.

I've done builds before and after the patch and diffed the resulting
HTML files, they show no difference. (HOWEVER, you do need a 'make
cleandocs' in between, as it seems doing 'make htmldocs; find
Documentation | xargs touch; make htmldocs' is going to change the
generated HTML for the sidebar -- another issue to look into at some
point, I guess; maybe it's specific to the Sphinx version I used here,
4.3.2.)

The script will leave alone any file that it doesn't quite understand
(e.g. for a lot of the translations there are way more underlines than
characters in the heading and it doesn't match up with the byte count
either).

Anyway, the question is: Is this worth doing in the first place, or is
it just churn? I assume just after -rc1 would be the ideal time to
submit these to avoid conflicts.


Vegard

[-- Attachment #2: 0001-docs-process-make-reST-headings-consistent.patch --]
[-- Type: text/x-patch, Size: 68858 bytes --]

From e19b7143843b0935cb53f55e8a386f8bac230de6 Mon Sep 17 00:00:00 2001
From: Vegard Nossum <vegard.nossum@oracle.com>
Date: Fri, 16 Feb 2024 21:58:09 +0100
Subject: [PATCH] docs: process: make reST headings consistent

Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/process/1.Intro.rst             | 11 ++--
 Documentation/process/2.Process.rst           | 17 +++---
 Documentation/process/3.Early-stage.rst       | 11 ++--
 Documentation/process/5.Posting.rst           | 11 ++--
 Documentation/process/7.AdvancedTopics.rst    |  5 +-
 Documentation/process/8.Conclusion.rst        |  2 +
 Documentation/process/adding-syscalls.rst     | 29 +++++-----
 Documentation/process/applying-patches.rst    |  7 +--
 Documentation/process/botching-up-ioctls.rst  | 12 ++---
 Documentation/process/clang-format.rst        |  9 ++--
 .../code-of-conduct-interpretation.rst        |  9 ++--
 Documentation/process/code-of-conduct.rst     |  3 +-
 Documentation/process/deprecated.rst          | 22 ++++----
 Documentation/process/development-process.rst |  1 +
 .../process/handling-regressions.rst          |  3 +-
 Documentation/process/howto.rst               | 35 ++++++------
 Documentation/process/index.rst               | 12 ++---
 Documentation/process/kernel-docs.rst         |  9 ++--
 .../process/kernel-driver-statement.rst       |  3 +-
 .../process/kernel-enforcement-statement.rst  |  3 +-
 Documentation/process/license-rules.rst       |  7 +--
 Documentation/process/magic-number.rst        |  1 +
 .../process/maintainer-handbooks.rst          |  1 +
 Documentation/process/maintainer-kvm-x86.rst  | 51 +++++++++---------
 Documentation/process/maintainer-netdev.rst   | 54 +++++++++----------
 .../process/maintainer-soc-clean-dts.rst      |  4 +-
 Documentation/process/maintainer-soc.rst      | 14 ++---
 Documentation/process/management-style.rst    | 13 ++---
 .../process/programming-language.rst          |  5 +-
 .../process/researcher-guidelines.rst         |  3 +-
 Documentation/process/security-bugs.rst       | 11 ++--
 Documentation/process/submit-checklist.rst    |  3 +-
 .../process/volatile-considered-harmful.rst   |  3 +-
 33 files changed, 206 insertions(+), 178 deletions(-)

diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst
index c3d0270bbfb3..05f59d742823 100644
--- a/Documentation/process/1.Intro.rst
+++ b/Documentation/process/1.Intro.rst
@@ -1,10 +1,11 @@
 .. _development_process_intro:
 
+============
 Introduction
 ============
 
 Executive summary
------------------
+=================
 
 The rest of this section covers the scope of the kernel development process
 and the kinds of frustrations that developers and their employers can
@@ -48,7 +49,7 @@ managing patches with git and reviewing patches posted by others.
 for more information on kernel development.
 
 What this document is about
----------------------------
+===========================
 
 The Linux kernel, at over 8 million lines of code and well over 1000
 contributors to each release, is one of the largest and most active free
@@ -103,7 +104,7 @@ better; the following text should help you - or those who work for you -
 join our community.
 
 Credits
--------
+=======
 
 This document was written by Jonathan Corbet, corbet@lwn.net.  It has been
 improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
@@ -115,7 +116,7 @@ This work was supported by the Linux Foundation; thanks especially to
 Amanda McPherson, who saw the value of this effort and made it all happen.
 
 The importance of getting code into the mainline
-------------------------------------------------
+================================================
 
 Some companies and developers occasionally wonder why they should bother
 learning how to work with the kernel community and get their code into the
@@ -228,7 +229,7 @@ point, vendors whose code is in the mainline and well maintained will be
 much better positioned to get the new product ready for market quickly.
 
 Licensing
----------
+=========
 
 Code is contributed to the Linux kernel under a number of licenses, but all
 code must be compatible with version 2 of the GNU General Public License
diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
index 613a01da4717..d178c1b74514 100644
--- a/Documentation/process/2.Process.rst
+++ b/Documentation/process/2.Process.rst
@@ -1,5 +1,6 @@
 .. _development_process:
 
+=================================
 How the development process works
 =================================
 
@@ -11,7 +12,7 @@ processes to keep development happening smoothly.  A solid understanding of
 how the process works is required in order to be an effective part of it.
 
 The big picture
----------------
+===============
 
 The kernel developers use a loosely time-based release process, with a new
 major kernel release happening every two or three months.  The recent
@@ -138,7 +139,7 @@ release.
 
 
 The lifecycle of a patch
-------------------------
+========================
 
 Patches do not go directly from the developer's keyboard into the mainline
 kernel.  There is, instead, a somewhat involved (if somewhat informal)
@@ -207,7 +208,7 @@ step.  This approach invariably leads to frustration for everybody
 involved.
 
 How patches get into the Kernel
--------------------------------
+===============================
 
 There is exactly one person who can merge patches into the mainline kernel
 repository: Linus Torvalds. But, for example, of the over 9,500 patches
@@ -254,7 +255,7 @@ normally the right way to go.
 
 
 Next trees
-----------
+==========
 
 The chain of subsystem trees guides the flow of patches into the kernel,
 but it also raises an interesting question: what if somebody wants to look
@@ -307,7 +308,7 @@ their way into linux-next some time before the merge window opens.
 
 
 Staging trees
--------------
+=============
 
 The kernel source tree contains the drivers/staging/ directory, where
 many sub-directories for drivers or filesystems that are on their way to
@@ -336,7 +337,7 @@ a proper mainline driver.
 
 
 Tools
------
+=====
 
 As can be seen from the above text, the kernel development process depends
 heavily on the ability to herd collections of patches in various
@@ -383,7 +384,7 @@ quilt is the best tool for the job.
 
 
 Mailing lists
--------------
+=============
 
 A great deal of Linux kernel development work is done by way of mailing
 lists.  It is hard to be a fully-functioning member of the community
@@ -453,7 +454,7 @@ in the MAINTAINERS file packaged with the kernel source.
 
 
 Getting started with Kernel development
----------------------------------------
+=======================================
 
 Questions about how to get started with the kernel development process are
 common - from both individuals and companies.  Equally common are missteps
diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst
index 894a920041c6..57c9690f2f02 100644
--- a/Documentation/process/3.Early-stage.rst
+++ b/Documentation/process/3.Early-stage.rst
@@ -1,5 +1,6 @@
 .. _development_early_stage:
 
+====================
 Early-stage planning
 ====================
 
@@ -11,7 +12,7 @@ communication can save far more time later on.
 
 
 Specifying the problem
-----------------------
+======================
 
 Like any engineering project, a successful kernel enhancement starts with a
 clear description of the problem to be solved.  In some cases, this step is
@@ -69,7 +70,7 @@ Only then does it make sense to start considering possible solutions.
 
 
 Early discussion
-----------------
+================
 
 When planning a kernel development project, it makes great sense to hold
 discussions with the community before launching into implementation.  Early
@@ -123,7 +124,7 @@ avoided with some early discussion with the kernel developers.
 
 
 Who do you talk to?
--------------------
+===================
 
 When developers decide to take their plans public, the next question will
 be: where do we start?  The answer is to find the right mailing list(s) and
@@ -165,7 +166,7 @@ track down a maintainer for a specific piece of code.
 
 
 When to post?
--------------
+=============
 
 If possible, posting your plans during the early stages can only be
 helpful.  Describe the problem being solved and any plans that have been
@@ -190,7 +191,7 @@ community informed as you go.
 
 
 Getting official buy-in
------------------------
+=======================
 
 If your work is being done in a corporate environment - as most Linux
 kernel work is - you must, obviously, have permission from suitably
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index de4edd42d5c0..42a6a029c173 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -1,5 +1,6 @@
 .. _development_posting:
 
+===============
 Posting patches
 ===============
 
@@ -15,7 +16,7 @@ and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
 
 
 When to post
-------------
+============
 
 There is a constant temptation to avoid posting patches before they are
 completely "ready."  For simple patches, that is not a problem.  If the
@@ -32,7 +33,7 @@ with the idea that they can help you drive the work in the right direction.
 
 
 Before creating patches
------------------------
+=======================
 
 There are a number of things which should be done before you consider
 sending patches to the development community.  These include:
@@ -58,7 +59,7 @@ always pays back the effort in short order.
 
 
 Patch preparation
------------------
+=================
 
 The preparation of patches for posting can be a surprising amount of work,
 but, once again, attempting to save time here is not generally advisable
@@ -129,7 +130,7 @@ done.  When done properly, though, it is time well spent.
 
 
 Patch formatting and changelogs
--------------------------------
+===============================
 
 So now you have a perfect series of patches for posting, but the work is
 not done quite yet.  Each patch needs to be formatted into a message which
@@ -276,7 +277,7 @@ the bug was reported in private.
 
 
 Sending the patch
------------------
+=================
 
 Before you mail your patches, there are a couple of other things you should
 take care of:
diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst
index 43291704338e..9f0ec5bec15e 100644
--- a/Documentation/process/7.AdvancedTopics.rst
+++ b/Documentation/process/7.AdvancedTopics.rst
@@ -1,5 +1,6 @@
 .. _development_advancedtopics:
 
+===============
 Advanced topics
 ===============
 
@@ -9,7 +10,7 @@ number of topics which can be helpful for developers wanting to become a
 regular part of the Linux kernel development process.
 
 Managing patches with git
--------------------------
+=========================
 
 The use of distributed version control for the kernel began in early 2002,
 when Linus first started playing with the proprietary BitKeeper
@@ -149,7 +150,7 @@ sure that you have remembered to push those changes to the public server.
 .. _development_advancedtopics_reviews:
 
 Reviewing patches
------------------
+=================
 
 Some readers will certainly object to putting this section with "advanced
 topics" on the grounds that even beginning kernel developers should be
diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst
index 8c847dffe76b..593ee94c8ec1 100644
--- a/Documentation/process/8.Conclusion.rst
+++ b/Documentation/process/8.Conclusion.rst
@@ -1,5 +1,6 @@
 .. _development_conclusion:
 
+====================
 For more information
 ====================
 
@@ -49,6 +50,7 @@ Documentation for git can be found at:
 	https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
 
 
+==========
 Conclusion
 ==========
 
diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
index 906c47f1a9e5..00e6712a7e3d 100644
--- a/Documentation/process/adding-syscalls.rst
+++ b/Documentation/process/adding-syscalls.rst
@@ -1,6 +1,7 @@
 
 .. _addsyscalls:
 
+========================
 Adding a New System Call
 ========================
 
@@ -10,7 +11,7 @@ Linux kernel, over and above the normal submission advice in
 
 
 System Call Alternatives
-------------------------
+========================
 
 The first thing to consider when adding a new system call is whether one of
 the alternatives might be suitable instead.  Although system calls are the
@@ -52,7 +53,7 @@ interface.
 
 
 Designing the API: Planning for Extension
------------------------------------------
+=========================================
 
 A new system call forms part of the API of the kernel, and has to be supported
 indefinitely.  As such, it's a very good idea to explicitly discuss the
@@ -104,7 +105,7 @@ See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
 
 
 Designing the API: Other Considerations
----------------------------------------
+=======================================
 
 If your new system call allows userspace to refer to a kernel object, it
 should use a file descriptor as the handle for that object -- don't invent a
@@ -174,7 +175,7 @@ structure that's passed in by pointer.)
 
 
 Proposing the API
------------------
+=================
 
 To make new system calls easy to review, it's best to divide up the patchset
 into separate chunks.  These should include at least the following items as
@@ -194,7 +195,7 @@ be cc'ed to linux-api@vger.kernel.org.
 
 
 Generic System Call Implementation
-----------------------------------
+==================================
 
 The main entry point for your new :manpage:`xyzzy(2)` system call will be called
 ``sys_xyzzy()``, but you add this entry point with the appropriate
@@ -249,7 +250,7 @@ To summarize, you need a commit that includes:
 
 
 x86 System Call Implementation
-------------------------------
+==============================
 
 To wire up your new system call for x86 platforms, you need to update the
 master syscall tables.  Assuming your new system call isn't special in some
@@ -267,7 +268,7 @@ relevant merge window.
 
 
 Compatibility System Calls (Generic)
-------------------------------------
+====================================
 
 For most system calls the same 64-bit implementation can be invoked even when
 the userspace program is itself 32-bit; even if the system call's parameters
@@ -354,7 +355,7 @@ To summarize, you need:
 
 
 Compatibility System Calls (x86)
---------------------------------
+================================
 
 To wire up the x86 architecture of a system call with a compatibility version,
 the entries in the syscall tables need to be adjusted.
@@ -388,7 +389,7 @@ layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
 
 
 System Calls Returning Elsewhere
---------------------------------
+================================
 
 For most system calls, once the system call is complete the user program
 continues exactly where it left off -- at the next instruction, with the
@@ -438,7 +439,7 @@ simulates registers etc).  Fixing this is as simple as adding a #define to
 
 
 Other Details
--------------
+=============
 
 Most of the kernel treats system calls in a generic way, but there is the
 occasional exception that may need updating for your particular system call.
@@ -455,7 +456,7 @@ call to check there are no other special cases.
 
 
 Testing
--------
+=======
 
 A new system call should obviously be tested; it is also useful to provide
 reviewers with a demonstration of how user space programs will use the system
@@ -480,7 +481,7 @@ for filesystem-related changes.
 
 
 Man Page
---------
+========
 
 All new system calls should come with a complete man page, ideally using groff
 markup, but plain text will do.  If groff is used, it's helpful to include a
@@ -492,7 +493,7 @@ For more details, see https://www.kernel.org/doc/man-pages/patches.html
 
 
 Do not call System Calls in the Kernel
---------------------------------------
+======================================
 
 System calls are, as stated above, interaction points between userspace and
 the kernel.  Therefore, system call functions such as ``sys_xyzzy()`` or
@@ -523,7 +524,7 @@ architecture-specific compatibility wrappers, or other code in arch/.
 
 
 References and Sources
-----------------------
+======================
 
  - LWN article from Michael Kerrisk on use of flags argument in system calls:
    https://lwn.net/Articles/585415/
diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
index c269f5e1a0a3..11f5cbe4de39 100644
--- a/Documentation/process/applying-patches.rst
+++ b/Documentation/process/applying-patches.rst
@@ -1,7 +1,8 @@
 .. _applying_patches:
 
+====================================
 Applying Patches To The Linux Kernel
-++++++++++++++++++++++++++++++++++++
+====================================
 
 Original by:
 	Jesper Juhl, August 2005
@@ -316,7 +317,7 @@ The -stable team provides normal as well as incremental patches. Below is
 how to apply these patches.
 
 Normal patches
-~~~~~~~~~~~~~~
+--------------
 
 These patches are not incremental, meaning that for example the 5.7.3
 patch does not apply on top of the 5.7.2 kernel source, but rather on top
@@ -335,7 +336,7 @@ Here's a small example::
 	$ mv linux-5.7.2 linux-5.7.3	# rename the kernel source dir
 
 Incremental patches
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Incremental patches are different: instead of being applied on top
 of base 5.x kernel, they are applied on top of previous stable kernel
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index a05e8401de1c..44ab68408377 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -22,7 +22,7 @@ something every GPU driver has to do on its own.
 
 
 Prerequisites
--------------
+=============
 
 First the prerequisites. Without these you have already failed, because you
 will need to add a 32-bit compat layer:
@@ -50,7 +50,7 @@ will need to add a 32-bit compat layer:
 
 
 Basics
-------
+======
 
 With the joys of writing a compat layer avoided we can take a look at the basic
 fumbles. Neglecting these will make backward and forward compatibility a real
@@ -82,7 +82,7 @@ will have a second iteration or at least an extension for any given interface.
 
 
 Fun with Error Paths
---------------------
+====================
 
 Nowadays we don't have any excuse left any more for drm drivers being neat
 little root exploits. This means we both need full input validation and solid
@@ -125,7 +125,7 @@ anyway:
 
 
 Time, Waiting and Missing it
-----------------------------
+============================
 
 GPUs do most everything asynchronously, so we have a need to time operations and
 wait for outstanding ones. This is really tricky business; at the moment none of
@@ -166,7 +166,7 @@ still tons more lessons to learn here.
 
 
 Leaking Resources, Not
-----------------------
+======================
 
 A full-blown drm driver essentially implements a little OS, but specialized to
 the given GPU platforms. This means a driver needs to expose tons of handles
@@ -200,7 +200,7 @@ entails its own little set of pitfalls:
 
 
 Last, but not Least
--------------------
+===================
 
 Not every problem needs a new ioctl:
 
diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst
index 1d089a847c1b..2ced44df2277 100644
--- a/Documentation/process/clang-format.rst
+++ b/Documentation/process/clang-format.rst
@@ -1,5 +1,6 @@
 .. _clangformat:
 
+============
 clang-format
 ============
 
@@ -44,7 +45,7 @@ See more information about the tool at:
 .. _clangformatreview:
 
 Review files and patches for coding style
------------------------------------------
+=========================================
 
 By running the tool in its inline mode, you can review full subsystems,
 folders or individual files for code style mistakes, typos or improvements.
@@ -84,7 +85,7 @@ at least until we see if ``clang-format`` becomes commonplace.
 .. _clangformatreformat:
 
 Reformatting blocks of code
----------------------------
+===========================
 
 By using an integration with your text editor, you can reformat arbitrary
 blocks (selections) of code with a single keystroke. This is specially
@@ -111,7 +112,7 @@ so that you can tweak a few options. See clangformatextra_.
 .. _clangformatmissing:
 
 Missing support
----------------
+===============
 
 ``clang-format`` is missing support for some things that are common
 in kernel code. They are easy to remember, so if you use the tool
@@ -157,7 +158,7 @@ In particular, some very common ones you will notice are:
 .. _clangformatextra:
 
 Extra features/options
-----------------------
+======================
 
 Some features/style options are not enabled by default in the configuration
 file in order to minimize the differences between the output and the current
diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst
index 66b07f14714c..3abf86d261c6 100644
--- a/Documentation/process/code-of-conduct-interpretation.rst
+++ b/Documentation/process/code-of-conduct-interpretation.rst
@@ -1,5 +1,6 @@
 .. _code_of_conduct_interpretation:
 
+================================================================
 Linux Kernel Contributor Covenant Code of Conduct Interpretation
 ================================================================
 
@@ -22,7 +23,7 @@ system kernel ever, and we do not want to do anything to cause the
 quality of submission and eventual result to ever decrease.
 
 Maintainers
------------
+===========
 
 The Code of Conduct uses the term "maintainers" numerous times.  In the
 kernel community, a "maintainer" is anyone who is responsible for a
@@ -30,7 +31,7 @@ subsystem, driver, or file, and is listed in the MAINTAINERS file in the
 kernel source tree.
 
 Responsibilities
-----------------
+================
 
 The Code of Conduct mentions rights and responsibilities for
 maintainers, and this needs some further clarifications.
@@ -84,7 +85,7 @@ the Code of Conduct.  The kernel community is aware of that and provides
 entry level programs in various forms like kernelnewbies.org.
 
 Scope
------
+=====
 
 The Linux kernel community primarily interacts on a set of public email
 lists distributed around a number of different servers controlled by a
@@ -119,7 +120,7 @@ part of the user/kernel API, or reflect terminology used in published
 standards or specifications, are not considered bugs.
 
 Enforcement
------------
+===========
 
 The address listed in the Code of Conduct goes to the Code of Conduct
 Committee.  The exact members receiving these emails at any given time
diff --git a/Documentation/process/code-of-conduct.rst b/Documentation/process/code-of-conduct.rst
index be50294aebd5..17213ae2f6ee 100644
--- a/Documentation/process/code-of-conduct.rst
+++ b/Documentation/process/code-of-conduct.rst
@@ -1,7 +1,8 @@
 .. _code_of_conduct:
 
+====================================
 Contributor Covenant Code of Conduct
-++++++++++++++++++++++++++++++++++++
+====================================
 
 Our Pledge
 ==========
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 1f7f3e6c9cda..42c8a3f8d5f4 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -18,7 +18,7 @@ point when uses of deprecated things are proposed for inclusion in the
 kernel.
 
 __deprecated
-------------
+============
 While this attribute does visually mark an interface as deprecated,
 it `does not produce warnings during builds any more
 <https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
@@ -30,7 +30,7 @@ be fully removed from the kernel, or added to this file to discourage
 others from using them in the future.
 
 BUG() and BUG_ON()
-------------------
+==================
 Use WARN() and WARN_ON() instead, and handle the "impossible"
 error condition as gracefully as possible. While the BUG()-family
 of APIs were originally designed to act as an "impossible situation"
@@ -52,7 +52,7 @@ to make sure their systems do not continue running in the face of
 <https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
 
 open-coded arithmetic in allocator arguments
---------------------------------------------
+============================================
 Dynamic size calculations (especially multiplication) should not be
 performed in memory allocator (or similar) function arguments due to the
 risk of them overflowing. This could lead to values wrapping around and a
@@ -110,7 +110,7 @@ as well as the related check_mul_overflow(), check_add_overflow(),
 check_sub_overflow(), and check_shl_overflow() family of functions.
 
 simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
-----------------------------------------------------------------------
+======================================================================
 The simple_strtol(), simple_strtoll(),
 simple_strtoul(), and simple_strtoull() functions
 explicitly ignore overflows, which may lead to unexpected results
@@ -120,7 +120,7 @@ correct replacements, though note that those require the string to be
 NUL or newline terminated.
 
 strcpy()
---------
+========
 strcpy() performs no bounds checking on the destination buffer. This
 could result in linear overflows beyond the end of the buffer, leading to
 all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various
@@ -132,7 +132,7 @@ the destination, but rather a count of non-NUL bytes copied (or negative
 errno when it truncates).
 
 strncpy() on NUL-terminated strings
------------------------------------
+===================================
 Use of strncpy() does not guarantee that the destination buffer will
 be NUL terminated. This can lead to various linear read overflows and
 other misbehavior due to the missing termination. It also NUL-pads
@@ -154,7 +154,7 @@ attribute to avoid future compiler warnings. For cases still needing
 NUL-padding, strtomem_pad() can be used.
 
 strlcpy()
----------
+=========
 strlcpy() reads the entire source buffer first (since the return value
 is meant to match that of strlen()). This read may exceed the destination
 size limit. This is both inefficient and can lead to linear read overflows
@@ -163,7 +163,7 @@ though care must be given to any cases where the return value of strlcpy()
 is used, since strscpy() will return negative errno values when it truncates.
 
 %p format specifier
--------------------
+===================
 Traditionally, using "%p" in format strings would lead to regular address
 exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to
 be exploitable, all "%p" uses in the kernel are being printed as a hashed
@@ -187,7 +187,7 @@ you can temporarily boot with the debug flag "`no_hash_pointers
 <https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_".
 
 Variable Length Arrays (VLAs)
------------------------------
+=============================
 Using stack VLAs produces much worse machine code than statically
 sized stack arrays. While these non-trivial `performance issues
 <https://git.kernel.org/linus/02361bc77888>`_ are reason enough to
@@ -198,7 +198,7 @@ stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting
 memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
 
 Implicit switch case fall-through
----------------------------------
+=================================
 The C language allows switch cases to fall through to the next case
 when a "break" statement is missing at the end of a case. This, however,
 introduces ambiguity in the code, as it's not always clear if the missing
@@ -235,7 +235,7 @@ All switch/case blocks must end in one of:
 * return [expression];
 
 Zero-length and one-element arrays
-----------------------------------
+==================================
 There is a regular need in the kernel to provide a way to declare having
 a dynamically sized set of trailing elements in a structure. Kernel code
 should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_
diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst
index e34d7da58b7f..3d17099ce94f 100644
--- a/Documentation/process/development-process.rst
+++ b/Documentation/process/development-process.rst
@@ -1,5 +1,6 @@
 .. _development_process_main:
 
+=========================================
 A guide to the Kernel Development Process
 =========================================
 
diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 5d3c3de3f4ec..7854f5ebbb66 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -1,8 +1,9 @@
 .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
 .. See the bottom of this file for additional redistribution information.
 
+====================
 Handling regressions
-++++++++++++++++++++
+====================
 
 *We don't cause regressions* -- this document describes what this "first rule of
 Linux kernel development" means in practice for developers. It complements
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index eebda4910a88..1c4e370225b4 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -1,5 +1,6 @@
 .. _process_howto:
 
+=================================
 HOWTO do Linux kernel development
 =================================
 
@@ -15,7 +16,7 @@ document.
 
 
 Introduction
-------------
+============
 
 So, you want to learn how to become a Linux kernel developer?  Or you
 have been told by your manager, "Go write a Linux driver for this
@@ -57,7 +58,7 @@ of doing things.
 
 
 Legal Issues
-------------
+============
 
 The Linux kernel source code is released under the GPL.  Please see the file
 COPYING in the main directory of the source tree. The Linux kernel licensing
@@ -73,7 +74,7 @@ For common questions and answers about the GPL, please see:
 
 
 Documentation
--------------
+=============
 
 The Linux kernel source tree has a large range of documents that are
 invaluable for learning how to interact with the kernel community.  When
@@ -183,7 +184,7 @@ They can also be generated on LaTeX and ePub formats with::
 	make epubdocs
 
 Becoming A Kernel Developer
----------------------------
+===========================
 
 If you do not know anything about Linux kernel development, you should
 look at the Linux KernelNewbies project:
@@ -228,7 +229,7 @@ repository of the kernel code may be found at:
 
 
 The development process
------------------------
+=======================
 
 Linux kernel development process currently consists of a few different
 main kernel "branches" and lots of different subsystem-specific kernel
@@ -240,7 +241,7 @@ branches.  These different branches are:
   - linux-next integration testing tree
 
 Mainline tree
-~~~~~~~~~~~~~
+-------------
 
 The mainline tree is maintained by Linus Torvalds, and can be found at
 https://kernel.org or in the repo.  Its development process is as follows:
@@ -276,7 +277,7 @@ mailing list about kernel releases:
 	preconceived timeline."*
 
 Various stable trees with multiple major numbers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
 
 Kernels with 3-part versions are -stable kernels. They contain
 relatively small and critical fixes for security problems or significant
@@ -299,7 +300,7 @@ in the kernel tree documents what kinds of changes are acceptable for
 the -stable tree, and how the release process works.
 
 Subsystem-specific trees
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 The maintainers of the various kernel subsystems --- and also many
 kernel subsystem developers --- expose their current state of
@@ -324,7 +325,7 @@ accepted, or rejected.  Most of these patchwork sites are listed at
 https://patchwork.kernel.org/.
 
 linux-next integration testing tree
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 Before updates from subsystem trees are merged into the mainline tree,
 they need to be integration-tested.  For this purpose, a special
@@ -339,7 +340,7 @@ Adventurous testers are very welcome to runtime-test the linux-next.
 
 
 Bug Reporting
--------------
+=============
 
 The file 'Documentation/admin-guide/reporting-issues.rst' in the main kernel
 source directory describes how to report a possible kernel bug, and details
@@ -348,7 +349,7 @@ down the problem.
 
 
 Managing bug reports
---------------------
+====================
 
 One of the best ways to put into practice your hacking skills is by fixing
 bugs reported by other people. Not only will you help to make the kernel
@@ -367,7 +368,7 @@ kernel get filed there.
 
 
 Mailing lists
--------------
+=============
 
 As some of the above documents describe, the majority of the core kernel
 developers participate on the Linux Kernel Mailing list.  Details on how
@@ -426,7 +427,7 @@ Above all, please remember to show respect to other subscribers.
 
 
 Working with the community
---------------------------
+==========================
 
 The goal of the kernel community is to provide the best possible kernel
 there is.  When you submit a patch for acceptance, it will be reviewed
@@ -468,7 +469,7 @@ resend it.
 
 
 Differences between the kernel community and corporate structures
------------------------------------------------------------------
+=================================================================
 
 The kernel community works differently than most traditional corporate
 development environments.  Here are a list of things that you can try to
@@ -515,7 +516,7 @@ English before sending them.
 
 
 Break up your changes
----------------------
+=====================
 
 The Linux kernel community does not gladly accept large chunks of code
 dropped on it all at once.  The changes need to be properly introduced,
@@ -571,7 +572,7 @@ that are unfinished and will be "fixed up later."
 
 
 Justify your change
--------------------
+===================
 
 Along with breaking up your patches, it is very important for you to let
 the Linux community know why they should add this change.  New features
@@ -579,7 +580,7 @@ must be justified as being needed and useful.
 
 
 Document your change
---------------------
+====================
 
 When sending in your patches, pay special attention to what you say in
 the text in your email.  This information will become the ChangeLog
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 6cb732dfcc72..265ee20eb7dd 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -16,7 +16,7 @@ it much easier for you to get your changes merged with a minimum of
 trouble.
 
 An introduction to how kernel development works
------------------------------------------------
+===============================================
 
 Read these documents first: an understanding of the material here will ease
 your entry into the kernel community.
@@ -30,7 +30,7 @@ your entry into the kernel community.
    submit-checklist
 
 Tools and technical guides for kernel developers
-------------------------------------------------
+================================================
 
 This is a collection of material that kernel developers should be familiar
 with.
@@ -50,7 +50,7 @@ with.
    botching-up-ioctls
 
 Policy guides and developer statements
---------------------------------------
+======================================
 
 These are the rules that we try to live by in the kernel community (and
 beyond).
@@ -70,7 +70,7 @@ beyond).
    researcher-guidelines
 
 Dealing with bugs
------------------
+=================
 
 Bugs are a fact of life; it is important that we handle them properly.
 The documents below describe our policies around the handling of a couple
@@ -84,7 +84,7 @@ of special classes of bugs: regressions and security problems.
    embargoed-hardware-issues
 
 Maintainer information
-----------------------
+======================
 
 How to find the people who will accept your patches.
 
@@ -95,7 +95,7 @@ How to find the people who will accept your patches.
    maintainers
 
 Other material
---------------
+==============
 
 Here are some other guides to the community that are of interest to most
 developers:
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index 8660493b91d0..3d2874365ba0 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -1,5 +1,6 @@
 .. _kernel_docs:
 
+=====================================
 Index of Further Kernel Documentation
 =====================================
 
@@ -33,7 +34,7 @@ All documents are cataloged with the following fields: the document's
    the exception of foundational books.
 
 Docs at the Linux Kernel tree
------------------------------
+=============================
 
 The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
 
@@ -48,7 +49,7 @@ The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
         be more up to date than the web version.
 
 On-line docs
-------------
+============
 
     * Title: **Linux Kernel Mailing List Glossary**
 
@@ -73,7 +74,7 @@ On-line docs
         actively maintained at https://github.com/sysprog21/lkmpg.
 
 Published books
----------------
+===============
 
     * Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules**
 
@@ -150,7 +151,7 @@ Published books
       :Notes: Foundational book
 
 Miscellaneous
--------------
+=============
 
     * Name: **Cross-Referencing Linux**
 
diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst
index a849790a68bc..7746fdeaa0cb 100644
--- a/Documentation/process/kernel-driver-statement.rst
+++ b/Documentation/process/kernel-driver-statement.rst
@@ -1,7 +1,8 @@
 .. _process_statement_driver:
 
+=======================
 Kernel Driver Statement
------------------------
+=======================
 
 Position Statement on Linux Kernel Modules
 ==========================================
diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst
index dc2d813b2e79..5bda031af067 100644
--- a/Documentation/process/kernel-enforcement-statement.rst
+++ b/Documentation/process/kernel-enforcement-statement.rst
@@ -1,7 +1,8 @@
 .. _process_statement_kernel:
 
+==================================
 Linux Kernel Enforcement Statement
-----------------------------------
+==================================
 
 As developers of the Linux kernel, we have a keen interest in how our software
 is used and how the license for our software is enforced.  Compliance with the
diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst
index 2ef44ada3f11..8a773de46549 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -2,6 +2,7 @@
 
 .. _kernel_licensing:
 
+============================
 Linux kernel licensing rules
 ============================
 
@@ -56,7 +57,7 @@ The valid identifiers used in the kernel are explained in the section
 license list at https://spdx.org/licenses/ along with the license texts.
 
 License identifier syntax
--------------------------
+=========================
 
 1. Placement:
 
@@ -149,7 +150,7 @@ License identifier syntax
       // SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+
 
 License identifiers
--------------------
+===================
 
 The licenses currently used, as well as the licenses for code added to the
 kernel, can be broken down into:
@@ -423,7 +424,7 @@ and extract right from the source, which is recommended by various FOSS
 organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_.
 
 _`MODULE_LICENSE`
------------------
+=================
 
    Loadable kernel modules also require a MODULE_LICENSE() tag. This tag is
    neither a replacement for proper source code license information
diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst
index 7029c3c084ee..3237dcb9eedb 100644
--- a/Documentation/process/magic-number.rst
+++ b/Documentation/process/magic-number.rst
@@ -1,5 +1,6 @@
 .. _magicnumbers:
 
+===================
 Linux magic numbers
 ===================
 
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 976391cec528..00068032ed47 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -2,6 +2,7 @@
 
 .. _maintainer_handbooks_main:
 
+================================================================
 Subsystem and maintainer tree specific development process notes
 ================================================================
 
diff --git a/Documentation/process/maintainer-kvm-x86.rst b/Documentation/process/maintainer-kvm-x86.rst
index 9183bd449762..0e3271e9f054 100644
--- a/Documentation/process/maintainer-kvm-x86.rst
+++ b/Documentation/process/maintainer-kvm-x86.rst
@@ -1,10 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+=======
 KVM x86
 =======
 
 Foreword
---------
+========
 KVM strives to be a welcoming community; contributions from newcomers are
 valued and encouraged.  Please do not be discouraged or intimidated by the
 length of this document and the many rules/guidelines it contains.  Everyone
@@ -14,11 +15,11 @@ and learn from any mistakes you make, you will be welcomed with open arms, not
 torches and pitchforks.
 
 TL;DR
------
+=====
 Testing is mandatory.  Be consistent with established styles and patterns.
 
 Trees
------
+=====
 KVM x86 is currently in a transition period from being part of the main KVM
 tree, to being "just another KVM arch".  As such, KVM x86 is split across the
 main KVM tree, ``git.kernel.org/pub/scm/virt/kvm/kvm.git``, and a KVM x86
@@ -34,7 +35,7 @@ Note, this transition period is expected to last quite some time, i.e. will be
 the status quo for the foreseeable future.
 
 Branches
-~~~~~~~~
+--------
 The KVM x86 tree is organized into multiple topic branches.  The purpose of
 using finer-grained topic branches is to make it easier to keep tabs on an area
 of development, and to limit the collateral damage of human errors and/or buggy
@@ -47,7 +48,7 @@ via a Cthulhu merge on an as-needed basis, i.e. when a topic branch is updated.
 As a result, force pushes to ``next`` are common.
 
 Lifecycle
-~~~~~~~~~
+---------
 Fixes that target the current release, a.k.a. mainline, are typically applied
 directly to the main KVM tree, i.e. do not route through the KVM x86 tree.
 
@@ -62,7 +63,7 @@ close around rc5 for new features, and a soft close around rc6 for fixes (for
 the next release; see above for fixes that target the current release).
 
 Timeline
-~~~~~~~~
+--------
 Submissions are typically reviewed and applied in FIFO order, with some wiggle
 room for the size of a series, patches that are "cache hot", etc.  Fixes,
 especially for the current release and or stable trees, get to jump the queue.
@@ -80,10 +81,10 @@ can, within reason, to ensure that your patches are ready to be merged!  Pings
 on series that break the build or fail tests lead to unhappy maintainers!
 
 Development
------------
+===========
 
 Base Tree/Branch
-~~~~~~~~~~~~~~~~
+----------------
 Fixes that target the current release, a.k.a. mainline, should be based on
 ``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``.  Note, fixes do not
 automatically warrant inclusion in the current release.  There is no singular
@@ -104,7 +105,7 @@ you're unsure whether a patch/series is truly multi-arch, err on the side of
 caution and treat it as multi-arch, i.e. use a common base.
 
 Coding Style
-~~~~~~~~~~~~
+------------
 When it comes to style, naming, patterns, etc., consistency is the number one
 priority in KVM x86.  If all else fails, match what already exists.
 
@@ -121,14 +122,14 @@ they are intended only for KVM-internal consumption (there are plans to
 privatize KVM's headers and exports to enforce this).
 
 Comments
-~~~~~~~~
+--------
 Write comments using imperative mood and avoid pronouns.  Use comments to
 provide a high level overview of the code, and/or to explain why the code does
 what it does.  Do not reiterate what the code literally does; let the code
 speak for itself.  If the code itself is inscrutable, comments will not help.
 
 SDM and APM References
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 Much of KVM's code base is directly tied to architectural behavior defined in
 Intel's Software Development Manual (SDM) and AMD's Architecture Programmer’s
 Manual (APM).  Use of "Intel's SDM" and "AMD's APM", or even just "SDM" or
@@ -146,7 +147,7 @@ Note, referencing the SDM/APM in changelogs to justify the change and provide
 context is perfectly ok and encouraged.
 
 Shortlog
-~~~~~~~~
+--------
 The preferred prefix format is ``KVM: <topic>:``, where ``<topic>`` is one of::
 
   - x86
@@ -191,7 +192,7 @@ limit.  I.e. let the shortlog run a few characters over the standard limit if
 you have good reason to do so.
 
 Changelog
-~~~~~~~~~
+---------
 Most importantly, write changelogs using imperative mood and avoid pronouns.
 
 See :ref:`describe_changes` for more information, with one amendment: lead with
@@ -224,7 +225,7 @@ preference.  E.g. having to skip one sentence to get to the context is less
 painful than having to skip three paragraphs to get to "what's changing".
 
 Fixes
-~~~~~
+-----
 If a change fixes a KVM/kernel bug, add a Fixes: tag even if the change doesn't
 need to be backported to stable kernels, and even if the change fixes a bug in
 an older release.
@@ -235,13 +236,13 @@ KVM x86 opts out of backporting Fixes: by default.  Some auto-selected patches
 do get backported, but require explicit maintainer approval (search MANUALSEL).
 
 Function References
-~~~~~~~~~~~~~~~~~~~
+-------------------
 When a function is mentioned in a comment, changelog, or shortlog (or anywhere
 for that matter), use the format ``function_name()``.  The parentheses provide
 context and disambiguate the reference.
 
 Testing
--------
+=======
 At a bare minimum, *all* patches in a series must build cleanly for KVM_INTEL=m
 KVM_AMD=m, and KVM_WERROR=y.  Building every possible combination of Kconfigs
 isn't feasible, but the more the merrier.  KVM_SMM, KVM_XEN, PROVE_LOCKING, and
@@ -270,7 +271,7 @@ If you can't fully test a change, e.g. due to lack of hardware, clearly state
 what level of testing you were able to do, e.g. in the cover letter.
 
 New Features
-~~~~~~~~~~~~
+------------
 With one exception, new features *must* come with test coverage.  KVM specific
 tests aren't strictly required, e.g. if coverage is provided by running a
 sufficiently enabled guest VM, or by running a related kernel selftest in a VM,
@@ -292,7 +293,7 @@ should clearly state what type of feedback is requested/expected.  Do not abuse
 the RFC process; RFCs will typically not receive in-depth review.
 
 Bug Fixes
-~~~~~~~~~
+---------
 Except for "obvious" found-by-inspection bugs, fixes must be accompanied by a
 reproducer for the bug being fixed.  In many cases the reproducer is implicit,
 e.g. for build errors and test failures, but it should still be clear to
@@ -310,10 +311,10 @@ if a bug is really truly the end of the world before posting a fix without a
 reproducer.
 
 Posting
--------
+=======
 
 Links
-~~~~~
+-----
 Do not explicitly reference bug reports, prior versions of a patch/series, etc.
 via ``In-Reply-To:`` headers.  Using ``In-Reply-To:`` becomes an unholy mess
 for large series and/or when the version count gets high, and ``In-Reply-To:``
@@ -329,7 +330,7 @@ formal Link: for bug reports and/or discussions that led to the patch.  The
 context of why a change was made is highly valuable for future readers.
 
 Git Base
-~~~~~~~~
+--------
 If you are using git version 2.9.0 or later (Googlers, this is all of you!),
 use ``git format-patch`` with the ``--base`` flag to automatically include the
 base tree information in the generated patches.
@@ -344,7 +345,7 @@ to yield ``--base=x/pmu``, where ``x`` is whatever name your repository uses to
 track the KVM x86 remote.
 
 Co-Posting Tests
-~~~~~~~~~~~~~~~~
+----------------
 KVM selftests that are associated with KVM changes, e.g. regression tests for
 bug fixes, should be posted along with the KVM changes as a single series.  The
 standard kernel rules for bisection apply, i.e. KVM changes that result in test
@@ -358,7 +359,7 @@ KVM patches, first post the KVM changes and then provide a lore Link: to the
 KVM patch/series in the KVM-unit-tests patch(es).
 
 Notifications
--------------
+=============
 When a patch/series is officially accepted, a notification email will be sent
 in reply to the original posting (cover letter for multi-patch series).  The
 notification will include the tree and topic branch, along with the SHA1s of
@@ -374,7 +375,7 @@ will be sent to the notification email explaining why the patch was dropped, as
 well as the next steps.
 
 SHA1 Stability
-~~~~~~~~~~~~~~
+--------------
 SHA1s are not 100% guaranteed to be stable until they land in Linus' tree!  A
 SHA1 is *usually* stable once a notification has been sent, but things happen.
 In most cases, an update to the notification email be provided if an applied
@@ -382,7 +383,7 @@ patch's SHA1 changes.  However, in some scenarios, e.g. if all KVM x86 branches
 need to be rebased, individual notifications will not be given.
 
 Vulnerabilities
----------------
+===============
 Bugs that can be exploited by the guest to attack the host (kernel or
 userspace), or that can be exploited by a nested VM to *its* host (L2 attacking
 L1), are of particular interest to KVM.  Please follow the protocol for
diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 84ee60fceef2..6092d403e8b2 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -7,7 +7,7 @@ Networking subsystem (netdev)
 =============================
 
 tl;dr
------
+=====
 
  - designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
  - for fixes the ``Fixes:`` tag is required, regardless of the tree
@@ -16,7 +16,7 @@ tl;dr
  - reverse xmas tree
 
 netdev
-------
+======
 
 netdev is a mailing list for all network-related Linux stuff.  This
 includes anything found under net/ (i.e. core code like IPv6) and
@@ -34,7 +34,7 @@ Linux development (i.e. RFC, review, comments, etc.) takes place on
 netdev.
 
 Development cycle
------------------
+=================
 
 Here is a bit of background information on
 the cadence of Linux development.  Each new release starts off with a
@@ -60,7 +60,7 @@ probably imminent. If the most recent tag is a final release tag
 and ``net-next`` is closed.
 
 git trees and patch flow
-------------------------
+========================
 
 There are two networking trees (git repositories) in play.  Both are
 driven by David Miller, the main network maintainer.  There is the
@@ -107,12 +107,12 @@ focus for ``net`` is on stabilization and bug fixes.
 Finally, the vX.Y gets released, and the whole cycle starts over.
 
 netdev patch review
--------------------
+===================
 
 .. _patch_status:
 
 Patch status
-~~~~~~~~~~~~
+------------
 
 Status of a patch can be checked by looking at the main patchwork
 queue for netdev:
@@ -155,7 +155,7 @@ which carried them so if you have trouble finding your patch append
 the value of ``Message-ID`` to the URL above.
 
 Updating patch status
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Contributors and reviewers do not have the permissions to update patch
 state directly in patchwork. Patchwork doesn't expose much information
@@ -188,7 +188,7 @@ Bot records its activity here:
   https://netdev.bots.linux.dev/pw-bot.html
 
 Review timelines
-~~~~~~~~~~~~~~~~
+----------------
 
 Generally speaking, the patches get triaged quickly (in less than
 48h). But be patient, if your patch is active in patchwork (i.e. it's
@@ -214,7 +214,7 @@ landed - describe your best guess and ask if it's correct. For example::
 .. _Changes requested:
 
 Changes requested
-~~~~~~~~~~~~~~~~~
+-----------------
 
 Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
 to be revised. The new version should come with a change log,
@@ -241,14 +241,14 @@ had to ask in previous discussions. Occasionally the update of
 the commit message will be the only change in the new version.
 
 Partial resends
-~~~~~~~~~~~~~~~
+---------------
 
 Please always resend the entire patch series and make sure you do number your
 patches such that it is clear this is the latest and greatest set of patches
 that can be applied. Do not try to resend just the patches which changed.
 
 Handling misapplied patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Occasionally a patch series gets applied before receiving critical feedback,
 or the wrong version of a series gets applied.
@@ -265,7 +265,7 @@ problems with the reverted commit. Reverts should be used as a last resort,
 when original change is completely wrong; incremental fixes are preferred.
 
 Stable tree
-~~~~~~~~~~~
+-----------
 
 While it used to be the case that netdev submissions were not supposed
 to carry explicit ``CC: stable@vger.kernel.org`` tags that is no longer
@@ -274,7 +274,7 @@ the case today. Please follow the standard stable rules in
 and make sure you include appropriate Fixes tags!
 
 Security fixes
-~~~~~~~~~~~~~~
+--------------
 
 Do not email netdev maintainers directly if you think you discovered
 a bug that might have possible security implications.
@@ -286,7 +286,7 @@ as possible alternative mechanisms.
 
 
 Co-posting changes to user space components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 User space code exercising kernel features should be posted
 alongside kernel patches. This gives reviewers a chance to see
@@ -313,7 +313,7 @@ Posting as one thread is discouraged because it confuses patchwork
 (as of patchwork 2.2.2).
 
 Preparing changes
------------------
+=================
 
 Attention to detail is important.  Re-read your own work as if you were the
 reviewer.  You can start with using ``checkpatch.pl``, perhaps even with
@@ -331,7 +331,7 @@ Finally, go back and read
 to be sure you are not repeating some common mistake documented there.
 
 Indicating target tree
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 To help maintainers and CI bots you should explicitly mark which tree
 your patch is targeting. Assuming that you use git, use the prefix
@@ -343,7 +343,7 @@ Use ``net`` instead of ``net-next`` (always lower case) in the above for
 bug-fix ``net`` content.
 
 Dividing work into patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Put yourself in the shoes of the reviewer. Each patch is read separately
 and therefore should constitute a comprehensible step towards your stated
@@ -357,7 +357,7 @@ with better review coverage. Re-posting large series also increases the mailing
 list traffic.
 
 Multi-line comments
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 Comment style convention is slightly different for networking and most of
 the tree.  Instead of this::
@@ -374,7 +374,7 @@ it is requested that you make it look like this::
    */
 
 Local variable ordering ("reverse xmas tree", "RCS")
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
 
 Netdev has a convention for ordering local variables in functions.
 Order the variable declaration lines longest to shortest, e.g.::
@@ -387,14 +387,14 @@ If there are dependencies between the variables preventing the ordering
 move the initialization out of line.
 
 Format precedence
-~~~~~~~~~~~~~~~~~
+-----------------
 
 When working in existing code which uses nonstandard formatting make
 your code follow the most recent guidelines, so that eventually all code
 in the domain of netdev is in the preferred format.
 
 Resending after review
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 Allow at least 24 hours to pass between postings. This will ensure reviewers
 from all geographical locations have a chance to chime in. Do not wait
@@ -410,10 +410,10 @@ not as a reply to the previous posting. Change log should include a link
 to the previous posting (see :ref:`Changes requested`).
 
 Testing
--------
+=======
 
 Expected level of testing
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
 
 At the very minimum your changes must survive an ``allyesconfig`` and an
 ``allmodconfig`` build with ``W=1`` set without new warnings or failures.
@@ -426,7 +426,7 @@ You are expected to test your changes on top of the relevant networking
 tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
 
 patchwork checks
-~~~~~~~~~~~~~~~~
+----------------
 
 Checks in patchwork are mostly simple wrappers around existing kernel
 scripts, the sources are available at:
@@ -440,7 +440,7 @@ gets overloaded very easily and netdev@vger really doesn't need more
 traffic if we can help it.
 
 netdevsim
-~~~~~~~~~
+---------
 
 ``netdevsim`` is a test driver which can be used to exercise driver
 configuration APIs without requiring capable hardware.
@@ -456,7 +456,7 @@ new ``netdevsim`` features must be accompanied by selftests under
 ``tools/testing/selftests/``.
 
 Reviewer guidance
------------------
+=================
 
 Reviewing other people's patches on the list is highly encouraged,
 regardless of the level of expertise. For general guidance and
@@ -471,7 +471,7 @@ review of submissions and not focus exclusively on trivial or subjective
 matters like code formatting, tags etc.
 
 Testimonials / feedback
------------------------
+=======================
 
 Some companies use peer feedback in employee performance reviews.
 Please feel free to request feedback from netdev maintainers,
diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
index 1b32430d0cfc..c9b7824d00f2 100644
--- a/Documentation/process/maintainer-soc-clean-dts.rst
+++ b/Documentation/process/maintainer-soc-clean-dts.rst
@@ -5,14 +5,14 @@ SoC Platforms with DTS Compliance Requirements
 ==============================================
 
 Overview
---------
+========
 
 SoC platforms or subarchitectures should follow all the rules from
 Documentation/process/maintainer-soc.rst.  This document referenced in
 MAINTAINERS impose additional requirements listed below.
 
 Strict DTS DT Schema and dtc Compliance
----------------------------------------
+=======================================
 
 No changes to the SoC platform Devicetree sources (DTS files) should introduce
 new ``make dtbs_check W=1`` warnings.  Warnings in a new board DTS, which are
diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst
index 12637530d68f..9e953ce0dae4 100644
--- a/Documentation/process/maintainer-soc.rst
+++ b/Documentation/process/maintainer-soc.rst
@@ -5,7 +5,7 @@ SoC Subsystem
 =============
 
 Overview
---------
+========
 
 The SoC subsystem is a place of aggregation for SoC-specific code.
 The main components of the subsystem are:
@@ -52,14 +52,14 @@ changes.  Each architecture has its own maintainers that are responsible for
 architectural details, CPU errata and the like.
 
 Information for (new) Submaintainers
-------------------------------------
+====================================
 
 As new platforms spring up, they often bring with them new submaintainers,
 many of whom work for the silicon vendor, and may not be familiar with the
 process.
 
 Devicetree ABI Stability
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 Perhaps one of the most important things to highlight is that dt-bindings
 document the ABI between the devicetree and the kernel.
@@ -73,7 +73,7 @@ expected impact on existing users, such as bootloaders or other operating
 systems.
 
 Driver Branch Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 A common problem is synchronizing changes between device drivers and devicetree
 files. Even if a change is compatible in both directions, this may require
@@ -106,7 +106,7 @@ There are multiple ways to deal with this:
   removing them in a later release
 
 Devicetree Naming Convention
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 The general naming scheme for devicetree files is as follows.  The aspects of a
 platform that are set at the SoC level, like CPU cores, are contained in a file
@@ -125,7 +125,7 @@ Directories are usually named after the vendor of the SoC at the time of its
 inclusion, leading to some historical directory names in the tree.
 
 Validating Devicetree Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 ``make dtbs_check`` can be used to validate that devicetree files are compliant
 with the dt-bindings that describe the ABI.  Please read the section
@@ -139,7 +139,7 @@ If in any doubt about a devicetree change, reach out to the devicetree
 maintainers.
 
 Branches and Pull Requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Just as the main SoC tree has several branches, it is expected that
 submaintainers will do the same. Driver, defconfig and devicetree changes should
diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst
index dfbc69bf49d4..7e112e0f166c 100644
--- a/Documentation/process/management-style.rst
+++ b/Documentation/process/management-style.rst
@@ -1,5 +1,6 @@
 .. _managementstyle:
 
+=============================
 Linux kernel management style
 =============================
 
@@ -32,7 +33,7 @@ Anyway, here goes:
 .. _decisions:
 
 1) Decisions
-------------
+============
 
 Everybody thinks managers make decisions, and that decision-making is
 important.  The bigger and more painful the decision, the bigger the
@@ -134,7 +135,7 @@ have screwed up on.
 
 
 2) People
----------
+=========
 
 Most people are idiots, and being a manager means you'll have to deal
 with it, and perhaps more importantly, that **they** have to deal with
@@ -181,7 +182,7 @@ trust somebody who is so clearly hiding their true character.
 
 
 3) People II - the Good Kind
-----------------------------
+============================
 
 While it turns out that most people are idiots, the corollary to that is
 sadly that you are one too, and that while we can all bask in the secure
@@ -214,7 +215,7 @@ direction, just don't push too hard.
 
 
 4) Placing blame
-----------------
+================
 
 Things will go wrong, and people want somebody to blame. Tag, you're it.
 
@@ -240,7 +241,7 @@ by now.
 
 
 5) Things to avoid
-------------------
+==================
 
 There's one thing people hate even more than being called "d*ckhead",
 and that is being called a "d*ckhead" in a sanctimonious voice.  The
@@ -273,7 +274,7 @@ have about criticism.
 
 
 6) Why me?
-----------
+==========
 
 Since your main responsibility seems to be to take the blame for other
 peoples mistakes, and make it painfully obvious to everybody else that
diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
index bc56dee6d0bc..2afa9409fe5a 100644
--- a/Documentation/process/programming-language.rst
+++ b/Documentation/process/programming-language.rst
@@ -1,5 +1,6 @@
 .. _programming_language:
 
+====================
 Programming Language
 ====================
 
@@ -13,7 +14,7 @@ This dialect contains many extensions to the language [gnu-extensions]_,
 and many of them are used within the kernel as a matter of course.
 
 Attributes
-----------
+==========
 
 One of the common extensions used throughout the kernel are attributes
 [gcc-attribute-syntax]_. Attributes allow to introduce
@@ -32,7 +33,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
 Please refer to ``include/linux/compiler_attributes.h`` for more information.
 
 Rust
-----
+====
 
 The kernel has experimental support for the Rust programming language
 [rust-language]_ under ``CONFIG_RUST``. It is compiled with ``rustc`` [rustc]_
diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst
index d159cd4f5e5b..5a7a212cf76b 100644
--- a/Documentation/process/researcher-guidelines.rst
+++ b/Documentation/process/researcher-guidelines.rst
@@ -2,8 +2,9 @@
 
 .. _researcher_guidelines:
 
+=====================
 Researcher Guidelines
-+++++++++++++++++++++
+=====================
 
 The Linux kernel community welcomes transparent research on the Linux
 kernel, the activities involved in producing it, and any other byproducts
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 692a3ba56cca..c40c9b81b48a 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -1,5 +1,6 @@
 .. _securitybugs:
 
+=============
 Security bugs
 =============
 
@@ -9,7 +10,7 @@ disclosed as quickly as possible.  Please report security bugs to the
 Linux kernel security team.
 
 Contact
--------
+=======
 
 The Linux kernel security team can be contacted by email at
 <security@kernel.org>.  This is a private list of security officers
@@ -34,7 +35,7 @@ issue if all the details are hidden away in attachments.  Think of it like a
 reproduction steps, and follow it with a proposed fix, all in plain text.
 
 Disclosure and embargoed information
-------------------------------------
+====================================
 
 The security list is not a disclosure channel.  For that, see Coordination
 below.
@@ -64,7 +65,7 @@ of the report are treated confidentially even after the embargo has been
 lifted, in perpetuity.
 
 Coordination with other groups
-------------------------------
+==============================
 
 While the kernel security team solely focuses on getting bugs fixed,
 other groups focus on fixing issues in distros and coordinating
@@ -94,7 +95,7 @@ fix is accepted do not Cc: "linux-distros", and after it's merged do not
 Cc: the kernel security team.
 
 CVE assignment
---------------
+==============
 
 The security team does not assign CVEs, nor do we require them for
 reports or fixes, as this can needlessly complicate the process and may
@@ -104,7 +105,7 @@ MITRE directly.  However under no circumstances will a patch inclusion
 be delayed to wait for a CVE identifier to arrive.
 
 Non-disclosure agreements
--------------------------
+=========================
 
 The Linux kernel security team is not a formal body and therefore unable
 to enter any non-disclosure agreements.
diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
index b1bc2d37bd0a..c4cd62b272df 100644
--- a/Documentation/process/submit-checklist.rst
+++ b/Documentation/process/submit-checklist.rst
@@ -1,7 +1,8 @@
 .. _submitchecklist:
 
+=======================================
 Linux Kernel patch submission checklist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=======================================
 
 Here are some basic things that developers should do if they want to see their
 kernel patch submissions accepted more quickly.
diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst
index 7eb6bd7c9214..7cfdb91980d5 100644
--- a/Documentation/process/volatile-considered-harmful.rst
+++ b/Documentation/process/volatile-considered-harmful.rst
@@ -1,8 +1,9 @@
 
 .. _volatile_considered_harmful:
 
+================================================
 Why the "volatile" type class should not be used
-------------------------------------------------
+================================================
 
 C programmers have often taken volatile to mean that the variable could be
 changed outside of the current thread of execution; as a result, they are
-- 
2.34.1

Re: [PATCH v3] Documentation: Document the Linux Kernel CVE process

[Greg Kroah-Hartman]

On Fri, Feb 16, 2024 at 07:58:00AM -0700, Jonathan Corbet wrote:
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> writes:
> 
> > On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
> >> rst basically allows any order of the heading underlines, and their
> >> relative hierarchy is determined by how they show up in each document,
> >> it's not specified by rst. However, it would be much easier for everyone
> >> if all the kernel documents followed the same style.
> >
> > Agreed, someone should pick a style and sweep the whole directory and
> > sync them up to the agreed formatting. :)
> 
> Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)

Fair enough, I'll go fix up the file headers here :)

thanks,

greg k-h

Re: [RFC] doc headings sweep

[Randy Dunlap]

On 2/16/24 23:31, Vegard Nossum wrote:
> On 16/02/2024 15:58, Jonathan Corbet wrote:
>> Greg Kroah-Hartman <gregkh@linuxfoundation.org> writes:
>>
>>> On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
>>>> rst basically allows any order of the heading underlines, and their
>>>> relative hierarchy is determined by how they show up in each document,
>>>> it's not specified by rst. However, it would be much easier for everyone
>>>> if all the kernel documents followed the same style.
>>>
>>> Agreed, someone should pick a style and sweep the whole directory and
>>> sync them up to the agreed formatting. :)
>>
>> Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)
> 
> I have a (very long and ugly) script that can fix these up to a
> consistent style, the attached patch is the result of running it on
> Documentation/process/ only.
> 
> I've done builds before and after the patch and diffed the resulting
> HTML files, they show no difference. (HOWEVER, you do need a 'make
> cleandocs' in between, as it seems doing 'make htmldocs; find
> Documentation | xargs touch; make htmldocs' is going to change the
> generated HTML for the sidebar -- another issue to look into at some
> point, I guess; maybe it's specific to the Sphinx version I used here,
> 4.3.2.)
> 
> The script will leave alone any file that it doesn't quite understand
> (e.g. for a lot of the translations there are way more underlines than
> characters in the heading and it doesn't match up with the byte count
> either).
> 
> Anyway, the question is: Is this worth doing in the first place, or is
> it just churn? I assume just after -rc1 would be the ideal time to
> submit these to avoid conflicts.

Yes, do it, please.
Thanks.

-- 
#Randy

Re: [RFC] doc headings sweep

[Jonathan Corbet]

Vegard Nossum <vegard.nossum@oracle.com> writes:

> I have a (very long and ugly) script that can fix these up to a
> consistent style, the attached patch is the result of running it on
> Documentation/process/ only.
>
> I've done builds before and after the patch and diffed the resulting
> HTML files, they show no difference. (HOWEVER, you do need a 'make
> cleandocs' in between, as it seems doing 'make htmldocs; find
> Documentation | xargs touch; make htmldocs' is going to change the
> generated HTML for the sidebar -- another issue to look into at some
> point, I guess; maybe it's specific to the Sphinx version I used here,
> 4.3.2.)
>
> The script will leave alone any file that it doesn't quite understand
> (e.g. for a lot of the translations there are way more underlines than
> characters in the heading and it doesn't match up with the byte count
> either).
>
> Anyway, the question is: Is this worth doing in the first place, or is
> it just churn? I assume just after -rc1 would be the ideal time to
> submit these to avoid conflicts.

So I must confess that I'm not convinced; it seems not that far removed
from the sorts of white-space fixes that drive developers nuts
elsewhere.

"Avoid conflicts" isn't going to happen.  By its nature, docs-next tends
to generate a lot of conflicts against other trees as it is -
*everybody* puts their fingers into Documentation/.  This would surely
create more of them, all of which I'd then get to explain to Linus.  I
think it might be better to encourage people to fix things up gradually
when they're in the files anyway.

But maybe others disagree?

Thanks,

jon