Structured, required proof-of-concept fields + Confidential team-only comments for private vulnerability reports (#63552)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>

Author: 3 people

content/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configure-for-a-repository.md

@@ -31,6 +31,56 @@ The instructions in this article refer to enablement at repository level. For in
 
 {% data reusables.security-advisory.private-vulnerability-api %}
 
+## Customizing the vulnerability reporting form
+
+By default, the private vulnerability reporting form requires reporters to provide a summary, details, proof of concept, and impact statement. This structured information helps maintainers assess reports consistently and reduces the need to request missing details.
+
+To customize the form, add a `VULNERABILITY_REPORT.yml` or `VULNERABILITY_REPORT.yaml` file to the repository's `.github` directory. You can also define a default form for an organization or personal account in the `.github` repository owned by that account. A form in an individual repository takes precedence over the form in the owner's `.github` repository.
+
+Private vulnerability reporting forms use the same YAML syntax as issue forms. The forms support `checkboxes`, `dropdown`, `input`, `markdown`, and `textarea` elements. You can mark fields as required and use `min_length` to require a minimum number of characters for `input` and `textarea` elements. For information about the supported keys for each element, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema).
+
+For example, the following form requires a detailed proof of concept of at least 100 characters.
+
+```yaml copy
+name: Private vulnerability report
+description: Provide the information maintainers need to assess the report.
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Summarize the vulnerability and its potential severity.
+    validations:
+      required: true
+  - type: textarea
+    id: proof_of_concept
+    attributes:
+      label: Proof of concept
+      description: Provide complete instructions for reproducing the vulnerability.
+    validations:
+      required: true
+      min_length: 100
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact
+      description: Explain who is affected and how.
+    validations:
+      required: true
+```
+
+If {% data variables.product.prodname_dotcom %} cannot parse or validate a custom form, reporters see the default form instead.
+
+## Requiring reporters to assign a CWE
+
+You can require reporters to associate at least one Common Weakness Enumeration (CWE) with each new report. This repository-level setting applies to reports submitted in the web interface and with the REST API. It does not apply to repository maintainers who create advisories or to edits of existing reports.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.navigate-to-code-security-and-analysis %}
+1. Under **{% data variables.product.UI_advanced_security %}**, to the right of **Private vulnerability reporting**, click **Settings**.
+1. Under **Submission requirements**, enable **Require a CWE assignment**.
+
 ## Configuring notifications for private vulnerability reporting
 
 {% data reusables.security-advisory.private-vulnerability-reporting-configure-notifications %}

content/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/manage-vulnerability-reports.md

@@ -21,20 +21,34 @@ When a security researcher reports a vulnerability privately, you are notified a
 
 For more information about configuring notification preferences, see [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configure-for-a-repository#configuring-notifications-for-private-vulnerability-reporting).
 
+## Reviewing a vulnerability report
+
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-security %}
 {% data reusables.repositories.sidebar-advisories %}
 1. Click the advisory you want to review. An advisory that was reported privately has a status of `Triage`.
 
    ![Screenshot of a "Security Advisories" list.](/assets/images/help/security/advisory-list.png)
 
-1. Carefully review the report, then choose how to proceed.
+1. Carefully review the report details and any disclosure of AI assistance. Then choose how to proceed.
    * To collaborate on a patch in private, click **Start a temporary private fork** to create a place for further discussions with the contributor. This does not change the status of the proposed advisory from `Triage`.
    * To accept the reported vulnerability, click **Accept and open as draft** to accept the vulnerability report as a draft advisory on {% data variables.product.prodname_dotcom %}. If you choose this option:
       * This doesn't make the report public.
       * The report becomes a draft repository security advisory and you can work on it in the same way as any draft advisory that you create.
      For more information on security advisories, see [AUTOTITLE](/code-security/concepts/vulnerability-reporting-and-management/repository-security-advisories).
-   * To ask for more information, or to open a discussion with the reporter, you can comment on the advisory. Any comments are visible only to the reporter and to any collaborators on the advisory.
+   * To ask for more information, or to open a discussion with the reporter, you can comment on the advisory. A regular comment is visible to the reporter and all collaborators on the advisory.
    * If you have enough information to determine that the problem the reporter describes is not a security risk, click **Close security advisory**. Where possible, you should add a comment explaining why you don't consider the report a security risk before you close the advisory.
 
      ![Screenshot showing the options available to the repository maintainer when reviewing an externally submitted vulnerability report.](/assets/images/help/security/advisory-maintainer-options.png)
