[PATCH v2] Documentation/security-bugs: overhaul

[PATCH v2] Documentation/security-bugs: overhaul

[Vegard Nossum]

The current instructions for reporting security vulnerabilities in the
kernel are not clear enough, in particular the process of disclosure
and requesting CVEs, and what the roles of the different lists are and
how exactly to report to each of them.

Let's give this document an overhaul. Goals are stated as a comment at
the bottom of the document; these will not appear in the rendered HTML
document.

v2: address feedback from Willy Tarreau and Jonathan Corbet

Link: https://seclists.org/oss-sec/2022/q2/133
Cc: Amit Shah <aams@amazon.com>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: David Woodhouse <dwmw@amazon.co.uk>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Gustavo A. R. Silva <gustavoars@kernel.org>
Cc: Jiri Kosina <jkosina@suse.cz>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kees Cook <keescook@chromium.org>
Cc: Laura Abbott <labbott@kernel.org>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Solar Designer <solar@openwall.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Thorsten Leemhuis <linux@leemhuis.info>
Cc: Tyler Hicks <tyhicks@linux.microsoft.com>
Cc: Will Deacon <will@kernel.org>
Cc: Willy Tarreau <w@1wt.eu>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
---
 Documentation/admin-guide/security-bugs.rst | 252 +++++++++++++-------
 1 file changed, 167 insertions(+), 85 deletions(-)

v1 thread:
https://lore.kernel.org/all/20220531230309.9290-1-vegard.nossum@oracle.com/T/#u

Updated rendered HTML:
https://vegard.github.io/security/Documentation/output/admin-guide/security-bugs-v2.html

diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
index 82e29837d5898..c63eeb1e89ffd 100644
--- a/Documentation/admin-guide/security-bugs.rst
+++ b/Documentation/admin-guide/security-bugs.rst
@@ -1,96 +1,178 @@
+
 .. _securitybugs:
 
