[PATCH 0/3] Documentation: clarify required info in security reports

[PATCH 0/3] Documentation: clarify required info in security reports

[Willy Tarreau]

Hi Greg,

I'm sending you the doc clarifications we discussed for the process of
reporting security issues. It's cut into the 3 patches I shared this
morning on the security list (plus two typos fixed and a paragraph
asking for one single issue per report):

  - one patch that reminds our need for a valid e-mail address
  - one that explains to reporters how to proceed to find maintainers
    addresses, hoping we won't have to do it for 90% of reports anymore
  - one that enumerates basic requirements for every report

I think it covers the difficulties we've faced this week. As always,
we might possibly find tiny adjustments to add, but my goal would be
for such updates to be merged in time to update the public page ASAP
so that we can redirect incomplete reports in an attempt to lower the
team's current load.

Thanks!
Willy

---

Willy Tarreau (3):
  Documentation: minor updates to the security contacts
  Documentation: explain how to find maintainers addresses for security
    reports
  Documentation: clarify the mandatory and desirable info for security
    reports

 Documentation/process/security-bugs.rst | 147 +++++++++++++++++++++---
 1 file changed, 132 insertions(+), 15 deletions(-)

-- 
2.52.0

[PATCH 1/3] Documentation: minor updates to the security contacts

[Willy Tarreau]

This clarifies the fact that the bug reporters must use a valid
e-mail address to send their report, and that the security team
assists developers working on a fix but doesn't always produce
fixes on its own.

Cc: Eric Dumazet <edumazet@google.com>
Cc: Greg KH <greg@kroah.com>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
 Documentation/process/security-bugs.rst | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index c0cf93e11565..da7937fd59df 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -8,6 +8,10 @@ like to know when a security bug is found so that it can be fixed and
 disclosed as quickly as possible.  Please report security bugs to the
 Linux kernel security team.
 
+Reports are to be sent over e-mail exclusively.  Please use a working e-mail
+address, preferably the same that you want to appear in ``Reported-by`` tags
+if any.  If unsure, send your report to yourself first.
+
 The security team and maintainers almost always require additional
 information beyond what was initially provided in a report and rely on
 active and efficient collaboration with the reporter to perform further
@@ -27,11 +31,9 @@ made public.
 
 The Linux kernel security team can be contacted by email at
 <security@kernel.org>.  This is a private list of security officers
-who will help verify the bug report and develop and release a fix.
-If you already have a fix, please include it with your report, as
-that can speed up the process considerably.  It is possible that the
-security team will bring in extra help from area maintainers to
-understand and fix the security vulnerability.
+who will help verify the bug report and assist developers working on a fix.
+It is possible that the security team will bring in extra help from area
+maintainers to understand and fix the security vulnerability.
 
 Please send **plain text** emails without attachments where possible.
 It is much harder to have a context-quoted discussion about a complex
-- 
2.52.0

[PATCH 2/3] Documentation: explain how to find maintainers addresses for security reports

[Willy Tarreau]

These days, 80% of the work done by the security team consists in
locating the affected subsystem in a report, running get_maintainers on
it, forwarding the report to these persons and responding to the reporter
with them in Cc. This is a huge and unneeded overhead that we must try to
lower for a better overall efficiency. This patch adds a complete section
explaining how to figure the list of recipients to send the report to.

Cc: Eric Dumazet <edumazet@google.com>
Cc: Greg KH <greg@kroah.com>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
 Documentation/process/security-bugs.rst | 76 ++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 3 deletions(-)

diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index da7937fd59df..6937fa9fba5a 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -5,8 +5,75 @@ Security bugs
 
 Linux kernel developers take security very seriously.  As such, we'd
 like to know when a security bug is found so that it can be fixed and
