diff --git a/guide.md b/guide.md index aca5133..5adc265 100644 --- a/guide.md +++ b/guide.md @@ -4,31 +4,31 @@ * **[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) - * [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) -* **[The vulnerability response process](#the-vulnerability-response-process)** + * [Create an embargo list](#create-an-embargo-list) + * [Select communication templates](#select-communication-templates) +* **[Publish your vulnerability management process](#publish-your-vulnerability-management-process)** +* **[Apply the vulnerability response process](#apply-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)** ## 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. +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. +Applying this guide will help you be ready. @@ -41,23 +41,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. @@ -68,16 +67,14 @@ 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") -======= -### Establish project's vulnerability handling expecations (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. -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. - -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. @@ -124,27 +121,30 @@ 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). - +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. -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 not use GitHub Security Advisory features for private patch development, follow the directions for [another service](#if-you-are-using-another-service). +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. -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 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. @@ -152,9 +152,11 @@ 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. In particular, it can be a challenge to share the proposed changes with many people without making them public using this approach. -**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). +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. @@ -162,7 +164,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: @@ -177,7 +179,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. @@ -190,12 +192,19 @@ 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. -## The vulnerability response process +## 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. + + + +## Apply the vulnerability response process ### Runbook @@ -228,7 +237,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: @@ -249,7 +258,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. @@ -278,13 +287,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). - - -## 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. - + 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. ## Troubleshooting the process @@ -312,9 +315,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