-Security bugs
-=============
+Reporting 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.
-
-Contact
--------
-
-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.
-
-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.
-
-Please send plain text emails without attachments where possible.
-It is much harder to have a context-quoted discussion about a complex
-issue if all the details are hidden away in attachments.  Think of it like a
-:doc:`regular patch submission <../process/submitting-patches>`
-(even if you don't have a patch yet): describe the problem and impact, list
+Linux kernel security team at security@kernel.org, henceforth "the
+security list". This is a closed list of trusted developers who will
+help verify the bug report and develop a patch in case none was already
+proposed.
+
+While the security list is closed, the security team may bring in
+extra help from the relevant maintainers to understand and fix the
+security vulnerability.
+
+Note that the main interest of the kernel security list is in getting
+bugs fixed and getting patches reviewed, tested, and merged; CVE
+assignment, disclosure to distributions, and public disclosure happen
+on different lists with different people, as described below.
+
+Here is a quick overview of the various lists:
+
+ =============================== ===== =================== ===============
+ List address                    Open? Purpose             Members
+ =============================== ===== =================== ===============
+ security@kernel.org                no | Reporting         Trusted kernel
+                                       | Patch development developers
+ ------------------------------- ----- ------------------- ---------------
+ linux-distros@vs.openwall.org      no | Coordination      Distribution
+                                       | CVE assignment    representatives
+                                       | Backporting
+                                       | Testing
+ ------------------------------- ----- ------------------- ---------------
+ oss-security@lists.openwall.com   yes | Disclosure        General public
+ =============================== ===== =================== ===============
+
+The following sections give a step-by-step guide to reporting and
+disclosure.
+
+Contacting the security list
+----------------------------
+
+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. Reporters are encouraged to propose patches, participate
+in the discussions of a fix, and test patches.
+
+The security team does not assign CVEs, nor does it require them
+for reports or fixes. CVEs may be requested when the issue is reported to
+the linux-distros list.
+
+**Disclosure.** The security list strongly prefers to have patches posted
+for review and testing on public mailing lists and and merged into the
+appropriate public git repository as soon as they become available.
+However, in exceptional cases, you or an affected party may request that
+the patch be withheld for some days; as a rule, the maximum is 7 days.
+Only in truly exceptional cases will the security list consider deferring
+the publication of a fix beyond this, and the only valid reason for doing
+so would be to accommodate the logistics of QA and large scale rollouts
+that require release coordination.
+
+Please note that although a fix is public, there may still be value
+in withholding the details of its security relevance and/or how to exploit
+it for another while; see below for when and how to properly disclose the
+security impact of your findings publicly.
+
+**List rules.** Please send plain text emails without attachments where
+possible. It is much harder to have a context-quoted discussion about a
+complex issue if all the details are hidden away in attachments. Think of
+it like regular patch submission (see Documentation/process/submitting-patches.rst)
+even if you don't have a patch yet; describe the problem and impact, list
 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.
-
-Once a robust fix has been developed, the release process starts.  Fixes
-for publicly known bugs are released immediately.
-
-Although our preference is to release fixes for publicly undisclosed bugs
-as soon as they become available, this may be postponed at the request of
-the reporter or an affected party for up to 7 calendar days from the start
-of the release process, with an exceptional extension to 14 calendar days
-if it is agreed that the criticality of the bug requires more time.  The
-only valid reason for deferring the publication of a fix is to accommodate
-the logistics of QA and large scale rollouts which require release
-coordination.
-
-While embargoed information may be shared with trusted individuals in
-order to develop a fix, such information will not be published alongside
-the fix or on any other disclosure channel without the permission of the
-reporter.  This includes but is not limited to the original bug report
-and followup discussions (if any), exploits, CVE information or the
-identity of the reporter.
-
-In other words our only interest is in getting bugs fixed.  All other
-information submitted to the security list and any followup discussions
-of the report are treated confidentially even after the embargo has been
-lifted, in perpetuity.
-
-Coordination
-------------
-
-Fixes for sensitive bugs, such as those that might lead to privilege
-escalations, may need to be coordinated with the private
-<linux-distros@vs.openwall.org> mailing list so that distribution vendors
-are well prepared to issue a fixed kernel upon public disclosure of the
-upstream fix. Distros will need some time to test the proposed patch and
-will generally request at least a few days of embargo, and vendor update
-publication prefers to happen Tuesday through Thursday. When appropriate,
-the security team can assist with this coordination, or the reporter can
-include linux-distros from the start. In this case, remember to prefix
-the email Subject line with "[vs]" as described in the linux-distros wiki:
-<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>
-
-CVE assignment
---------------
-
-The security team does not normally 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 ahead of public disclosure, they will need to contact the private
-linux-distros list, described above. When such a CVE identifier is known
-before a patch is provided, it is desirable to mention it in the commit
-message if the reporter agrees.
-
-Non-disclosure agreements
--------------------------
+**Confidentiality.** While embargoed information may be shared with trusted
+individuals in order to develop a fix, such information will not be
+published alongside the fix or on any other disclosure channel without the
+permission of the reporter. This includes but is not limited to the
+original bug report and followup discussions (if any), exploits, CVE
+information or the identity of the reporter. All such other information
+submitted to the security list and any follow-up discussions of the report
+are treated confidentially even after the embargo has been lifted, in
+perpetuity.
 
 The Linux kernel security team is not a formal body and therefore unable
 to enter any non-disclosure agreements.
+
+Once a patch has been developed, you are encouraged to contact the
+linux-distros list.
+
+Contacting the linux-distros list
+---------------------------------
+
+Fixes for particularly sensitive bugs (such as those that might lead to
+privilege escalations) may need to be coordinated with the private
+linux-distros mailing list (linux-distros@vs.openwall.org) so that
+distribution vendors are well prepared to release a fixed kernel as soon
+as possible after the public disclosure of the upstream fix. This
+includes verifying the reported issue, testing proposed fixes,
+developing a fix (if none is known yet), and backporting to older kernels
+and other versions.
+
+The linux-distros list can also help with assigning a CVE for your issue.
+
+**Disclosure.** The linux-distros list has a strict policy of requiring
+reporters to post about the security issue on oss-security within 14 days
+of the list being contacted regardless of whether a patch is available or
+not. It is therefore preferable that you don't send your initial bug
+report to the linux-distros list unless you already have a patch for the
+issue.
+
+**List rules.** The main rules to be aware of when contacting the
+linux-distros list are:
+
+* Don't post about issues that are already public. If your issue has a
+  public patch, but the security impact is not generally known, then you
+  may still post about it.
+
+* The submitter can suggest an embargo end-date, but as a rule, embargoes
+  should not be longer than 7 days, or at most 14 days in exceptional
+  cases. Keep in mind that vendors may prefer to release new kernel
+  packages and/or updates Tuesday through Thursday.
+
+* When the embargo ends, the issue must be disclosed immediately on
+  the oss-security list (see below).
+
+* Prefix your subject with the string "[vs]" to avoid getting rejected
+  by the spam filter.
+
+For the full list of rules, see:
+https://oss-security.openwall.org/wiki/mailing-lists/distros#list-policy-and-instructions-for-reporters
+
+**Confidentiality.** Please note that, as opposed to the security list, any
+and all material submitted to the list must be made public once the
+security issue is publicly disclosed, so please do not post information
+to the linux-distros list that cannot be made public.
+
+Contacting the oss-security list
+--------------------------------
+
+When your security issue is public, or you wish to make your issue public,
+you can write to the oss-security list (oss-security@lists.openwall.com).
+This is a public list (anybody can subscribe and view the list archives)
+and it is not restricted to Linux kernel issues.
+
+The oss-security list typically does not assign CVEs or accept requests for
+CVE assignments.
+
+**List rules.** Please do not cross-post to other lists when writing to
+this list. Make sure to read the other list rules before posting:
+https://oss-security.openwall.org/wiki/mailing-lists/oss-security
+.
+
+..
+    If you modify this document, please consider the following:
+    
+    1) The most important information should be at the top (preferably in
+    the opening paragraph). This means contacting <security@kernel.org>;
+    if somebody doesn't read any further than that, at least the security
+    team will have the report.
+    
+    2) Make the differences between the lists extremely clear. The old
+    version did make an attempt at this, but the lines were not drawn
+    clearly enough.
+    
+    3) Emphasize some of the posting rules which can be confusing to new
+    people (e.g. the fact that posting to linux-distros means you must
+    propose an embargo date and that this cannot under any circumstances
+    be more than 14 days).
+    
+    4) The document should be a "step-by-step process" as much as possible,
+    so that you can use it as a guide while reporting an issue instead of
+    having to search back and forth for the thing you're looking for.
-- 
2.35.1.46.g38062e73e0

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Jiri Kosina]