-disclosed as quickly as possible.  Please report security bugs to the
-Linux kernel security team.
+disclosed as quickly as possible.
+
+Identifying contacts
+--------------------
+
+The most effective way to report a security bug is to send it directly to the
+affected subsystem's maintainers and Cc: the Linux kernel security team.  Do
+not send it to a public list at this stage, unless you have good reasons to
+consider the issue as being public or trivial to discover (e.g. result of a
+widely available automated vulnerability scanning tool that can be repeated by
+anyone).
+
+If you're sending a report for issues affecting multiple parts in the kernel,
+even if they're fairly similar issues, please send individual messages (think
+that maintainers will not all work on the issues at the same time). The only
+exception is when an issue concerns closely related parts maintained by the
+exact same subset of maintainers, and these parts are expected to be fixed all
+at once by the same commit, then it may be acceptable to report them at once.
+
+One difficulty for most first-time reporters is to figure the right list of
+recipients to send a report to.  In the Linux kernel, all official maintainers
+are trusted, so the consequences of accidentally including the wrong maintainer
+are essentially a bit more noise for that person, i.e. nothing dramatic.  As
+such, a suitable method to figure the list of maintainers (which kernel
+security officers use) is to rely on the get_maintainers.pl script, tuned to
+only report maintainers.  This script, when passed a file name, will look for
+its path in the MAINTAINERS file to figure a hierarchical list of relevant
+maintainers.  Calling it a first time with the finest level of filtering will
+most of the time return a short list of this specific file's maintainers::
+
+  $ ./scripts/get_maintainer.pl --no-l --no-r --pattern-depth 1 \
+    drivers/example.c
+  Developer One <dev1@example.com> (maintainer:example driver)
+  Developer Two <dev2@example.org> (maintainer:example driver)
+
+These two maintainers should then receive the message.  If the command does not
+return anything, it means the affected file is part of a wider subsystem, so we
+should be less specific::
+
+  $ ./scripts/get_maintainer.pl --no-l --no-r drivers/example.c
+  Developer One <dev1@example.com> (maintainer:example subsystem)
+  Developer Two <dev2@example.org> (maintainer:example subsystem)
+  Developer Three <dev3@example.com> (maintainer:example subsystem [GENERAL])
+  Developer Four <dev4@example.org> (maintainer:example subsystem [GENERAL])
+
+Here, picking the first, most specific ones, is sufficient.  When the list is
+long, it is possible to produce a comma-delimited e-mail address list on a
+single line suitable for use in the To: field of a mailer like this::
+
+  $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \
+    --no-git-fallback --no-substatus --no-rolestats --no-multiline \
+    --pattern-depth 1 drivers/example.c
+  dev1@example.com, dev2@example.org
+
+or this for the wider list::
+
+  $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \
+    --no-git-fallback --no-substatus --no-rolestats --no-multiline \
+    drivers/example.c
+  dev1@example.com, dev2@example.org, dev3@example.com, dev4@example.org
+
+If at this point you're still facing difficulties spotting the right
+maintainers, **and only in this case**, it's possible to send your report to
+the Linux kernel security team only.  Your message will be triaged, and you
+will receive instructions about whom to contact, if needed.  Your message may
+equally be forwarded as-is to the relevant maintainers.
+
+Sending the report
+------------------
 
 Reports are to be sent over e-mail exclusively.  Please use a working e-mail
 address, preferably the same that you want to appear in ``Reported-by`` tags
@@ -29,6 +96,7 @@ information is helpful.  Any exploit code is very helpful and will not
 be released without consent from the reporter unless it has already been
 made public.
 
+The report must be sent to maintainers, with the security team in ``Cc:``.
 The Linux kernel security team can be contacted by email at
 <security@kernel.org>.  This is a private list of security officers
 who will help verify the bug report and assist developers working on a fix.
@@ -44,7 +112,9 @@ reproduction steps, and follow it with a proposed fix, all in plain text.
 Markdown, HTML and RST formatted reports are particularly frowned upon since
 they're quite hard to read for humans and encourage to use dedicated viewers,
 sometimes online, which by definition is not acceptable for a confidential
-security report.
+security report. Note that some mailers tend to mangle formatting of plain
+text by default, please consult :doc:`the email client howto
+<../process/email-clients>` for more info.
 
 Disclosure and embargoed information
 ------------------------------------
-- 
2.52.0

Re: [PATCH 2/3] Documentation: explain how to find maintainers addresses for security reports

[Randy Dunlap]