+
+## Discussing a report with people who have write access
+
+People with write access to the repository can use confidential comments to coordinate with each other. These comments are hidden from the reporter and invited advisory collaborators who do not have write access.
+
+Access to confidential comments is based on current repository permissions. If a person's write access is removed, they can no longer read confidential comments. People who gain write access can read existing confidential comments.
+
+1. In the advisory, type your comment.
+1. Below the comment field, select **Confidential. Only maintainers will see this comment**.
+1. Click **Comment**.
+
+You can edit or delete a confidential comment if you still have write access to the repository. You cannot change a comment from regular to confidential, or from confidential to regular, after posting it.

content/code-security/how-tos/report-and-fix-vulnerabilities/report-privately.md

@@ -24,7 +24,7 @@ category:
 
 > [!NOTE]
 > * If you have admin or security permissions for a public repository, you don’t need to submit a vulnerability report. Instead, create a draft security advisory directly. See [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/create-repository-advisory).
-> * Private vulnerability reporting is separate from a repository’s `SECURITY.md` file. You can only report vulnerabilities privately for repositories where this feature is enabled, and you don’t need to follow the instructions in `SECURITY.md`.
+> * Private vulnerability reporting is separate from a repository’s `SECURITY.md` file. You can only report vulnerabilities privately for repositories where this feature is enabled. If the repository has a security policy, the policy is displayed above the reporting form so you can review the maintainer's guidance before submitting.
 
 If a public repository has private vulnerability reporting enabled, anyone can submit a private vulnerability report to the repository maintainers.
 

content/code-security/reference/permissions/repository-security-advisory.md

@@ -40,6 +40,8 @@ Add and remove credits for a security advisory (see [AUTOTITLE](/code-security/h
 Close the draft security advisory | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %}  |
 Publish the security advisory (see [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/publish-repository-advisory)) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %}  |
 
+Repository security advisory collaborators without write access to the repository cannot create or view confidential comments. This restriction includes the reporter of a privately reported vulnerability unless they also have write access. See [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/manage-vulnerability-reports#discussing-a-report-with-people-who-have-write-access).
+
 ### Permission differences for global security advisories
 
 Unlike repository security advisories, anyone can contribute to **global security advisories** in the {% data variables.product.prodname_advisory_database %} at [github.com/advisories](https://github.com/advisories). Edits to global advisories will not change or affect how the advisory appears on the repository. See [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/edit-advisory-database).

content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md

@@ -72,6 +72,9 @@ You can create defaults in your organization or personal account for the followi
 |  {% endif %} |
 | Issue and pull request templates and _config.yml_ | Issue and pull request templates customize and standardize the information you'd like contributors to include when they open issues and pull requests in your repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates).<br /><br />If an issue template sets a label, that label must be created in your `.github` repository and any repositories where the template will be used. |
 | _SECURITY.md_ | A SECURITY file gives instructions on how to report a security vulnerability in your project and description that hyperlinks the file. For more information, see [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/add-security-policy). |
+|  {% ifversion fpt or ghec %} |
+| _VULNERABILITY_REPORT.yml_ or _VULNERABILITY_REPORT.yaml_ | A vulnerability report form customizes the information that reporters must provide when they privately report a vulnerability. For more information, see [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configure-for-a-repository#customizing-the-vulnerability-reporting-form). |
+|  {% endif %} |
 | _SUPPORT.md_ | A SUPPORT file lets people know about ways to get help with your project. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project). |
 
 You cannot create a default license file. License files must be added to individual repositories so the file will be included when a project is cloned, packaged, or downloaded.
@@ -86,4 +89,10 @@ You cannot create a default license file. License files must be added to individ
 1. {% ifversion ghec %}If you are creating the repository for an {% data variables.enterprise.prodname_emu_org %}, set the repository status to **Internal**. For any other eligible account, set the status to **Public**.{% else %}Make sure the repository status is set to **Public**.{% endif %} A repository for default files cannot be private.
 {% data reusables.repositories.initialize-with-readme %}
 {% data reusables.repositories.create-repo %}
-1. In the repository, create one of the supported community health files. Discussion category forms must be in a folder called `.github/DISCUSSION_TEMPLATE`. Issue templates and their configuration file must be in a folder called `.github/ISSUE_TEMPLATE`. {% ifversion fpt or ghec %}A `FUNDING.yml` file must be in the `.github` folder. {% endif %}All other supported files may be in the root of the repository, the `.github` folder, or the `docs` folder. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files).
+1. In the repository, create one of the supported community health files. Store the file in the required location:
+   * Store discussion category forms in `.github/DISCUSSION_TEMPLATE`.
+   * Store issue templates and their configuration file in `.github/ISSUE_TEMPLATE`.
+   {% ifversion fpt or ghec %}* Store `FUNDING.yml`, `VULNERABILITY_REPORT.yml`, and `VULNERABILITY_REPORT.yaml` in the `.github` folder.{% endif %}
+   * Store all other supported files in the root of the repository, the `.github` folder, or the `docs` folder.
+
+   For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files).