On Mon, 6 Jun 2022, Vegard Nossum wrote:

> The current instructions for reporting security vulnerabilities in the
> kernel are not clear enough, in particular the process of disclosure
> and requesting CVEs, and what the roles of the different lists are and
> how exactly to report to each of them.
> 
> Let's give this document an overhaul. Goals are stated as a comment at
> the bottom of the document; these will not appear in the rendered HTML
> document.
> 
> v2: address feedback from Willy Tarreau and Jonathan Corbet
> 
> Link: https://seclists.org/oss-sec/2022/q2/133
> Cc: Amit Shah <aams@amazon.com>
> Cc: Dave Hansen <dave.hansen@linux.intel.com>
> Cc: David Woodhouse <dwmw@amazon.co.uk>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Gustavo A. R. Silva <gustavoars@kernel.org>
> Cc: Jiri Kosina <jkosina@suse.cz>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Kees Cook <keescook@chromium.org>
> Cc: Laura Abbott <labbott@kernel.org>
> Cc: Linus Torvalds <torvalds@linux-foundation.org>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Solar Designer <solar@openwall.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Thorsten Leemhuis <linux@leemhuis.info>
> Cc: Tyler Hicks <tyhicks@linux.microsoft.com>
> Cc: Will Deacon <will@kernel.org>
> Cc: Willy Tarreau <w@1wt.eu>
> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
> ---
>  Documentation/admin-guide/security-bugs.rst | 252 +++++++++++++-------
>  1 file changed, 167 insertions(+), 85 deletions(-)
> 
> v1 thread:
> https://lore.kernel.org/all/20220531230309.9290-1-vegard.nossum@oracle.com/T/#u
> 
> Updated rendered HTML:
> https://vegard.github.io/security/Documentation/output/admin-guide/security-bugs-v2.html
> 
> diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
> index 82e29837d5898..c63eeb1e89ffd 100644
> --- a/Documentation/admin-guide/security-bugs.rst
> +++ b/Documentation/admin-guide/security-bugs.rst

Thanks for investing time into fixing this aged document.

Two rather minor things come to my mind, but as you are touching that 
document anyway ...

- what sense does it make to have embargoed-hardware-issues.rst and 
  security-bugs.rst live in different Documentation/ subdirectories 
  (admin-guide/ vs process/)? It'd seem to make sense to me to have them 
  in one common place?

- would it make sense to briefly reference embargoed-hardware-issues.rst 
  somewhere in this text, to make the distinction as obvious as possible? 
  It's referenced the other way around.