On 4/2/26 11:26 AM, Willy Tarreau wrote:
> These days, 80% of the work done by the security team consists in
> locating the affected subsystem in a report, running get_maintainers on
> it, forwarding the report to these persons and responding to the reporter
> with them in Cc. This is a huge and unneeded overhead that we must try to
> lower for a better overall efficiency. This patch adds a complete section
> explaining how to figure the list of recipients to send the report to.
> 
> Cc: Eric Dumazet <edumazet@google.com>
> Cc: Greg KH <greg@kroah.com>
> Signed-off-by: Willy Tarreau <w@1wt.eu>
> ---
>  Documentation/process/security-bugs.rst | 76 ++++++++++++++++++++++++-
>  1 file changed, 73 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> index da7937fd59df..6937fa9fba5a 100644
> --- a/Documentation/process/security-bugs.rst
> +++ b/Documentation/process/security-bugs.rst


>  Markdown, HTML and RST formatted reports are particularly frowned upon since
>  they're quite hard to read for humans and encourage to use dedicated viewers,
>  sometimes online, which by definition is not acceptable for a confidential
> -security report.
> +security report. Note that some mailers tend to mangle formatting of plain
> +text by default, please consult :doc:`the email client howto
> +<../process/email-clients>` for more info.

Just use the file name and let automarkup do its job:

   text by default; please consult Documentation/process/email-clients.rst
   for more information.

It's also more convenient for text readers that way.

>  
>  Disclosure and embargoed information
>  ------------------------------------

-- 
~Randy

Re: [PATCH 2/3] Documentation: explain how to find maintainers addresses for security reports

[Willy Tarreau]

On Thu, Apr 02, 2026 at 11:42:51AM -0700, Randy Dunlap wrote:
> 
> 
> On 4/2/26 11:26 AM, Willy Tarreau wrote:
> > These days, 80% of the work done by the security team consists in
> > locating the affected subsystem in a report, running get_maintainers on
> > it, forwarding the report to these persons and responding to the reporter
> > with them in Cc. This is a huge and unneeded overhead that we must try to
> > lower for a better overall efficiency. This patch adds a complete section
> > explaining how to figure the list of recipients to send the report to.
> > 
> > Cc: Eric Dumazet <edumazet@google.com>
> > Cc: Greg KH <greg@kroah.com>
> > Signed-off-by: Willy Tarreau <w@1wt.eu>
> > ---
> >  Documentation/process/security-bugs.rst | 76 ++++++++++++++++++++++++-
> >  1 file changed, 73 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> > index da7937fd59df..6937fa9fba5a 100644
> > --- a/Documentation/process/security-bugs.rst
> > +++ b/Documentation/process/security-bugs.rst
> 
> 
> >  Markdown, HTML and RST formatted reports are particularly frowned upon since
> >  they're quite hard to read for humans and encourage to use dedicated viewers,
> >  sometimes online, which by definition is not acceptable for a confidential
> > -security report.
> > +security report. Note that some mailers tend to mangle formatting of plain
> > +text by default, please consult :doc:`the email client howto
> > +<../process/email-clients>` for more info.
> 
> Just use the file name and let automarkup do its job:
> 
>    text by default; please consult Documentation/process/email-clients.rst
>    for more information.
> 
> It's also more convenient for text readers that way.

If that's supposed to work, I'm indeed all for it! I must confess that
I have not even understood the reason for "../process" when coming from
the same directory, but I just picked that from existing entries.

Thanks for your feedback, much appreciated!
Willy

[PATCH 3/3] Documentation: clarify the mandatory and desirable info for security reports

[Willy Tarreau]

A significant part of the effort of the security team consists in begging
reporters for patch proposals, or asking them to provide them in regular
format, and most of the time they're willing to provide this, they just
didn't know that it would help. So let's add a section detailing the
required and desirable contents in a security report to help reporters
write more actionable reports which do not require round trips.

Cc: Eric Dumazet <edumazet@google.com>
Cc: Greg KH <greg@kroah.com>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
 Documentation/process/security-bugs.rst | 66 ++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 7 deletions(-)

diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 6937fa9fba5a..b243ac24eb12 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -7,6 +7,65 @@ Linux kernel developers take security very seriously.  As such, we'd
 like to know when a security bug is found so that it can be fixed and
 disclosed as quickly as possible.
 