content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema.md

@@ -132,6 +132,7 @@ You can use a `textarea` element to add a multi-line text field to your form. Co
 | Key | Description | Required | Type | Default | Valid values |
 | --- | ----------- | -------- | ---- | ------- | ------- |
 {% data reusables.form-schema.required-key %}
+{% data reusables.form-schema.min-length-key %}
 
 #### Example of `textarea`
 
@@ -150,6 +151,7 @@ body:
     render: bash
   validations:
     required: true
+    min_length: 100
 ```
 
 ### `input`
@@ -174,6 +176,7 @@ You can use an `input` element to add a single-line text field to your form.
 | Key | Description | Required | Type | Default | Valid values |
 | --- | ----------- | -------- | ---- | ------- | ------- |
 {% data reusables.form-schema.required-key %}
+{% data reusables.form-schema.min-length-key %}
 
 #### Example of `input`
 
@@ -187,6 +190,7 @@ body:
     placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
   validations:
     required: true
+    min_length: 20
 ```
 
 ### `dropdown`

data/reusables/form-schema/min-length-key.md

@@ -0,0 +1 @@
+| `min_length` | Prevents form submission until the response contains at least the specified number of characters. | {% octicon "x" aria-label="Optional" %} | Integer | {% octicon "dash" aria-label="Not applicable" %} | A non-negative integer |

data/reusables/security-advisory/private-vulnerability-api.md

@@ -1 +1,3 @@
-Security researchers can also use the REST API to privately report security vulnerabilities. See [AUTOTITLE](/rest/security-advisories/repository-advisories#privately-report-a-security-vulnerability).
+Security researchers can also use the REST API to privately report security vulnerabilities. API submissions use a Markdown `description`. If the repository or its owner's `.github` repository defines a custom vulnerability reporting form, the API description must contain the required sections and responses from that form. The built-in default form is not enforced for API submissions.
+
+You can use the REST API to retrieve the custom form that applies to a repository. See [AUTOTITLE](/rest/security-advisories/repository-advisories).

data/reusables/security-advisory/reporting-a-vulnerability-non-admin.md

@@ -1,13 +1,13 @@
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-security %}
 1. Click **Report a vulnerability** to open the advisory form.
-1. Fill in the advisory details form.
+1. If the repository has a security policy, review the policy displayed above the form.
+1. Fill in the vulnerability reporting form.
 
    > [!TIP]
-   > In this form, only the title and description are mandatory. (In the general draft security advisory form, which the repository maintainer initiates, specifying the ecosystem is also required.) However, we recommend security researchers provide as much information as possible on the form so that the maintainers can make an informed decision about the submitted report. You can adopt the template used by our security researchers from the {% data variables.product.prodname_security %}, which is available on the [`github/securitylab` repository](https://github.com/github/securitylab/blob/main/docs/report-template.md).
-
-   For more information about the fields available and guidance on filling in the form, see [AUTOTITLE](/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/create-repository-advisory) and [AUTOTITLE](/code-security/tutorials/fix-reported-vulnerabilities/write-security-advisories).
+   > By default, you must provide a summary, details, proof of concept, and impact statement. Maintainers can customize the form and require other information. Provide enough detail for the maintainers to reproduce and assess the vulnerability.
 
+1. Optionally, select **I used AI assistance to find or write up this report**.
 1. At the bottom of the form, click **Submit report**. {% data variables.product.prodname_dotcom %} will display a message letting you know that maintainers have been notified and that you have a pending credit for this security advisory.
 
    > [!TIP]