Thanks,

-- 
Jiri Kosina
SUSE Labs

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Will Deacon]

Hi,

On Mon, Jun 06, 2022 at 09:48:50PM +0200, Vegard Nossum wrote:
> The current instructions for reporting security vulnerabilities in the
> kernel are not clear enough, in particular the process of disclosure
> and requesting CVEs, and what the roles of the different lists are and
> how exactly to report to each of them.
> 
> Let's give this document an overhaul. Goals are stated as a comment at
> the bottom of the document; these will not appear in the rendered HTML
> document.
> 
> v2: address feedback from Willy Tarreau and Jonathan Corbet
> 
> Link: https://seclists.org/oss-sec/2022/q2/133
> Cc: Amit Shah <aams@amazon.com>
> Cc: Dave Hansen <dave.hansen@linux.intel.com>
> Cc: David Woodhouse <dwmw@amazon.co.uk>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Cc: Gustavo A. R. Silva <gustavoars@kernel.org>
> Cc: Jiri Kosina <jkosina@suse.cz>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Kees Cook <keescook@chromium.org>
> Cc: Laura Abbott <labbott@kernel.org>
> Cc: Linus Torvalds <torvalds@linux-foundation.org>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Cc: Solar Designer <solar@openwall.com>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Thorsten Leemhuis <linux@leemhuis.info>
> Cc: Tyler Hicks <tyhicks@linux.microsoft.com>
> Cc: Will Deacon <will@kernel.org>
> Cc: Willy Tarreau <w@1wt.eu>
> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
> ---
>  Documentation/admin-guide/security-bugs.rst | 252 +++++++++++++-------
>  1 file changed, 167 insertions(+), 85 deletions(-)
> 
> v1 thread:
> https://lore.kernel.org/all/20220531230309.9290-1-vegard.nossum@oracle.com/T/#u
> 
> Updated rendered HTML:
> https://vegard.github.io/security/Documentation/output/admin-guide/security-bugs-v2.html
> 
> diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst
> index 82e29837d5898..c63eeb1e89ffd 100644
> --- a/Documentation/admin-guide/security-bugs.rst
> +++ b/Documentation/admin-guide/security-bugs.rst
> @@ -1,96 +1,178 @@
> +
>  .. _securitybugs:
>  
> -Security bugs
> -=============
> +Reporting 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.
> -
> -Contact
> --------
> -
> -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.
> -
> -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.
> -
> -Please send plain text emails without attachments where possible.
> -It is much harder to have a context-quoted discussion about a complex
> -issue if all the details are hidden away in attachments.  Think of it like a
> -:doc:`regular patch submission <../process/submitting-patches>`
> -(even if you don't have a patch yet): describe the problem and impact, list
> +Linux kernel security team at security@kernel.org, henceforth "the
> +security list". This is a closed list of trusted developers who will
> +help verify the bug report and develop a patch in case none was already
> +proposed.
> +
> +While the security list is closed, the security team may bring in
> +extra help from the relevant maintainers to understand and fix the
> +security vulnerability.
> +
> +Note that the main interest of the kernel security list is in getting
> +bugs fixed and getting patches reviewed, tested, and merged; CVE
> +assignment, disclosure to distributions, and public disclosure happen
> +on different lists with different people, as described below.
> +
> +Here is a quick overview of the various lists:
> +
> + =============================== ===== =================== ===============
> + List address                    Open? Purpose             Members
> + =============================== ===== =================== ===============
> + security@kernel.org                no | Reporting         Trusted kernel
> +                                       | Patch development developers
> + ------------------------------- ----- ------------------- ---------------
> + linux-distros@vs.openwall.org      no | Coordination      Distribution
> +                                       | CVE assignment    representatives
> +                                       | Backporting
> +                                       | Testing
> + ------------------------------- ----- ------------------- ---------------
> + oss-security@lists.openwall.com   yes | Disclosure        General public
> + =============================== ===== =================== ===============
> +
> +The following sections give a step-by-step guide to reporting and
> +disclosure.
> +
> +Contacting the security list
> +----------------------------
> +
> +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. Reporters are encouraged to propose patches, participate
> +in the discussions of a fix, and test patches.
> +
> +The security team does not assign CVEs, nor does it require them
> +for reports or fixes. CVEs may be requested when the issue is reported to
> +the linux-distros list.
> +
> +**Disclosure.** The security list strongly prefers to have patches posted
> +for review and testing on public mailing lists and and merged into the

typo: "and and"

> +appropriate public git repository as soon as they become available.
> +However, in exceptional cases, you or an affected party may request that
> +the patch be withheld for some days; as a rule, the maximum is 7 days.
> +Only in truly exceptional cases will the security list consider deferring
> +the publication of a fix beyond this, and the only valid reason for doing
> +so would be to accommodate the logistics of QA and large scale rollouts
> +that require release coordination.

I think there's a semantic change here, and I tend to feel that these sort
of changes would be much easier to review if the semantic changes were done
separately from the reformatting or the addition of entirely new sections.
As it stands, the whole doc is effectively being replaced, but what we
currently have has been tweaked over the years (often as a result of
spirited debate) and I'm keen not to open up some of the issues we had
previously if at all possible.

Case in point: the new text above removes both the mention of "calendar
days" which is a useful disambiguation as well as removing the "extension
to 14 calendar days" which is a useful upper bound. Why are you removing
these?

You have also removed use of the term "robust fix", which I think was
useful. That is, security@ isn't going to post a broken patch to the public
list just because it's been available for 7 days; that period should only
begin (if it is even needed) once the fix is ready to go.

Thanks,

Will

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Vegard Nossum]