+Preparing your report
+---------------------
+
+Like with any bug report, a security bug report requires a lot of analysis work
+from the developers, so the more information you can share about the issue, the
+better.  Please review the procedure outlined in
+'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
+information is helpful.  The following information are absolutely necessary in
+**any** security bug report:
+
+  * **affected kernel version range**: with no version indication, your report
+    will not be processed.  A significant part of reports are for bugs that
+    have already been fixed, so it is extremely important that vulnerabilities
+    are verified on recent versions (development tree or latest stable
+    version), at least by verifying that the code has not changed since the
+    version where it was detected.
+
+  * **description of the problem**: a detailed description of the problem, with
+    traces showing its manifestation, and why you consider that the observed
+    behavior as a problem in the kernel, is necessary.
+
+  * **reproducer**: developers will need to be able to reproduce the problem to
+    consider a fix as effective.  This includes both a way to trigger the issue
+    and a way to confirm it happens.  A reproducer with low complexity
+    dependencies will be needed (source code, shell script, sequence of
+    instructions, file-system image etc).  Binary-only executables are not
+    accepted.  Working exploits are extremely helpful and will not be released
+    without consent from the reporter, unless they are already public.  By
+    definition if an issue cannot be reproduced, it is not exploitable, thus it
+    is not a security bug.
+
+  * **conditions**: if the bug depends on certain configuration options,
+    sysctls, permissions, timing, code modifications etc, these should be
+    indicated.
+
+In addition, the following information are highly desirable:
+
+  * **suspected location of the bug**: the file names and functions where the
+    bug is suspected to be present are very important, at least to help forward
+    the report to the appropriate maintainers.  When not possible (for example,
+    "system freezes each time I run this command"), the security team will help
+    identify the source of the bug.
+
+  * **a proposed fix**: bug reporters who have analyzed the cause of a bug in
+    the source code almost always have an accurate idea on how to fix it,
+    because they spent a long time studying it and its implications.  Proposing
+    a tested fix will save maintainers a lot of time, even if the fix ends up
+    not being the right one, because it helps understand the bug.  When
+    proposing a tested fix, please always format it in a way that can be
+    immediately merged (see :doc:`regular patch submission
+    <../process/submitting-patches>`).  This will save some back-and-forth
+    exchanges if it is accepted, and you will be credited for finding and
+    fixing this issue.  Note that in this case only a ``Signed-off-by:`` tag is
+    needed, without ``Reported-by:` when the reporter and author are the same.
+
+  * **mitigations**: very often during a bug analysis, some ways of mitigating
+    the issue appear. It is useful to share them, as they can be helpful to
+    keep end users protected during the time it takes them to apply the fix.
+
 Identifying contacts
 --------------------
 
@@ -89,13 +148,6 @@ run additional tests.  Reports where the reporter does not respond promptly
 or cannot effectively discuss their findings may be abandoned if the
 communication does not quickly improve.
 
-As it is with any bug, the more information provided the easier it
-will be to diagnose and fix.  Please review the procedure outlined in
-'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
-information is helpful.  Any exploit code is very helpful and will not
-be released without consent from the reporter unless it has already been
-made public.
-
 The report must be sent to maintainers, with the security team in ``Cc:``.
 The Linux kernel security team can be contacted by email at
 <security@kernel.org>.  This is a private list of security officers
-- 
2.52.0

Re: [PATCH 3/3] Documentation: clarify the mandatory and desirable info for security reports

[Randy Dunlap]

On 4/2/26 11:26 AM, Willy Tarreau wrote:
> A significant part of the effort of the security team consists in begging
> reporters for patch proposals, or asking them to provide them in regular
> format, and most of the time they're willing to provide this, they just
> didn't know that it would help. So let's add a section detailing the
> required and desirable contents in a security report to help reporters
> write more actionable reports which do not require round trips.
> 
> Cc: Eric Dumazet <edumazet@google.com>
> Cc: Greg KH <greg@kroah.com>
> Signed-off-by: Willy Tarreau <w@1wt.eu>
> ---
>  Documentation/process/security-bugs.rst | 66 ++++++++++++++++++++++---
>  1 file changed, 59 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> index 6937fa9fba5a..b243ac24eb12 100644
> --- a/Documentation/process/security-bugs.rst
> +++ b/Documentation/process/security-bugs.rst
> @@ -7,6 +7,65 @@ Linux kernel developers take security very seriously.  As such, we'd
>  like to know when a security bug is found so that it can be fixed and
>  disclosed as quickly as possible.
>  
> +Preparing your report
> +---------------------
> +
> +Like with any bug report, a security bug report requires a lot of analysis work
> +from the developers, so the more information you can share about the issue, the
> +better.  Please review the procedure outlined in
> +'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what

Drop the single quote marks.

> +information is helpful.  The following information are absolutely necessary in
> +**any** security bug report:
> +
> +  * **affected kernel version range**: with no version indication, your report
> +    will not be processed.  A significant part of reports are for bugs that
> +    have already been fixed, so it is extremely important that vulnerabilities
> +    are verified on recent versions (development tree or latest stable
> +    version), at least by verifying that the code has not changed since the
> +    version where it was detected.
> +
> +  * **description of the problem**: a detailed description of the problem, with
> +    traces showing its manifestation, and why you consider that the observed
> +    behavior as a problem in the kernel, is necessary.
> +
> +  * **reproducer**: developers will need to be able to reproduce the problem to
> +    consider a fix as effective.  This includes both a way to trigger the issue
> +    and a way to confirm it happens.  A reproducer with low complexity
> +    dependencies will be needed (source code, shell script, sequence of
> +    instructions, file-system image etc).  Binary-only executables are not
> +    accepted.  Working exploits are extremely helpful and will not be released
> +    without consent from the reporter, unless they are already public.  By
> +    definition if an issue cannot be reproduced, it is not exploitable, thus it
> +    is not a security bug.
> +
> +  * **conditions**: if the bug depends on certain configuration options,
> +    sysctls, permissions, timing, code modifications etc, these should be
> +    indicated.
> +
> +In addition, the following information are highly desirable:
> +
> +  * **suspected location of the bug**: the file names and functions where the
> +    bug is suspected to be present are very important, at least to help forward
> +    the report to the appropriate maintainers.  When not possible (for example,
> +    "system freezes each time I run this command"), the security team will help
> +    identify the source of the bug.
> +
> +  * **a proposed fix**: bug reporters who have analyzed the cause of a bug in
> +    the source code almost always have an accurate idea on how to fix it,
> +    because they spent a long time studying it and its implications.  Proposing
> +    a tested fix will save maintainers a lot of time, even if the fix ends up
> +    not being the right one, because it helps understand the bug.  When
> +    proposing a tested fix, please always format it in a way that can be
> +    immediately merged (see :doc:`regular patch submission
> +    <../process/submitting-patches>`).  This will save some back-and-forth

Hm, I don't see anything in submitting-patches.rst called "regular patch submission".
Is it in some other patch?

> +    exchanges if it is accepted, and you will be credited for finding and
> +    fixing this issue.  Note that in this case only a ``Signed-off-by:`` tag is
> +    needed, without ``Reported-by:` when the reporter and author are the same.


