Merge pull request #17853 from github/mc-dependabot-advisory-db

High-level user documentation about disclosing vulnerabilities in GitHub

Author: mchammer01

content/code-security/security-advisories/about-coordinated-disclosure-of-security-vulnerabilities.md

@@ -0,0 +1,65 @@
+---
+title: About coordinated disclosure of security vulnerabilities
+intro: 'Vulnerability disclosure is a coordinated effort between security reporters and repository maintainers.'
+miniTocMaxHeadingLevel: 4
+versions:
+  free-pro-team: '*'
+---
+
+### About disclosing vulnerabilities in the industry
+
+{% data reusables.security-advisory.disclosing-vulnerabilities %}
+
+The initial report of a vulnerability is made privately, and the full details are only published once the maintainer has acknowledged the issue, and ideally made remediations or a patch available, sometimes with a delay to allow more time for the patches to be installed. For more information, see the "[OWASP Cheat Sheet Series about vulnerability disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html#commercial-and-open-source-software)" on the OWASP Cheat Sheet Series website.
+
+#### Best practices for vulnerability reporters
+
+It's good practice to report vulnerabilities privately to maintainers. When possible, as a vulnerability reporter, we recommend you avoid:
+- Disclosing the vulnerability publicly without giving maintainers a chance to remediate.
+- Bypassing the maintainers.
+- Disclosing the vulnerability before a fixed version of the code is available.
+- Expecting to be compensated for reporting an issue, where no public bounty program exists.
+
+It's acceptable for vulnerability reporters to disclose a vulnerability publicly after a period of time, if they have tried to contact the maintainers and not received a response, or contacted them and been asked to wait too long to disclose it. 
+
+We recommend vulnerability reporters clearly state the terms of their disclosure policy as part of their reporting process. Even if the vulnerability reporter does not adhere to a strict policy, it's a good idea to set clear expectations for maintainers in terms of timelines on intended vulnerability disclosures. For an example of disclosure policy, see the "[Security Lab's disclosure policy](https://securitylab.github.com/advisories#policy)" on the GitHub Security Lab website.
+
+#### Best practices for maintainers
+
+As a maintainer, it's good practice to clearly indicate how and where you want to receive reports for vulnerabilities. If this information is not clearly available, vulnerability reporters don't know how to contact you, and may resort to extracting developer email addresses from git commit histories to try to find an appropriate security contact. This can lead to friction, lost reports, or the publication of unresolved reports.
+
+Maintainers should disclose vulnerabilities in a timely manner. If there is a security vulnerability in your repository, we recommend you:
+- Treat the vulnerability as a security issue rather than a simple bug, both in your response and your disclosure. For example, you'll need to explicitly mention that the issue is a security vulnerability in the release notes.
+- Acknowlege receipt of the vulnerability report as quickly as possible, even if no immediate resources are available for investigation. This sends the message that you are quick to respond and act, and it sets a positive tone for the rest of the interaction between you and the vulnerability reporter.
+- Involve the vulnerability reporter when you verify the impact and veracity of the report. It's likely the vulnerability reporter has already spent time considering the vulnerability in a variety of scenarios, some of which you may have not considered yourself.
+- Remediate the issue in a way that you see fit, taking any concerns and advice provided by the vulnerability reporter into careful consideration. Often the vulnerability reporter will have knowledge of certain corner cases and remediation bypasses that are easy to miss without a security research background.
+- Always acknowledge the vulnerability reporter when you credit the discovery.
+- Aim to publish a fix as soon as you can.
+- Ensure that you make the wider ecosystem aware of the issue and its remediation when you disclose the vulnerability. It is not uncommon to see cases where a recognized security issue is fixed in the current development branch of a project, but the commit or subsequent release is not explicitly marked as a security fix or release. This can cause problems with downstream consumers.
+
+Publishing the details of a security vulnerability doesn't make maintainers look bad. Security vulnerabilities are present everywhere in software, and users will trust maintainers who have a clear and established process for disclosing security vulnerabilities in their code.
+
+### About reporting and disclosing vulnerabilities in projects on {% data variables.product.prodname_dotcom %}
+
+The process for reporting and disclosing vulnerabilities for projects on {% data variables.product.prodname_dotcom_the_website %} is as follows:
+
+ If you are a vulnerability reporter (for example, a security researcher) who would like report a vulnerability, first check if there is a security policy for the related repository. For more information, see "[About security policies](/github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository#about-security-policies)." If there is one, follow it to understand the process before contacting the security team for that repository. 
+ 
+ If there isn't a security policy in place, the most efficient way to establish a private means of communication with maintainers is to create an issue asking for a preferred security contact. It's worth noting that the issue will be immediately publicly visible, so it should not include any information about the bug. Once communication is established, you can suggest the maintainers define a security policy for future use.
+
+{% note %}
+
+**Note**: _For npm only_ - If we receive a report of malware in an npm package, we try to contact you privately. If you don't address the issue in a timely manner, we will disclose it. For more information, see "[Reporting malware in an npm package](https://docs.npmjs.com/reporting-malware-in-an-npm-package)" on the npm Docs website.
+
+{% endnote %}
+
+ If you've found a security vulnerability in {% data variables.product.prodname_dotcom_the_website %}, please report the vulnerability through our coordinated disclosure process. For more information, see the [{% data variables.product.prodname_dotcom %} Security Bug Bounty](https://bounty.github.com/) website.
+
+ If you are a maintainer, you can take ownership of the process at the very beginning of the pipeline by setting up a security policy for your repository, or otherwise making security reporting instructions clearly available, for example in your project’s README file. For information about adding a security policy, see "[About security policies](/github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository#about-security-policies)." If there is no security policy, it's likely that a vulnerability reporter will try to email you or otherwise privately contact you. Alternatively, someone may open a (public) issue with details of a security issue.
+
+ As a maintainer, to disclose a vulnerability in your code, you first create a draft security advisory in the package's repository in {% data variables.product.prodname_dotcom %}. {% data reusables.security-advisory.security-advisory-overview %} For more information, see "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories)."
+
+
+ To get started, see "[Creating a security advisory](/github/managing-security-vulnerabilities/creating-a-security-advisory)."
+
+

content/code-security/security-advisories/about-github-security-advisories.md

@@ -17,27 +17,31 @@ topics:
 
 ### About {% data variables.product.prodname_security_advisories %}
 
-{% data variables.product.prodname_security_advisories %} allows repository maintainers to privately discuss and fix a security vulnerability in a project. After collaborating on a fix, repository maintainers can publish the security advisory to publicly disclose the security vulnerability to the project's community. By publishing security advisories, repository maintainers make it easier for their community to update package dependencies and research the impact of the security vulnerabilities.
+{% data reusables.security-advisory.disclosing-vulnerabilities %} For more information, see "[About coordinated disclosure of security vulnerabilities](/code-security/security-advisories/about-coordinated-disclosure-of-security-vulnerabilities)."
+
+{% data reusables.security-advisory.security-advisory-overview %}
 
 With {% data variables.product.prodname_security_advisories %}, you can:
 
-1. Create a draft security advisory, and use the draft to privately discuss the impact of the vulnerability on your project.
+1. Create a draft security advisory, and use the draft to privately discuss the impact of the vulnerability on your project. For more information, see "[Creating a security advisory](/github/managing-security-vulnerabilities/creating-a-security-advisory)."
 2. Privately collaborate to fix the vulnerability in a temporary private fork.
-3. Publish the security advisory to alert your community of the vulnerability.
+3. Publish the security advisory to alert your community of the vulnerability once a patch is released. For more information, see "[Publishing a security advisory](/github/managing-security-vulnerabilities/publishing-a-security-advisory)."
 
 {% data reusables.repositories.security-advisories-republishing %}
 
-To get started, see "[Creating a security advisory](/github/managing-security-vulnerabilities/creating-a-security-advisory)."
-
 You can give credit to individuals who contributed to a security advisory. For more information, see "[Editing a security advisory](/github/managing-security-vulnerabilities/editing-a-security-advisory#about-credits-for-security-advisories)."
 
 {% data reusables.repositories.security-guidelines %}
 
+If you created a security advisory in your repository, the security advisory will stay in your repository. We publish security advisories for any of the ecosystems supported by the dependency graph to the {% data variables.product.prodname_advisory_database %} on [github.com/advisories](https://github.com/advisories). If a security advisory is specifically for npm, we also publish the advisory to the npm security advisories. For more information, see [npmjs.com/advisories](https://www.npmjs.com/advisories).
+
 {% data reusables.repositories.github-security-lab %}
 
 ### CVE identification numbers
 
-{% data variables.product.prodname_security_advisories %} builds upon the foundation of the Common Vulnerabilities and Exposures (CVE) list. {% data variables.product.prodname_dotcom %} is a CVE Numbering Authority (CNA) and is authorized to assign CVE identification numbers. For more information, see "[About CVE](https://cve.mitre.org/about/index.html)" and "[CVE Numbering Authorities](https://cve.mitre.org/cve/cna.html)" on the CVE website.
+{% data variables.product.prodname_security_advisories %} builds upon the foundation of the Common Vulnerabilities and Exposures (CVE) list. The security advisory form on {% data variables.product.prodname_dotcom %} is a standardized form that matches the CVE description format. 
+
+{% data variables.product.prodname_dotcom %} is a CVE Numbering Authority (CNA) and is authorized to assign CVE identification numbers. For more information, see "[About CVE](https://cve.mitre.org/about/index.html)" and "[CVE Numbering Authorities](https://cve.mitre.org/cve/cna.html)" on the CVE website.
 
 When you create a security advisory for a public repository on {% data variables.product.prodname_dotcom %}, you have the option of providing an existing CVE identification number for the security vulnerability. {% data reusables.repositories.request-security-advisory-cve-id %}
 
@@ -46,4 +50,4 @@ For more information, see "[Publishing a security advisory](/github/managing-sec
 
 ### {% data variables.product.prodname_dependabot_alerts %} for published security advisories
 
-{% data reusables.repositories.github-reviews-security-advisories %}
+{% data reusables.repositories.github-reviews-security-advisories %}

content/code-security/security-advisories/adding-a-security-policy-to-your-repository.md

@@ -22,7 +22,7 @@ You can create a default security policy for your organization or user account.
 
 {% endtip %}
 
-After someone reports a security vulnerability in your project, you can use {% data variables.product.prodname_security_advisories %} to disclose, fix, and publish information about the vulnerability. For more information, see "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories)."
+After someone reports a security vulnerability in your project, you can use {% data variables.product.prodname_security_advisories %} to disclose, fix, and publish information about the vulnerability. For more information about the process of reporting and disclosing vulnerabilities in {% data variables.product.prodname_dotcom %}, see "[About coordinated disclosure of security vulnerabilities](/code-security/security-advisories/about-coordinated-disclosure-of-security-vulnerabilities#about-reporting-and-disclosing-vulnerabilities-in-projects-on-github)." For more information about {% data variables.product.prodname_security_advisories %}, see "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories)."
 
 {% data reusables.repositories.github-security-lab %}
 

content/code-security/security-advisories/index.md

@@ -14,6 +14,7 @@ topics:
 ### Table of Contents
 
 {% link_in_list /adding-a-security-policy-to-your-repository %}
+{% link_in_list /about-coordinated-disclosure-of-security-vulnerabilities %}  
 {% link_in_list /about-github-security-advisories %}
 {% link_in_list /permission-levels-for-security-advisories %}
 {% link_in_list /creating-a-security-advisory %}

content/code-security/supply-chain-security/about-dependabot-security-updates.md

@@ -16,6 +16,9 @@ topics:
 
 {% data variables.product.prodname_dependabot_security_updates %} make it easier for you to fix vulnerable dependencies in your repository. If you enable this feature, when a {% data variables.product.prodname_dependabot %} alert is raised for a vulnerable dependency in the dependency graph of your repository, {% data variables.product.prodname_dependabot %} automatically tries to fix it. For more information, see "[About alerts for vulnerable dependencies](/code-security/supply-chain-security/about-alerts-for-vulnerable-dependencies)" and "[Configuring {% data variables.product.prodname_dependabot_security_updates %}](/github/managing-security-vulnerabilities/configuring-dependabot-security-updates)."
 
+{% data variables.product.prodname_dotcom %} may send {% data variables.product.prodname_dependabot %} alerts to repositories affected by a vulnerability disclosed by a recently published {% data variables.product.prodname_dotcom %} security advisory. For more information, see "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories#dependabot-alerts-for-published-security-advisories)."
+
+
 {% data variables.product.prodname_dependabot %} checks whether it's possible to upgrade the vulnerable dependency to a fixed version without disrupting the dependency graph for the repository. Then {% data variables.product.prodname_dependabot %} raises a pull request to update the dependency to the minimum version that includes the patch and links the pull request to the {% data variables.product.prodname_dependabot %} alert, or reports an error on the alert. For more information, see "[Troubleshooting {% data variables.product.prodname_dependabot %} errors](/github/managing-security-vulnerabilities/troubleshooting-dependabot-errors)."
 
 {% note %}

data/reusables/repositories/github-reviews-security-advisories.md

@@ -1,3 +1,3 @@
 {% data variables.product.prodname_dotcom %} will review each published security advisory, add it to the {% data variables.product.prodname_advisory_database %}, and may use the security advisory to send {% data variables.product.prodname_dependabot_alerts %} to affected repositories. If the security advisory comes from a fork, we'll only send an alert if the fork owns a package, published under a unique name, on a public package registry. This process can take up to 72 hours and {% data variables.product.prodname_dotcom %} may contact you for more information.
 
-For more information about {% data variables.product.prodname_dependabot_alerts %}, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies)." For more information about {% data variables.product.prodname_advisory_database %}, see "[Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}](/github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database)."
+For more information about {% data variables.product.prodname_dependabot_alerts %}, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies#dependabot-alerts-for-vulnerable-dependencies)" and "[About {% data variables.product.prodname_dependabot_security_updates %}](/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-dependabot-security-updates)." For more information about {% data variables.product.prodname_advisory_database %}, see "[Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}](/github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database)."