On 6/7/22 11:07, Will Deacon wrote:
> On Mon, Jun 06, 2022 at 09:48:50PM +0200, Vegard Nossum wrote:
>> +**Disclosure.** The security list strongly prefers to have patches posted
>> +for review and testing on public mailing lists and and merged into the
> 
> typo: "and and"

Fixed, thanks.

>> +appropriate public git repository as soon as they become available.
>> +However, in exceptional cases, you or an affected party may request that
>> +the patch be withheld for some days; as a rule, the maximum is 7 days.
>> +Only in truly exceptional cases will the security list consider deferring
>> +the publication of a fix beyond this, and the only valid reason for doing
>> +so would be to accommodate the logistics of QA and large scale rollouts
>> +that require release coordination.
> 
> I think there's a semantic change here, and I tend to feel that these sort
> of changes would be much easier to review if the semantic changes were done
> separately from the reformatting or the addition of entirely new sections.
> As it stands, the whole doc is effectively being replaced, but what we
> currently have has been tweaked over the years (often as a result of
> spirited debate) and I'm keen not to open up some of the issues we had
> previously if at all possible.

My goal with the rewrite was to clarify the policy for reporters,
include the updates to linux-distros policy, and turn the document into
more of a step-by-step guide for reporters that corresponds to both what
happens in reality and what the "ideal" flow for a security bug report
is. It's not my intention here to modify the policy itself.

My impression of the current document is that it's a little bit chaotic
and difficult to follow -- perhaps exactly because of tweaking over the
years rather than writing for the reader/reporter.

> Case in point: the new text above removes both the mention of "calendar
> days" which is a useful disambiguation as well as removing the "extension
> to 14 calendar days" which is a useful upper bound. Why are you removing
> these?

"calendar days" -- this got changed just to make it more readable. Maybe
it's just me and my personal experience, but this wording seemed
redundant. Why would "day" default to anything but a calendar day except
in a business setting (which this is not)?

That said, I agree if this has been contentious in the past there is
value in being explicit. My goal was maximum clarity, so if this could
be unclear to anybody then it's better to leave it in -- however, if I
leave it in, then I should also change all other occurrences of the word
"days" to also be "calendar days" so that the reader is not left
wondering why it's specified as calendar days in one place and
unspecified in another.

"extension to 14 calendar days" -- I changed this after comments from
Willy who said too many people took this to mean that 7 days was the
norm and that 14 days was still an acceptable proposal in most cases. I
_think_ (but I'm not sure) that 14 days is not even really the absolute
maximum, depending on the severity of the bug.

In my mind, this document is more for reporters of security issues and
less a formal standard for the security list members and so the "Only in
truly exceptional cases will the security list consider deferring the
publication of a fix beyond this" already covers what happens if
somebody wants or request that the patch be withheld for more than 7
days -- it's basically up to the list members to decide whether to
honour requests beyond the stated maximum.

Any new thoughts with all this in mind..?

> You have also removed use of the term "robust fix", which I think was
> useful. That is, security@ isn't going to post a broken patch to the public
> list just because it's been available for 7 days; that period should only
> begin (if it is even needed) once the fix is ready to go.

Okay, how about changing it like this:

-**Disclosure.** The security list strongly prefers to have patches posted
-for review and testing on public mailing lists and and merged into the
-appropriate public git repository as soon as they become available.
+**Disclosure.** When a robust patch or patchset has been developed, the
+security list strongly prefers to have these posted for review and testing
+on public mailing lists and merged into the appropriate public git
+repository as soon as possible.

It's always possible to go into more detail about what "robust" means
exactly or who makes this decision (and how), but I think brevity does a
lot to keep things readable.

Thanks for the comments.


Vegard

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Jonathan Corbet]