-- 
~Randy

Re: [PATCH 3/3] Documentation: clarify the mandatory and desirable info for security reports

[Willy Tarreau]

Hi Randy,

On Thu, Apr 02, 2026 at 11:50:00AM -0700, Randy Dunlap wrote:
> 
> On 4/2/26 11:26 AM, Willy Tarreau wrote:
> > A significant part of the effort of the security team consists in begging
> > reporters for patch proposals, or asking them to provide them in regular
> > format, and most of the time they're willing to provide this, they just
> > didn't know that it would help. So let's add a section detailing the
> > required and desirable contents in a security report to help reporters
> > write more actionable reports which do not require round trips.
> > 
> > Cc: Eric Dumazet <edumazet@google.com>
> > Cc: Greg KH <greg@kroah.com>
> > Signed-off-by: Willy Tarreau <w@1wt.eu>
> > ---
> >  Documentation/process/security-bugs.rst | 66 ++++++++++++++++++++++---
> >  1 file changed, 59 insertions(+), 7 deletions(-)
> > 
> > diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> > index 6937fa9fba5a..b243ac24eb12 100644
> > --- a/Documentation/process/security-bugs.rst
> > +++ b/Documentation/process/security-bugs.rst
> > @@ -7,6 +7,65 @@ Linux kernel developers take security very seriously.  As such, we'd
> >  like to know when a security bug is found so that it can be fixed and
> >  disclosed as quickly as possible.
> >  
> > +Preparing your report
> > +---------------------
> > +
> > +Like with any bug report, a security bug report requires a lot of analysis work
> > +from the developers, so the more information you can share about the issue, the
> > +better.  Please review the procedure outlined in
> > +'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
> 
> Drop the single quote marks.