data/reusables/repositories/request-security-advisory-cve-id.md

@@ -1 +1,5 @@
 If you don't already have a CVE identification number for the security vulnerability in your project, you can request a CVE identification number from {% data variables.product.prodname_dotcom %}. {% data variables.product.prodname_dotcom %} usually reviews the request within 72 hours. Requesting a CVE identification number doesn't make your security advisory public. If your security advisory is eligible for a CVE,  {% data variables.product.prodname_dotcom %} will reserve a CVE identification number for your advisory. We'll then publish the CVE details after you publish the security advisory.
+
+If you already have a CVE you want to use, for example, if you use a CNA other than {% data variables.product.prodname_dotcom %}, add it to the security advisory form. This may happen, for example, if you want to get the advisory consistent with other communications you plan to send out at publication time. 
+
+If an advisory form doesn't have a CVE, we will request a CVE for you when you publish the advisory.

data/reusables/repositories/security-advisory-edit-cwe-cve.md

@@ -1,2 +1,2 @@
 1. Add common weakness enumerators (CWEs) for the kinds of security weaknesses that this security advisory addresses. For a full list of CWEs, see the "[Common Weakness Enumeration](https://cwe.mitre.org/index.html)" from MITRE.
-1. If you have an existing CVE identifier, select "I have an existing CVE identifier" and type the CVE identifier in the text box. Otherwise, you can request a CVE from {% data variables.product.prodname_dotcom %} later.
+1. If you have an existing CVE identifier, select "I have an existing CVE identifier" and type the CVE identifier in the text box. Otherwise, you can request a CVE from {% data variables.product.prodname_dotcom %} later. For more information, see "[About {% data variables.product.prodname_security_advisories %}](/github/managing-security-vulnerabilities/about-github-security-advisories#cve-identification-numbers)."

data/reusables/security-advisory/disclosing-vulnerabilities.md

@@ -0,0 +1 @@
+Vulnerability disclosure is an area where collaboration between vulnerability reporters, such as security researchers, and project maintainers is very important. Both parties need to work together from the moment a potentially harmful security vulnerability is found, right until a vulnerability is disclosed to the world, ideally with a patch available. Typically, when someone lets a maintainer know privately about a security vulnerability, the maintainer develops a fix, validates it, and notifies the users of the project or package.