Jiri Kosina <jikos@kernel.org> writes:

> - what sense does it make to have embargoed-hardware-issues.rst and 
>   security-bugs.rst live in different Documentation/ subdirectories 
>   (admin-guide/ vs process/)? It'd seem to make sense to me to have them 
>   in one common place?

Yes, I think that would make sense...a lot of stuff got sorted out into
the various guides quickly, and it didn't all land in the right place.
I'd be in favor of moving this over to the process guide, and perhaps
making a security-specific section there.

Thanks,

jon

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Willy Tarreau]

On Tue, Jun 07, 2022 at 07:30:10AM -0600, Jonathan Corbet wrote:
> Jiri Kosina <jikos@kernel.org> writes:
> 
> > - what sense does it make to have embargoed-hardware-issues.rst and 
> >   security-bugs.rst live in different Documentation/ subdirectories 
> >   (admin-guide/ vs process/)? It'd seem to make sense to me to have them 
> >   in one common place?
> 
> Yes, I think that would make sense...a lot of stuff got sorted out into
> the various guides quickly, and it didn't all land in the right place.
> I'd be in favor of moving this over to the process guide, and perhaps
> making a security-specific section there.

I, too, regularly search for it in process/, fail to find it then use
"find" to spot it under admin... Process seems more suitable to me at
least.

Willy

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Will Deacon]

On Tue, Jun 07, 2022 at 03:06:37PM +0200, Vegard Nossum wrote:
> On 6/7/22 11:07, Will Deacon wrote:
> > On Mon, Jun 06, 2022 at 09:48:50PM +0200, Vegard Nossum wrote:
> >> +**Disclosure.** The security list strongly prefers to have patches posted
> >> +for review and testing on public mailing lists and and merged into the
> > 
> > typo: "and and"
> 
> Fixed, thanks.
> 
> >> +appropriate public git repository as soon as they become available.
> >> +However, in exceptional cases, you or an affected party may request that
> >> +the patch be withheld for some days; as a rule, the maximum is 7 days.
> >> +Only in truly exceptional cases will the security list consider deferring
> >> +the publication of a fix beyond this, and the only valid reason for doing
> >> +so would be to accommodate the logistics of QA and large scale rollouts
> >> +that require release coordination.
> > 
> > I think there's a semantic change here, and I tend to feel that these sort
> > of changes would be much easier to review if the semantic changes were done
> > separately from the reformatting or the addition of entirely new sections.
> > As it stands, the whole doc is effectively being replaced, but what we
> > currently have has been tweaked over the years (often as a result of
> > spirited debate) and I'm keen not to open up some of the issues we had
> > previously if at all possible.
> 
> My goal with the rewrite was to clarify the policy for reporters,
> include the updates to linux-distros policy, and turn the document into
> more of a step-by-step guide for reporters that corresponds to both what
> happens in reality and what the "ideal" flow for a security bug report
> is. It's not my intention here to modify the policy itself.

Oh, for-sure, I'm not trying to suggest there's any malice involved here.
Rather, my heart sinks at the prospect of reopening old (and, frankly,
tedious) discussions around the finer details of what is in that doc.

> My impression of the current document is that it's a little bit chaotic
> and difficult to follow -- perhaps exactly because of tweaking over the
> years rather than writing for the reader/reporter.

That's a fair criticism, but a straight-up rewrite won't solve that imo; the
thing will still get tweaked until the next rewrite comes along etc etc

> > Case in point: the new text above removes both the mention of "calendar
> > days" which is a useful disambiguation as well as removing the "extension
> > to 14 calendar days" which is a useful upper bound. Why are you removing
> > these?
> 
> "calendar days" -- this got changed just to make it more readable. Maybe
> it's just me and my personal experience, but this wording seemed
> redundant. Why would "day" default to anything but a calendar day except
> in a business setting (which this is not)?