I just moved this part as-is, and I've been extremely hesitant to change
formatting as I can't easily check the validity of the output.

> > +information is helpful.  The following information are absolutely necessary in
> > +**any** security bug report:
> > +
> > +  * **affected kernel version range**: with no version indication, your report
> > +    will not be processed.  A significant part of reports are for bugs that
> > +    have already been fixed, so it is extremely important that vulnerabilities
> > +    are verified on recent versions (development tree or latest stable
> > +    version), at least by verifying that the code has not changed since the
> > +    version where it was detected.
> > +
> > +  * **description of the problem**: a detailed description of the problem, with
> > +    traces showing its manifestation, and why you consider that the observed
> > +    behavior as a problem in the kernel, is necessary.
> > +
> > +  * **reproducer**: developers will need to be able to reproduce the problem to
> > +    consider a fix as effective.  This includes both a way to trigger the issue
> > +    and a way to confirm it happens.  A reproducer with low complexity
> > +    dependencies will be needed (source code, shell script, sequence of
> > +    instructions, file-system image etc).  Binary-only executables are not
> > +    accepted.  Working exploits are extremely helpful and will not be released
> > +    without consent from the reporter, unless they are already public.  By
> > +    definition if an issue cannot be reproduced, it is not exploitable, thus it
> > +    is not a security bug.
> > +
> > +  * **conditions**: if the bug depends on certain configuration options,
> > +    sysctls, permissions, timing, code modifications etc, these should be
> > +    indicated.
> > +
> > +In addition, the following information are highly desirable:
> > +
> > +  * **suspected location of the bug**: the file names and functions where the
> > +    bug is suspected to be present are very important, at least to help forward
> > +    the report to the appropriate maintainers.  When not possible (for example,
> > +    "system freezes each time I run this command"), the security team will help
> > +    identify the source of the bug.
> > +
> > +  * **a proposed fix**: bug reporters who have analyzed the cause of a bug in
> > +    the source code almost always have an accurate idea on how to fix it,
> > +    because they spent a long time studying it and its implications.  Proposing
> > +    a tested fix will save maintainers a lot of time, even if the fix ends up
> > +    not being the right one, because it helps understand the bug.  When
> > +    proposing a tested fix, please always format it in a way that can be
> > +    immediately merged (see :doc:`regular patch submission
> > +    <../process/submitting-patches>`).  This will save some back-and-forth
> 
> Hm, I don't see anything in submitting-patches.rst called "regular patch submission".
> Is it in some other patch?

Not sure what you mean. Is this supposed to be a sub-section and not just a
title ? On https://www.kernel.org/doc/html/latest/process/security-bugs.html
it appears as the title. This one was already present in the same document
and was moved there without a change.

Thanks a lot for your help!
Willy

Re: [PATCH 3/3] Documentation: clarify the mandatory and desirable info for security reports

[Randy Dunlap]

