From d36261c4665835b9a3bd84ddea4816fb0a207af2 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 12:38:14 -0400 Subject: [PATCH 01/15] Remove stray "TL/DL" with bogus header Remove weird heading-1 "TL/DL" line which doesn't belong there. Maybe it was supposed to be "TLDR", but it's still wrong, and it's the wrong heading level anyway (this uses heading1=title). Removing it seems like the best course. Signed-off-by: David A. Wheeler --- guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guide.md b/guide.md index aca5133..88bbbc3 100644 --- a/guide.md +++ b/guide.md @@ -21,9 +21,8 @@ ## Before you begin -# TL/DL -This guide is intended to help open source projects and maintainers create and maintain a coordinated vulnerability response process. +This guide is intended to help open source projects and maintainers create and maintain a coordinated vulnerability response process. No software is perfect. Software is written by people (at least today) and people sometimes make mistakes. This is true for closed source as well as open source software. For open source software (OSS) this problem can be more challenging due to the very factors that make OSS so powerful - From cf290e0d8dcf2b40b33934714652d064b52783da Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 12:53:16 -0400 Subject: [PATCH 02/15] Various small tweaks Fixed some spelling errors, removed trailing spaces, and inserted a definition of "vulnerability reporter" (which was oddly missing). Signed-off-by: David A. Wheeler --- guide.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/guide.md b/guide.md index 88bbbc3..d49ebb2 100644 --- a/guide.md +++ b/guide.md @@ -24,10 +24,10 @@ This guide is intended to help open source projects and maintainers create and maintain a coordinated vulnerability response process. -No software is perfect. Software is written by people (at least today) and people sometimes make mistakes. +No software is perfect. Software is written by people (at least today) and people sometimes make mistakes. This is true for closed source as well as open source software. For open source software (OSS) this problem can be more challenging due to the very factors that make OSS so powerful - highly distributed development by multiple contributors. -At some point in the life of your project, someone--a user, a contributor, or a security researcher--will find a vulnerability that affects the safety and usefulness of your project. +At some point in the life of your project, someone--a user, a contributor, or a security researcher--will find a vulnerability that affects the safety and usefulness of your project. @@ -40,23 +40,22 @@ The OpenSSF Vulnerability Disclosure Working Group believes coordinated vulnerab -### Who's a vulnerability reporter (aka "Finder")? +### Who's a vulnerability reporter (aka "finder")? -There’s no single example of how security issues are reported, or why people report them. That’s one of the things that can make vulnerability management and disclosure tricky: the human on the other side is, well, a human, who has their own wants, needs, and interests out of a vulnerability disclosure. This is one reason why the phrase “coordinated vulnerability disclosure” (CVD) is now preferred over “responsible disclosure.” There are two parties involved (or more depending on the situation), and you need to *coordinate and work together!* - -The OpenSSF Vulnerability Disclosure working group uses [personas](https://en.wikipedia.org/wiki/Persona_(user_experience)) to describe persons/roles that interact within the CVD process. A vulnerabilty reporter is called a [Finder](https://github.com/ossf/wg-vulnerability-disclosures/blob/main/docs/personas.md#finder) within the security community. This category represents many different diverse and divergent desires around reporting a security vulnerability to a developer. +A vulnerability reporter, aka finder, is someone who reports a vulnerability to a project. There’s no single example of how security issues are reported, or why people report them. That’s one of the things that can make vulnerability management and disclosure tricky: the human on the other side is, well, a human, who has their own wants, needs, and interests out of a vulnerability disclosure. This is one reason why the phrase “coordinated vulnerability disclosure” (CVD) is now preferred over “responsible disclosure.” There are at least two parties involved, the reporter(s) and project representative(s), and you need to *coordinate and work together!* +The OpenSSF Vulnerability Disclosure working group uses [personas](https://en.wikipedia.org/wiki/Persona_(user_experience)) to describe persons/roles that interact within the CVD process. A vulnerability reporter is one of those personas and is often called a [finder](https://github.com/ossf/wg-vulnerability-disclosures/blob/main/docs/personas.md#finder) within the security community. This reporter persona represents many different diverse and divergent desires around reporting a security vulnerability to a developer. *Very* broadly, reporters fall into two camps: those with a direct connection to the project, and those with an indirect connection. Direct reporters are active users of the project, or were hired to do work on behalf of a direct user. Because they are direct users, they have a strong motivation for an issue to be patched and smoothly rolled out. They might *want* to help develop and test a patch—they have a reason to see this through to a fix. Indirect reporters may be security researchers, people doing penetration testing or security audits, or may stumble across an issue in your project as the result of chasing an issue in a dependent project. They may want to be highly involved in the patching and disclosure process, including coordinating publicity for their work, or they may just want to send over the issue and not be involved further. -**Finders have done your project a favor by telling you about a vulnerability.** -Finders will have any number of possibly complex motivations and desires in reporting a potential vulnerability to a project. +**Reporters have done your project a favor by telling you about a vulnerability.** +Reporters will have any number of possibly complex motivations and desires in reporting a potential vulnerability to a project. Unfortunately, there are incentives to not report vulnerabilities, sometimes including cash. -Having clearly established expecations around vulnerability reporting and the project's triage and handling practices will help eliminate friction as the issue moves forward towards resolution. +Having clearly established expectations around vulnerability reporting and the project's triage and handling practices will help eliminate friction as the issue moves forward towards resolution. Ultimately the goal of using CVD is to reduce the risk to [Consumers](https://github.com/ossf/wg-vulnerability-disclosures/blob/main/docs/personas.md#consumer) of that software. @@ -69,14 +68,14 @@ It's important to be ready for a vulnerability report *before* you get a report. ======= -### Establish project's vulnerability handling expecations (aka "Security Policy") +### Establish project's vulnerability handling expectations (aka "Security Policy") -Every project has different goals, capabilities, and norms. A critical first step to addressing security vulnerabilities is to share with any downstream consumers or collaborators on how the project will take in vulnerability reports and what a reporter's expecations of communication and response should be. Larger, more experienced projects will possibly have a dedicated team (see VMT below) of security specialists that have experience within open source of fixing security bugs. Small-to-medium sized projects most likely will not have access to these trained professionals or that type of work is simply out of their scope. It is important to understand that all software will have defects, some of those defects will have security impacting aspects (impacting data's confidentiality, integrity, availability, or auditability) and a small bit of preparation at the start of a project can ensure the team talks about and documents what tehy will do when these types of reports arise. +Every project has different goals, capabilities, and norms. A critical first step to addressing security vulnerabilities is to share with any downstream consumers or collaborators on how the project will take in vulnerability reports and what a reporter's expectations of communication and response should be. Larger, more experienced projects will possibly have a dedicated team (see VMT below) of security specialists that have experience within open source of fixing security bugs. Small-to-medium sized projects most likely will not have access to these trained professionals or that type of work is simply out of their scope. It is important to understand that all software will have defects, some of those defects will have security impacting aspects (impacting data's confidentiality, integrity, availability, or auditability) and a small bit of preparation at the start of a project can ensure the team talks about and documents what they will do when these types of reports arise. -Processes and tooling do not need to be complex and burdensome to the maintainers and contributors, but the following should be clearly documented by the project to ensure a reporter can get the bug report to the responsible developers: +Processes and tooling do not need to be complex and burdensome to the maintainers and contributors, but the following should be clearly documented by the project to ensure a reporter can get the bug report to the responsible developers: - How to contact the team about a potential security vulnerability - The vulnerability report can be kept private until such time the project decides to share more broadly -- The reporter's expecations on communication/collaboration around the issue are properly set +- The reporter's expectations on communication/collaboration around the issue are properly set An example template for open source projects for a basic security policy can be found within this OpenSSF repository. Projects are able to reuse it with a few minimal changes or borrow any elements useful to them in their existing documentation. @@ -151,7 +150,7 @@ Later sections will cover how to determine if something is a security issue, a r You have a decision to make: Will you use the GitHub Security Advisory feature to do private development of a patch? Based on the feature set of GitHub Security Advisory at the time of writing, **our recommendation is that if you are a project using GitHub, you should typically use the private development features to generate your patch there.** -**Pros:** Keeps all development within one platform, easy to add external contributors (eg the reporter, or other experts who can help with patching), when the vulnerability is disclosed, it is easy to flip the work from “private” to “public.” +**Pros:** Keeps all development within one platform, easy to add external contributors (e.g., the reporter, or other experts who can help with patching), when the vulnerability is disclosed, it is easy to flip the work from “private” to “public.” **Cons:** One problem with private development is that you will not be able to get widespread feedback of your change; as a result, the fix may not truly fix the problem and/or have bad unintended consequences. If the vulnerability is *already* publicly known and widely exploited, there's no advantage to trying to keep things private. In the case where the vulnerability is already widely known publicly, it may be better to develop the fix in public as well (where you may get more people to help and more feedback). From 29fed5f4aa5ff029c9b5c83c1cf97160e2796e2f Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 17:06:28 -0400 Subject: [PATCH 03/15] Fix spelling of "vulnerability" Signed-off-by: David A. Wheeler --- guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide.md b/guide.md index d49ebb2..d398264 100644 --- a/guide.md +++ b/guide.md @@ -226,7 +226,7 @@ See [`Runbook.md`]( https://github.com/ossf/oss-vulnerability-guide/blob/main/ru | Feature request | Let the reporter know this is the intended behavior. If they think this behavior could be improved, they can file a feature request. Close the security issue. | | Vulnerability | Let the reporter know that you have confirmed this is unwanted behavior that creates a security issue. Proceed with process. | -3. **Discuss embargo period with vulnerabilty reporter** +3. **Discuss embargo period with vulnerability reporter** Vulnerability reporters will typically state the embargo period they're willing to accept. The "embargo period" is the time where the vulnerability report is kept from the public, enabling the project to repond, fix, and publicly disclose the vulnerability themselves. This may or may not be the embargo period requested by the project. There are different recommendations and norms about embargo periods among different groups: From 512c033cdf362ee58841d589b6ba30099d19848f Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 17:11:19 -0400 Subject: [PATCH 04/15] Parallelize "Setting up the vulnerability management infrastructure" The subheadings of the second section had wildly different grammar types. Make them all verb-object. Signed-off-by: David A. Wheeler --- guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide.md b/guide.md index d398264..0a3f602 100644 --- a/guide.md +++ b/guide.md @@ -7,10 +7,10 @@ * **[Setting up the vulnerability management "infrastructure"](#setting-up-the-vulnerability-management-infrastructure)** * [Create a vulnerability management team (VMT)](#create-a-vulnerability-management-team-vmt) * [Set up report intake](#set-up-report-intake) - * [Private patch development](#private-patch-development) + * [Enable private patch development](#enable-private-patch-development) * [Establish a CNA contact](#establish-a-cna-contact) - * [Embargo lists](#embargo-list) - * [Communication templates](#communication-templates) + * [Create an embargo list](#create-an-embargo-list) + * [Select communication templates](#select-communication-templates) * **[The vulnerability response process](#the-vulnerability-response-process)** * [Runbook](#runbook) * [Response process](#response-process) @@ -142,7 +142,7 @@ Even if you have an issue tracker, state an email address available as an altern We recommend using an email service for accepting vulnerability reports (such as security@PROJECTNAME) that supports hop-to-hop encryption using STARTTLS. Examples of such systems include Gmail, Outlook.com, and runbox.com. Your email client should use encryption to communicate with your email system (i.e., if you use a web-based email client then use HTTPS, and if you use email client software then configure it to use encryption). Hop-to-hop encryption isn't as strong as end-to-end encryption, but many users find it too difficult today to use end-to-end encryption, and it's more important to *get* the vulnerability report. -### Private patch development +### Enable private patch development Later sections will cover how to determine if something is a security issue, a regular issue, and something that you will patch privately and then disclose. If it is a security issue and you will be issuing a patch, you will need a way to privately develop and test your work. If you test a particular patch in public, an observant attacker may see the exploitability, and exploit the vulnerability before you’re able to issue a patch. @@ -175,7 +175,7 @@ There are many issue trackers that are able to separate security issues from reg CNAs ([CVE Numbering Authorities](https://cve.mitre.org/cve/request_id.html)) are organizations who can assign CVE numbers to new vulnerabilities. CNAs have various scopes, and do not issue CVEs outside of their scopes. (e.g., While the (fictitious) SpeakerCompany uses open source software in their products, their scope could be restricted to vulnerabilities only found in SpeakerCompany software, and they would not handle a CVE request for an upstream issue.) There are many CNAs; the only “pre-work” for the VMT is to know of at least one CNA whose scope covers your project and who you will go to first for a CVE assignment. MITRE, the organization that manages CVE administration, is also a [“CNA of Last Resort” for open source projects](https://cveform.mitre.org/), and can be used if no better scope is available. -### Embargo list +### Create an embargo list **TL;DR:** Embargoed notification requires careful administration and management, adds additional responsibility for the VMT, and adds time to the disclosure process. Unless your project has a significant vendor ecosystem, embargoed notification is probably not necessary. @@ -188,7 +188,7 @@ Using an embargoed notification is not without risk. An embargoed notification i If an embargo list is relevant to your project, you will want to create a restricted, read-only announcement list that is administered by your VMT. The VMT is responsible for approving access requests and maintaining an accurate list (e.g. removing outdated members), but it is the provider’s responsibility to request access to your list. List the requirements and directions for requesting access in your security documentation. -### Communication templates +### Select communication templates The more you have pre-written, the less there is to do when you have an issue to respond to. [See the `Templates` directory](https://github.com/ossf/oss-vulnerability-guide/tree/main/templates) for security policy (`SECURITY.md`), embargoed notification, and public disclosure templates. From 13c59e7a6e656905c612caf6691c9781b24f9a77 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 17:20:47 -0400 Subject: [PATCH 05/15] What about withholding info after fix is posted? Briefly discuss withholding info about the vulnerability fix has been posted. Signed-off-by: David A. Wheeler --- guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide.md b/guide.md index 0a3f602..0faa6bd 100644 --- a/guide.md +++ b/guide.md @@ -276,7 +276,7 @@ See [`Runbook.md`]( https://github.com/ossf/oss-vulnerability-guide/blob/main/ru It’s recommended to also send the announcement to appropriate mailing lists for your community (i.e. a security-announce@ list, and even a general mailing list for high impact vulnerabilities). - + Once you release the update, detailed information about the vulnerability is essentially released to the public. You might choose to briefly withold details about how the vulnerability can be exploited, in the hopes that this will give users a little more time to update before attackers begin exploiting the vulnerability. This only makes sense if it's not obvious to attackers how the vulnerability can be exploited, and in most cases attackers will find it obvious. In addition, attackers can usually review changes made to software (in source or executable form) and easily determine an attack. Thus, withholding detailed information can only be helpful for a few days at most, even in the few cases where it helps at all. ## Publishing your vulnerability management process From f54629f6a0ed120b5fd8f10404b9819097582d36 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 17:31:03 -0400 Subject: [PATCH 06/15] Others services don't always use git Git is extremely popular, but not the only VCS in use. We should provide general guidance, & then specifics for common cases. Signed-off-by: David A. Wheeler --- guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide.md b/guide.md index 0faa6bd..c3d83e0 100644 --- a/guide.md +++ b/guide.md @@ -122,7 +122,7 @@ The vulnerability reporter is doing you a favor; don’t add more steps than abs ##### If you are using GitHub -GitHub Security Advisory is a GitHub feature that allows *only* selected users to privately share information about reported issues, develop patches on a private branch, and publish a security advisory. If you plan to use GitHub Security Advisory for private patch development, follow the directions below. Otherwise, follow the directions for [another git service](#git-for-intake). +GitHub Security Advisory is a GitHub feature that allows *only* selected users to privately share information about reported issues, develop patches on a private branch, and publish a security advisory. If you plan to use GitHub Security Advisory for private patch development, follow the directions below. Otherwise, follow the directions for [another service](#if-you-are-using-another-service). However, GitHub Security Advisory *cannot* today be a general-purpose intake method for vulnerability reports. The GitHub Security Advisory workflow starts when a repo or org admin opens a Security Advisory; general users cannot create a Security Advisory or create a private “security issue” out of a standard GitHub issue. Thus, currently GitHub Security Advisory *must* be supplemented with other intake mechanisms. @@ -136,7 +136,7 @@ If you are using an issue tracker to track security vulnerabilities (e.g., [Laun If you do not have an issue tracker with a security issue feature, you need an alternative method for intake. Your intake solution should restrict access to the content of the messages to verified identities (or at least verified email addresses), to counter being overwhelmed with spam. However, this solution also has to be accessible and low friction. Typically this will be an email address. -Even if you have an issue tracker, state an email address available as an alternative method of intake [can help make sure issues get to you.](https://googleprojectzero.blogspot.com/2018/08/adventures-in-vulnerability-reporting.html) +Even if you have an issue tracker, state an email address available as an alternative method of intake so you [can help make sure issues get to you](https://googleprojectzero.blogspot.com/2018/08/adventures-in-vulnerability-reporting.html). ##### Accepting vulnerability reports via email with hop-to-hop encryption @@ -160,7 +160,7 @@ If you need to test against hardware or systems not already included in your tes Running private mirrors can be done, but we do not recommend this as the default. If you run a private mirror for developing and testing security patches, you will want to have this set up and operational before you have a vulnerability report. -#### If you are using another git service +#### If you are using another service There are many issue trackers that are able to separate security issues from regular issues. Whatever tracker you select, the following features are strongly recommended for your vulnerability reporting system: From b4326ba60e9daafe8a4cf665ac82d588cf65fed5 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:11:56 -0400 Subject: [PATCH 07/15] Wrap up an intro paragraph Signed-off-by: David A. Wheeler --- guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/guide.md b/guide.md index c3d83e0..c32e379 100644 --- a/guide.md +++ b/guide.md @@ -28,6 +28,7 @@ No software is perfect. Software is written by people (at least today) and peopl This is true for closed source as well as open source software. For open source software (OSS) this problem can be more challenging due to the very factors that make OSS so powerful - highly distributed development by multiple contributors. At some point in the life of your project, someone--a user, a contributor, or a security researcher--will find a vulnerability that affects the safety and usefulness of your project. +Applying this guide will help you be ready. From b0ae01908365c9148b9bba70e54a379882563ff6 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:14:29 -0400 Subject: [PATCH 08/15] Remove unnecessary horizontal line I think this is a mistake that somehow carried over. Signed-off-by: David A. Wheeler --- guide.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guide.md b/guide.md index c32e379..6b16a34 100644 --- a/guide.md +++ b/guide.md @@ -67,8 +67,6 @@ It is important to thank reporters for taking the time to find the developer and It's important to be ready for a vulnerability report *before* you get a report. [Preparing to receive a vulnerability report is required to get a CII Best Practices badge](https://bestpractices.coreinfrastructure.org/criteria/0##vulnerability_report_process). This section explains how to get ready; the next sections will walk through how to actually handle a vulnerability report. - -======= ### Establish project's vulnerability handling expectations (aka "Security Policy") Every project has different goals, capabilities, and norms. A critical first step to addressing security vulnerabilities is to share with any downstream consumers or collaborators on how the project will take in vulnerability reports and what a reporter's expectations of communication and response should be. Larger, more experienced projects will possibly have a dedicated team (see VMT below) of security specialists that have experience within open source of fixing security bugs. Small-to-medium sized projects most likely will not have access to these trained professionals or that type of work is simply out of their scope. It is important to understand that all software will have defects, some of those defects will have security impacting aspects (impacting data's confidentiality, integrity, availability, or auditability) and a small bit of preparation at the start of a project can ensure the team talks about and documents what they will do when these types of reports arise. From 638b9ad5ac5fe536f7b0e4d1770699abae896255 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:15:52 -0400 Subject: [PATCH 09/15] Make TOC and heading text match Signed-off-by: David A. Wheeler --- guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide.md b/guide.md index 6b16a34..837339e 100644 --- a/guide.md +++ b/guide.md @@ -4,7 +4,7 @@ * **[Before you begin](#before-you-begin)** * [About this guide](#about-this-guide) * [Who's a vulnerability reporter?](#whos-a-vulnerability-reporter) -* **[Setting up the vulnerability management "infrastructure"](#setting-up-the-vulnerability-management-infrastructure)** +* **[Set up the vulnerability management *infrastructure*](#setting-up-the-vulnerability-management-infrastructure)** * [Create a vulnerability management team (VMT)](#create-a-vulnerability-management-team-vmt) * [Set up report intake](#set-up-report-intake) * [Enable private patch development](#enable-private-patch-development) From 87aa48e15ef422780dfc6a07e5fd7c10b8b7f188 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:19:21 -0400 Subject: [PATCH 10/15] Clarify which users are meant Signed-off-by: David A. Wheeler --- guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide.md b/guide.md index 837339e..0e94436 100644 --- a/guide.md +++ b/guide.md @@ -246,7 +246,7 @@ See [`Runbook.md`]( https://github.com/ossf/oss-vulnerability-guide/blob/main/ru In your assessment process, you should have identified what versions are affected. As you prepare your patch, take note of backwards compatibility and upgrade requirements (for example: v1.0.0 is affected, but the patch is not compatible, and users will need to upgrade to v1.7.0 or above to apply the patch). You will need to communicate these details in your disclosure announcements. - When creating a patch, it is *vital* that it be *easy* to users to update (at least users if they're using the most recent release of the software). Your change should not require the users to use a different API, or eliminate user functionality, unless that is *absolutely* necessary. Where practical, the change should involve a simple update. If such changes are *absolutely* necessary to fully fix the vulnerability, minimize the user impact, and look for ways to mitigate the vulnerability without applying the change (since many users will be unable to install such changes in a timely way). + When creating a patch, it is *vital* that it be *easy* to users to update (at least for the users who are using the most recent release of the software). Your change should not require the users to use a different API, or eliminate user functionality, unless that is *absolutely* necessary. Where practical, the change should involve a simple update. If such changes are *absolutely* necessary to fully fix the vulnerability, minimize the user impact, and look for ways to mitigate the vulnerability without applying the change (since many users will be unable to install such changes in a timely way). For issues in patching, see the [Troubleshooting](#troubleshooting-the-process) section of the guide. From 11b2d17e7805675c606cc9a30a0ddfe22aa7a88c Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:22:27 -0400 Subject: [PATCH 11/15] Move "publish" right after creating the process The easiest time to publish the process is after you've made the decisions, so I think it's better placed a little earlier. Signed-off-by: David A. Wheeler --- guide.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/guide.md b/guide.md index 0e94436..7ca7ccc 100644 --- a/guide.md +++ b/guide.md @@ -11,10 +11,10 @@ * [Establish a CNA contact](#establish-a-cna-contact) * [Create an embargo list](#create-an-embargo-list) * [Select communication templates](#select-communication-templates) +* **[Publish your vulnerability management process](#publish-your-vulnerability-management-process)** * **[The vulnerability response process](#the-vulnerability-response-process)** * [Runbook](#runbook) * [Response process](#response-process) -* **[Publishing your vulnerability management process](#publishing-your-vulnerability-management-process)** * **[Troubleshooting](#troubleshooting-the-process)** * **[Acknowledgements](#acknowledgements)** @@ -192,6 +192,13 @@ If an embargo list is relevant to your project, you will want to create a restri The more you have pre-written, the less there is to do when you have an issue to respond to. [See the `Templates` directory](https://github.com/ossf/oss-vulnerability-guide/tree/main/templates) for security policy (`SECURITY.md`), embargoed notification, and public disclosure templates. +## Publish your vulnerability management process + + +It can be beneficial to both reporters and users to publish what your project does when it receives a security issue, and if you have a time-based disclosure deadline along with the usual time period. This helps reporters follow the process along, and helps users have context for how an issue was handled when they see a disclosure. If you follow this process, just link to this document! Users and reporters may also want to know if a VMT is active; a regular status update can help with this. + + + ## The vulnerability response process @@ -277,12 +284,6 @@ See [`Runbook.md`]( https://github.com/ossf/oss-vulnerability-guide/blob/main/ru Once you release the update, detailed information about the vulnerability is essentially released to the public. You might choose to briefly withold details about how the vulnerability can be exploited, in the hopes that this will give users a little more time to update before attackers begin exploiting the vulnerability. This only makes sense if it's not obvious to attackers how the vulnerability can be exploited, and in most cases attackers will find it obvious. In addition, attackers can usually review changes made to software (in source or executable form) and easily determine an attack. Thus, withholding detailed information can only be helpful for a few days at most, even in the few cases where it helps at all. -## Publishing your vulnerability management process - - -It can be beneficial to both reporters and users to publish what your project does when it receives a security issue, and if you have a time-based disclosure deadline along with the usual time period. This helps reporters follow the process along, and helps users have context for how an issue was handled when they see a disclosure. If you follow this process, just link to this document! Users and reporters may also want to know if a VMT is active; a regular status update can help with this. - - ## Troubleshooting the process From a7cd95728873ea4dff96c8c5c6285da8fb267070 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:24:16 -0400 Subject: [PATCH 12/15] Add verb to heading so it's more parallel Most other headings start with a verb (they're active); do the same thing here. Signed-off-by: David A. Wheeler --- guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide.md b/guide.md index 7ca7ccc..c2eec05 100644 --- a/guide.md +++ b/guide.md @@ -12,7 +12,7 @@ * [Create an embargo list](#create-an-embargo-list) * [Select communication templates](#select-communication-templates) * **[Publish your vulnerability management process](#publish-your-vulnerability-management-process)** -* **[The vulnerability response process](#the-vulnerability-response-process)** +* **[Apply the vulnerability response process](#apply-the-vulnerability-response-process)** * [Runbook](#runbook) * [Response process](#response-process) * **[Troubleshooting](#troubleshooting-the-process)** @@ -199,7 +199,7 @@ It can be beneficial to both reporters and users to publish what your project do -## The vulnerability response process +## Apply the vulnerability response process ### Runbook From c0d9992f99b02529338018f8da0d7d772cc8394d Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:27:55 -0400 Subject: [PATCH 13/15] Clarify "public" is the key Add the word "publicly* to make it clear that's the distinguishing factor. Signed-off-by: David A. Wheeler --- guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide.md b/guide.md index c2eec05..4d68ccc 100644 --- a/guide.md +++ b/guide.md @@ -310,9 +310,9 @@ If you’re struggling to develop a patch that fully resolves the issue, you hav If an issue is unresolvable, it is better that users know than not know. “Security through obscurity” is a weak defense in vulnerability management. Any existing vulnerability can be found and exploited by bad actors. Document the issue well, including any related work-arounds for common environments, and continue to work on it in public. -**Someone disclosed a vulnerability without working with us** +**Someone publicly disclosed a vulnerability without working with us** -Maybe it’s found in a research paper, an article, or on social media, but if someone discloses a vulnerability in your project that you had no prior awareness of, the best thing to do is treat it as a regular project issue (it is, after all, already public) but assign it high priority and communicate with your users, particularly if it’s a publicized or critical issue. Let them know you’re aware of the issue, how it’s being handled, and where they should watch for updates. Handling an issue of this type publicly removes a significant part of the communication burden, as it allows others to find this information and not have to contact the VMT. +Maybe it’s found in a research paper, an article, or on social media, but if someone publicly discloses a vulnerability in your project that you had no prior awareness of, the best thing to do is treat it as a regular project issue (it is, after all, already public) but assign it high priority and communicate with your users, particularly if it’s a publicized or critical issue. Let them know you’re aware of the issue, how it’s being handled, and where they should watch for updates. Handling an issue of this type publicly removes a significant part of the communication burden, as it allows others to find this information and not have to contact the VMT. ## Acknowledgements From 7f46b38ac2d8162c715cb3f90da82251152293a4 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:35:24 -0400 Subject: [PATCH 14/15] Rewrite GitHub security advisory text It wasn't clear what the pronouns referred to, and overall the text was confusing. I reordered & tweaked the text here; I don't think I changed the meaning, but hopefully I made it clearer. Signed-off-by: David A. Wheeler --- guide.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/guide.md b/guide.md index 4d68ccc..8c9ae4a 100644 --- a/guide.md +++ b/guide.md @@ -121,16 +121,19 @@ The vulnerability reporter is doing you a favor; don’t add more steps than abs ##### If you are using GitHub -GitHub Security Advisory is a GitHub feature that allows *only* selected users to privately share information about reported issues, develop patches on a private branch, and publish a security advisory. If you plan to use GitHub Security Advisory for private patch development, follow the directions below. Otherwise, follow the directions for [another service](#if-you-are-using-another-service). +You may choose to use GitHub Security Advisory, but it *cannot* today be used as a general-purpose intake method for vulnerability reports. +GitHub Security Advisory is a GitHub feature that allows *only* selected users to privately share information about reported issues, develop patches on a private branch, and publish a security advisory. +The GitHub Security Advisory workflow starts when a repo or org admin opens a Security Advisory. +General users cannot create a Security Advisory or create a private “security issue” out of a standard GitHub issue. +Thus, currently GitHub Security Advisory *must* be supplemented with other intake mechanisms. +If you choose to not use GitHub Security Advisory features for private patch development, follow the directions for [another service](#if-you-are-using-another-service). -However, GitHub Security Advisory *cannot* today be a general-purpose intake method for vulnerability reports. The GitHub Security Advisory workflow starts when a repo or org admin opens a Security Advisory; general users cannot create a Security Advisory or create a private “security issue” out of a standard GitHub issue. Thus, currently GitHub Security Advisory *must* be supplemented with other intake mechanisms. - +If you choose to use use GitHub Security Advisory for private patch development, here's how we recommend supplementing it. Your Security Policy should instruct reporters to email the VMT with a vulnerability report ([see `SECURITY.md` templates](https://github.com/ossf/oss-vulnerability-guide/tree/main/templates/security_policies)). The VMT will then open a Security Advisory and add the reporter as a collaborator ([see GitHub documentation on GitHub Security Advisory](https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/about-github-security-advisories)). It is also appropriate to email that alias for questions about the vulnerability disclosure process. ##### If you are using another service - If you are using an issue tracker to track security vulnerabilities (e.g., [Launchpad](https://launchpad.net/), Buganizer, or [Bugzilla](https://www.bugzilla.org/)), your Security Policy should instruct reporters to open a security issue in that tracker. It is also appropriate to email the VMT alias for questions about the vulnerability disclosure process or if there are problems opening a security issue. If you do not have an issue tracker with a security issue feature, you need an alternative method for intake. Your intake solution should restrict access to the content of the messages to verified identities (or at least verified email addresses), to counter being overwhelmed with spam. However, this solution also has to be accessible and low friction. Typically this will be an email address. From 8c58895f355cdfc72cdc5c1152dba3890801b037 Mon Sep 17 00:00:00 2001 From: "David A. Wheeler" Date: Fri, 3 Sep 2021 18:39:43 -0400 Subject: [PATCH 15/15] Tweak confusing text about GitHub Security Advisory Signed-off-by: David A. Wheeler --- guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/guide.md b/guide.md index 8c9ae4a..5adc265 100644 --- a/guide.md +++ b/guide.md @@ -154,7 +154,9 @@ You have a decision to make: Will you use the GitHub Security Advisory feature t **Pros:** Keeps all development within one platform, easy to add external contributors (e.g., the reporter, or other experts who can help with patching), when the vulnerability is disclosed, it is easy to flip the work from “private” to “public.” -**Cons:** One problem with private development is that you will not be able to get widespread feedback of your change; as a result, the fix may not truly fix the problem and/or have bad unintended consequences. If the vulnerability is *already* publicly known and widely exploited, there's no advantage to trying to keep things private. In the case where the vulnerability is already widely known publicly, it may be better to develop the fix in public as well (where you may get more people to help and more feedback). +**Cons:** One problem with private development is that you will not be able to get widespread feedback of your change; as a result, the fix may not truly fix the problem and/or have bad unintended consequences. In particular, it can be a challenge to share the proposed changes with many people without making them public using this approach. + +If the vulnerability is *already* publicly known and widely exploited, there's no advantage to trying to keep things private. In the case where the vulnerability is already widely known publicly, it is probably better to develop the fix in public as well (where you may get more people to help and more feedback). Also, at the time of writing, private forks created as part of GitHub Security Advisory do not have access to integration like CI systems ([see documentation](https://docs.github.com/en/free-pro-team@latest/github/managing-security-vulnerabilities/collaborating-in-a-temporary-private-fork-to-resolve-a-security-vulnerability#creating-a-temporary-private-fork)), so you will need to run tests locally.