In the past, people were unclear as to whether this included weekends,
public holidays etc and so being explicit helps.

> That said, I agree if this has been contentious in the past there is
> value in being explicit. My goal was maximum clarity, so if this could
> be unclear to anybody then it's better to leave it in -- however, if I
> leave it in, then I should also change all other occurrences of the word
> "days" to also be "calendar days" so that the reader is not left
> wondering why it's specified as calendar days in one place and
> unspecified in another.

Right, and I think _that_ would be a reviewable change on its own.

> "extension to 14 calendar days" -- I changed this after comments from
> Willy who said too many people took this to mean that 7 days was the
> norm and that 14 days was still an acceptable proposal in most cases. I
> _think_ (but I'm not sure) that 14 days is not even really the absolute
> maximum, depending on the severity of the bug.

The current text says:

 | ... an exceptional extension to 14 calendar days if it is agreed that
 | the criticality of the bug requires more time. The only valid reason
 | for deferring the publication of a fix is to accommodate the logistics
 | of QA and large scale rollouts which require release coordination.

which I think is pretty clear; it states the single criterion under which
an exceptional extension to 14 days will be considered. There's no mention
of this in the rewrite.

> In my mind, this document is more for reporters of security issues and
> less a formal standard for the security list members and so the "Only in
> truly exceptional cases will the security list consider deferring the
> publication of a fix beyond this" already covers what happens if
> somebody wants or request that the patch be withheld for more than 7
> days -- it's basically up to the list members to decide whether to
> honour requests beyond the stated maximum.
> 
> Any new thoughts with all this in mind..?

I think the document provides a useful set of "ground rules" which mean
that reporters can engage with security@ with a reasonable expectation
of how the process is going to go ahead of time. I'm all for reworking
phrasing, stylistic changes and adding extra information to make the
document more useful, but I really don't think a rewrite is warranted.
It will cause more problems than it solves. Please work with the text
that is already there instead.

> > You have also removed use of the term "robust fix", which I think was
> > useful. That is, security@ isn't going to post a broken patch to the public
> > list just because it's been available for 7 days; that period should only
> > begin (if it is even needed) once the fix is ready to go.
> 
> Okay, how about changing it like this:
> 
> -**Disclosure.** The security list strongly prefers to have patches posted
> -for review and testing on public mailing lists and and merged into the
> -appropriate public git repository as soon as they become available.
> +**Disclosure.** When a robust patch or patchset has been developed, the
> +security list strongly prefers to have these posted for review and testing
> +on public mailing lists and merged into the appropriate public git
> +repository as soon as possible.

This isn't addressing my concern. The current document is clear that any
agreed embargo begins only from the point where we have a robust fix:

  | Once a robust fix has been developed, the release process starts.

This is important -- if distributions mistakenly think that they have a
maximum of seven days to describe the problem, involve the right people,
iterate on a patch, backport it, test it and deploy it then they'll do
all of this in private and just notify security@ at the end, at which
point it's either a waste of time or the patch is found not to be as
robust as they thought because the right people weren't involved.

> It's always possible to go into more detail about what "robust" means
> exactly or who makes this decision (and how), but I think brevity does a
> lot to keep things readable.

What exactly is unreadable with the current doc?

Will

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Willy Tarreau]

A few quick points below.

On Thu, Jun 09, 2022 at 03:51:27PM +0100, Will Deacon wrote:
> > "calendar days" -- this got changed just to make it more readable. Maybe
> > it's just me and my personal experience, but this wording seemed
> > redundant. Why would "day" default to anything but a calendar day except
> > in a business setting (which this is not)?
> 
> In the past, people were unclear as to whether this included weekends,
> public holidays etc and so being explicit helps.

In fact that's often the problem between what is known from insiders
and what is understood outside. The original 5 days used to allow to
include a Monday's fix into the Sunday's -rc. It then extended to 7
days to improve the likelyhood that participants involved the first
day were available on the release day, but that was always implicitly
"calendar days" or at least reminded as such during private discussions.
But with more and more professionals reporting bugs as part of their
job, the risk that this is implicitly understood with work days is much
more present nowadays and I think it's worth being explicit here.