On 4/2/26 12:03 PM, Willy Tarreau wrote:
> Hi Randy,
> 
> On Thu, Apr 02, 2026 at 11:50:00AM -0700, Randy Dunlap wrote:
>>
>> On 4/2/26 11:26 AM, Willy Tarreau wrote:
>>> A significant part of the effort of the security team consists in begging
>>> reporters for patch proposals, or asking them to provide them in regular
>>> format, and most of the time they're willing to provide this, they just
>>> didn't know that it would help. So let's add a section detailing the
>>> required and desirable contents in a security report to help reporters
>>> write more actionable reports which do not require round trips.
>>>
>>> Cc: Eric Dumazet <edumazet@google.com>
>>> Cc: Greg KH <greg@kroah.com>
>>> Signed-off-by: Willy Tarreau <w@1wt.eu>
>>> ---
>>>  Documentation/process/security-bugs.rst | 66 ++++++++++++++++++++++---
>>>  1 file changed, 59 insertions(+), 7 deletions(-)
>>>
>>> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
>>> index 6937fa9fba5a..b243ac24eb12 100644
>>> --- a/Documentation/process/security-bugs.rst
>>> +++ b/Documentation/process/security-bugs.rst
>>> @@ -7,6 +7,65 @@ Linux kernel developers take security very seriously.  As such, we'd
>>>  like to know when a security bug is found so that it can be fixed and
>>>  disclosed as quickly as possible.
>>>  
>>> +Preparing your report
>>> +---------------------
>>> +
>>> +Like with any bug report, a security bug report requires a lot of analysis work
>>> +from the developers, so the more information you can share about the issue, the
>>> +better.  Please review the procedure outlined in
>>> +'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
>>
>> Drop the single quote marks.
> 
> I just moved this part as-is, and I've been extremely hesitant to change
> formatting as I can't easily check the validity of the output.
> 
>>> +information is helpful.  The following information are absolutely necessary in
>>> +**any** security bug report:
>>> +
>>> +  * **affected kernel version range**: with no version indication, your report
>>> +    will not be processed.  A significant part of reports are for bugs that
>>> +    have already been fixed, so it is extremely important that vulnerabilities
>>> +    are verified on recent versions (development tree or latest stable
>>> +    version), at least by verifying that the code has not changed since the
>>> +    version where it was detected.
>>> +
>>> +  * **description of the problem**: a detailed description of the problem, with
>>> +    traces showing its manifestation, and why you consider that the observed
>>> +    behavior as a problem in the kernel, is necessary.
>>> +
>>> +  * **reproducer**: developers will need to be able to reproduce the problem to
>>> +    consider a fix as effective.  This includes both a way to trigger the issue
>>> +    and a way to confirm it happens.  A reproducer with low complexity
>>> +    dependencies will be needed (source code, shell script, sequence of
>>> +    instructions, file-system image etc).  Binary-only executables are not
>>> +    accepted.  Working exploits are extremely helpful and will not be released
>>> +    without consent from the reporter, unless they are already public.  By
>>> +    definition if an issue cannot be reproduced, it is not exploitable, thus it
>>> +    is not a security bug.
>>> +
>>> +  * **conditions**: if the bug depends on certain configuration options,
>>> +    sysctls, permissions, timing, code modifications etc, these should be
>>> +    indicated.
>>> +
>>> +In addition, the following information are highly desirable:
>>> +
>>> +  * **suspected location of the bug**: the file names and functions where the
>>> +    bug is suspected to be present are very important, at least to help forward
>>> +    the report to the appropriate maintainers.  When not possible (for example,
>>> +    "system freezes each time I run this command"), the security team will help
>>> +    identify the source of the bug.
>>> +
>>> +  * **a proposed fix**: bug reporters who have analyzed the cause of a bug in
>>> +    the source code almost always have an accurate idea on how to fix it,
>>> +    because they spent a long time studying it and its implications.  Proposing
>>> +    a tested fix will save maintainers a lot of time, even if the fix ends up
>>> +    not being the right one, because it helps understand the bug.  When
>>> +    proposing a tested fix, please always format it in a way that can be
>>> +    immediately merged (see :doc:`regular patch submission
>>> +    <../process/submitting-patches>`).  This will save some back-and-forth
>>
>> Hm, I don't see anything in submitting-patches.rst called "regular patch submission".
>> Is it in some other patch?
> 
> Not sure what you mean. Is this supposed to be a sub-section and not just a
> title ? On https://www.kernel.org/doc/html/latest/process/security-bugs.html
> it appears as the title. This one was already present in the same document
> and was moved there without a change.

I see. Sorry for the noise.

-- 
~Randy

Re: [PATCH 3/3] Documentation: clarify the mandatory and desirable info for security reports

[Willy Tarreau]

On Thu, Apr 02, 2026 at 12:17:38PM -0700, Randy Dunlap wrote:
> 
> 
> On 4/2/26 12:03 PM, Willy Tarreau wrote:
> > Hi Randy,
> > 
> > On Thu, Apr 02, 2026 at 11:50:00AM -0700, Randy Dunlap wrote:
> >>
> >> On 4/2/26 11:26 AM, Willy Tarreau wrote:
> >>> A significant part of the effort of the security team consists in begging
> >>> reporters for patch proposals, or asking them to provide them in regular
> >>> format, and most of the time they're willing to provide this, they just
> >>> didn't know that it would help. So let's add a section detailing the
> >>> required and desirable contents in a security report to help reporters
> >>> write more actionable reports which do not require round trips.
> >>>
> >>> Cc: Eric Dumazet <edumazet@google.com>
> >>> Cc: Greg KH <greg@kroah.com>
> >>> Signed-off-by: Willy Tarreau <w@1wt.eu>
> >>> ---
> >>>  Documentation/process/security-bugs.rst | 66 ++++++++++++++++++++++---
> >>>  1 file changed, 59 insertions(+), 7 deletions(-)
> >>>
> >>> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> >>> index 6937fa9fba5a..b243ac24eb12 100644
> >>> --- a/Documentation/process/security-bugs.rst
> >>> +++ b/Documentation/process/security-bugs.rst
> >>> @@ -7,6 +7,65 @@ Linux kernel developers take security very seriously.  As such, we'd
> >>>  like to know when a security bug is found so that it can be fixed and
> >>>  disclosed as quickly as possible.
> >>>  
> >>> +Preparing your report
> >>> +---------------------
> >>> +
> >>> +Like with any bug report, a security bug report requires a lot of analysis work
> >>> +from the developers, so the more information you can share about the issue, the
> >>> +better.  Please review the procedure outlined in
> >>> +'Documentation/admin-guide/reporting-issues.rst' if you are unclear about what
> >>
> >> Drop the single quote marks.
> > 
> > I just moved this part as-is, and I've been extremely hesitant to change
> > formatting as I can't easily check the validity of the output.
> > 
> >>> +information is helpful.  The following information are absolutely necessary in
> >>> +**any** security bug report:
> >>> +
> >>> +  * **affected kernel version range**: with no version indication, your report
> >>> +    will not be processed.  A significant part of reports are for bugs that
> >>> +    have already been fixed, so it is extremely important that vulnerabilities
> >>> +    are verified on recent versions (development tree or latest stable
> >>> +    version), at least by verifying that the code has not changed since the
> >>> +    version where it was detected.
> >>> +
> >>> +  * **description of the problem**: a detailed description of the problem, with
> >>> +    traces showing its manifestation, and why you consider that the observed
> >>> +    behavior as a problem in the kernel, is necessary.
> >>> +
> >>> +  * **reproducer**: developers will need to be able to reproduce the problem to
> >>> +    consider a fix as effective.  This includes both a way to trigger the issue
> >>> +    and a way to confirm it happens.  A reproducer with low complexity
> >>> +    dependencies will be needed (source code, shell script, sequence of
> >>> +    instructions, file-system image etc).  Binary-only executables are not
> >>> +    accepted.  Working exploits are extremely helpful and will not be released
> >>> +    without consent from the reporter, unless they are already public.  By
> >>> +    definition if an issue cannot be reproduced, it is not exploitable, thus it
> >>> +    is not a security bug.
> >>> +
> >>> +  * **conditions**: if the bug depends on certain configuration options,
> >>> +    sysctls, permissions, timing, code modifications etc, these should be
> >>> +    indicated.
> >>> +
> >>> +In addition, the following information are highly desirable:
> >>> +
> >>> +  * **suspected location of the bug**: the file names and functions where the
> >>> +    bug is suspected to be present are very important, at least to help forward
> >>> +    the report to the appropriate maintainers.  When not possible (for example,
> >>> +    "system freezes each time I run this command"), the security team will help
> >>> +    identify the source of the bug.
> >>> +
> >>> +  * **a proposed fix**: bug reporters who have analyzed the cause of a bug in
> >>> +    the source code almost always have an accurate idea on how to fix it,
> >>> +    because they spent a long time studying it and its implications.  Proposing
> >>> +    a tested fix will save maintainers a lot of time, even if the fix ends up
> >>> +    not being the right one, because it helps understand the bug.  When
> >>> +    proposing a tested fix, please always format it in a way that can be
> >>> +    immediately merged (see :doc:`regular patch submission
> >>> +    <../process/submitting-patches>`).  This will save some back-and-forth
> >>
> >> Hm, I don't see anything in submitting-patches.rst called "regular patch submission".
> >> Is it in some other patch?
> > 
> > Not sure what you mean. Is this supposed to be a sub-section and not just a
> > title ? On https://www.kernel.org/doc/html/latest/process/security-bugs.html
> > it appears as the title. This one was already present in the same document
> > and was moved there without a change.
> 
> I see. Sorry for the noise.

No worries, I appreciate your help, the format is not trivial and mistakes
are easy!

Thanks,
Willy