> > "extension to 14 calendar days" -- I changed this after comments from
> > Willy who said too many people took this to mean that 7 days was the
> > norm and that 14 days was still an acceptable proposal in most cases. I
> > _think_ (but I'm not sure) that 14 days is not even really the absolute
> > maximum, depending on the severity of the bug.
> 
> The current text says:
> 
>  | ... an exceptional extension to 14 calendar days if it is agreed that
>  | the criticality of the bug requires more time. The only valid reason
>  | for deferring the publication of a fix is to accommodate the logistics
>  | of QA and large scale rollouts which require release coordination.
> 
> which I think is pretty clear; it states the single criterion under which
> an exceptional extension to 14 days will be considered. There's no mention
> of this in the rewrite.

Indeed, it's important to keep that sentence to make sure reporters do
not count on that upfront.

> The current document is clear that any
> agreed embargo begins only from the point where we have a robust fix:
> 
>   | Once a robust fix has been developed, the release process starts.
> 
> This is important -- if distributions mistakenly think that they have a
> maximum of seven days to describe the problem, involve the right people,
> iterate on a patch, backport it, test it and deploy it then they'll do
> all of this in private and just notify security@ at the end, at which
> point it's either a waste of time or the patch is found not to be as
> robust as they thought because the right people weren't involved.

This part is particularly important and is indeed at the core of some
of the recent trouble. We need to make it clearer that it can take more
time to develop a fix, possibly adding more and more people, but that
once the fix is confirmed, the process starts and the only reason for
an embargo is QA/rollout (which explains why there's no reason for a
long embargo since everything is ready). But that brings back the
concern that if we suggest that the reporter contacts linux-distros
after the fix is ready, he may be bound by a 2-week embargo (unless
it's fine to cut it to one week max by default). We need to make sure
to limit friction because many reporters are first-timers and it's
really unpleasant for them to be bounced between lists with different
policies and being told they can't ask for this or that.

> > It's always possible to go into more detail about what "robust" means
> > exactly or who makes this decision (and how), but I think brevity does a
> > lot to keep things readable.
> 
> What exactly is unreadable with the current doc?

I don't think there's anything unreadable, however both you (Will)
and me are on the list and have implicit knowledge of certain things.
Vegard is not and his perception is useful because it's closer to the
one from a reporter who tries to find their way through all this. Even
a feeling like "it's too difficult to grasp" can be listened to IMHO.

Just my two cents,
Willy

Re: [PATCH v2] Documentation/security-bugs: overhaul

[Vegard Nossum]

On 6/9/22 16:51, Will Deacon wrote:
> On Tue, Jun 07, 2022 at 03:06:37PM +0200, Vegard Nossum wrote:
>> On 6/7/22 11:07, Will Deacon wrote:
>>> I think there's a semantic change here, and I tend to feel that these sort
>>> of changes would be much easier to review if the semantic changes were done
>>> separately from the reformatting or the addition of entirely new sections.
>>> As it stands, the whole doc is effectively being replaced, but what we
>>> currently have has been tweaked over the years (often as a result of
>>> spirited debate) and I'm keen not to open up some of the issues we had
>>> previously if at all possible.
>>
>> My goal with the rewrite was to clarify the policy for reporters,
>> include the updates to linux-distros policy, and turn the document into
>> more of a step-by-step guide for reporters that corresponds to both what
>> happens in reality and what the "ideal" flow for a security bug report
>> is. It's not my intention here to modify the policy itself.
> 
> Oh, for-sure, I'm not trying to suggest there's any malice involved here.
> Rather, my heart sinks at the prospect of reopening old (and, frankly,
> tedious) discussions around the finer details of what is in that doc.
> 
>> My impression of the current document is that it's a little bit chaotic
>> and difficult to follow -- perhaps exactly because of tweaking over the
>> years rather than writing for the reader/reporter.
> 
> That's a fair criticism, but a straight-up rewrite won't solve that imo; the
> thing will still get tweaked until the next rewrite comes along etc etc

[...]

> What exactly is unreadable with the current doc?

Lots of people have been confused about the 7/14 days of the kernel list
vs. the 7/14 days of the distros list, the fact that these are two
separate groups, etc. Many reporters contact distros first, or submit
their report to both lists at the same time (which has the unfortunate
effect of starting off the disclosure countdown for the distros list
before s@k.o has had a chance to look at the report). I've since shared
the updated doc with a couple of people who submitted reports and they
said they found it a lot clearer.

I've split my changes into a series of 7 patches and reverted some of
the wording back to the original document in the cases where you thought
the original was clearer or the semantics had changed -- will send it
out shortly.

Thanks for your comments so far.


Vegard