Merge pull request #31064 from github/repo-sync

Repo sync

content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md

@@ -293,9 +293,15 @@ jobs:
 
 {% endif %}
 
-## Defining the alert severities that give a check failure for a pull request
+## Defining the alert severities that cause a check failure for a pull request
 
-By default, only alerts with the severity level of `Error` or security severity level of `Critical` or `High` will cause a pull request check failure, and a check will still succeed with alerts of lower severities. You can change the levels of alert severities and of security severities that will cause a pull request check failure in your repository settings. For more information about severity levels, see "[AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details)."
+{% data reusables.code-scanning.pull-request-checks %}
+
+{% ifversion code-scanning-without-workflow %}
+
+You can edit which severity and security severity alert levels cause a check failure. For more information, see "[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request)."
+
+{% else %}
 
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-settings %}
@@ -303,6 +309,8 @@ By default, only alerts with the severity level of `Error` or security severity
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", in the "Protection rules" section, use the drop-down menu to define which alerts should cause a check failure. Choose one level for alerts of type "Security" and one level for all other alerts.{% else %}
 1. Under "{% data variables.product.prodname_code_scanning_caps %}", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.{% endif %}
 
+{% endif %}
+
 ## Configuring a category for the analysis
 
 Use `category` to distinguish between multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. The category you specify in your workflow will be included in the SARIF results file.

content/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts.md

@@ -42,20 +42,6 @@ If you configure {% data variables.product.prodname_code_scanning %} using {% da
 
 When {% data variables.product.prodname_code_scanning %} reports data-flow alerts, {% data variables.product.prodname_dotcom %} shows you how data moves through the code. {% data variables.product.prodname_code_scanning_caps %} allows you to identify the areas of your code that leak sensitive information, and that could be the entry point for attacks by malicious users.
 
-### About severity levels
-
-Alert severity levels may be `Error`, `Warning`, or `Note`.
-
-If {% data variables.product.prodname_code_scanning %} is enabled as a pull request check, the check will fail if it detects any results with a severity of `error`. You can specify which severity level of code scanning alerts causes a check failure. For more information, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#defining-the-severities-causing-pull-request-check-failure)."
-
-### About security severity levels
-
-{% data variables.product.prodname_code_scanning_caps %} displays security severity levels for alerts that are generated by security queries. Security severity levels can be `Critical`, `High`, `Medium`, or `Low`.
-
-To calculate the security severity of an alert, we use Common Vulnerability Scoring System (CVSS) data. CVSS is an open framework for communicating the characteristics and severity of software vulnerabilities, and is commonly used by other security products to score alerts. For more information about how severity levels are calculated, see [this blog post](https://gh.io/2021-07-19-code-scanning-security-severity).
-
-By default, any {% data variables.product.prodname_code_scanning %} results with a security severity of `Critical` or `High` will cause a check failure. You can specify which security severity level for {% data variables.product.prodname_code_scanning %} results should cause a check failure. For more information, see "[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#defining-the-severities-causing-pull-request-check-failure)."
-
 ### About {% ifversion remove-code-scanning-configurations %}alerts from multiple configurations{% else %}analysis origins{% endif %}
 
 {% ifversion remove-code-scanning-configurations %}
@@ -106,3 +92,29 @@ When you click through to see details for the alert, you can see that the file p
 {% endnote %}
 
 {% endif %}
+
+## About alert severity and security severity levels
+
+The severity level for a {% data variables.product.prodname_code_scanning %} alert indicates how much risk the problem adds to your codebase.
+
+- **Severity.** All {% data variables.product.prodname_code_scanning %} alerts have a level of `Error`, `Warning`, or `Note`.
+- **Security severity.** Each security alert found using {% data variables.product.prodname_codeql %} also has a security severity level of `Critical`, `High`, `Medium`, or `Low`.
+
+When an alert has a security severity level, {% data variables.product.prodname_code_scanning %} displays and uses this level in preference to the `severity`. Security severity levels follow the industry-standard Common Vulnerability Scoring System (CVSS) that is also used for advisories in the {% data variables.product.prodname_advisory_database %}.  For more information, see [CVSS: Qualitative Severity Rating Scale](https://www.first.org/cvss/v3.1/specification-document#Qualitative-Severity-Rating-Scale).
+
+### Pull request check failures for {% data variables.product.prodname_code_scanning %} alerts
+
+{% data reusables.code-scanning.pull-request-checks %}
+
+You can edit which severity and security severity alert levels cause a check failure. For more information, see {% ifversion code-scanning-without-workflow %}"[AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request){% else %}"[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request){% endif %}."
+
+### Calculation of security severity levels
+
+When a security query is added to the {% data variables.product.prodname_codeql %} Default or Extended query suite, the {% data variables.product.prodname_codeql %} engineering team calculates the security severity as follows.
+
+1. Search for all CVEs that are assigned one or more of the CWE tags associated with the new security query.
+1. Calculate the 75th percentile of the CVSS score for those CVEs.
+1. Define that score as the security severity for the query.
+1. When displaying alerts found by the query, translate the numerical scores to `Critical`, `High`, `Medium`, or `Low` using the CVSS definitions.
+
+For more information, see [{% data variables.product.prodname_codeql %} CWE coverage](https://codeql.github.com/codeql-query-help/codeql-cwe-coverage/) on the {% data variables.product.prodname_codeql %} documentation site.

content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md

@@ -54,6 +54,16 @@ If you need to change any other aspects of your {% data variables.product.prodna
 1. To update your configuration of default setup, click **Enable {% data variables.product.prodname_codeql %}**.
 {% endif %}
 
+## Defining the alert severities that cause a check failure for a pull request
+
+{% data reusables.code-scanning.pull-request-checks %}
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.navigate-to-code-security-and-analysis %} {% ifversion fpt or ghec %}
+1. Under "{% data variables.product.prodname_code_scanning_caps %}", in the "Protection rules" section, use the drop-down menu to define which alerts should cause a check failure. Choose one level for alerts of type "Security" and one level for all other alerts.{% else %}
+1. Under "{% data variables.product.prodname_code_scanning_caps %}", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.{% endif %}
+
 {% ifversion codeql-threat-models-java %}
 
 ## Including local sources of tainted data in default setup

data/reusables/code-scanning/pull-request-checks.md

@@ -0,0 +1 @@
+When you enable {% data variables.product.prodname_code_scanning %} on pull requests the check fails only if one or more alerts of severity `error`, or security severity `critical` or `high` are detected. The check will succeed if alerts with lower severities or security severities are detected. For important codebases, you may want the {% data variables.product.prodname_code_scanning %} check to fail if any alerts are detected, so that the alert must be fixed or dismissed before the code change is merged. For more information about severity levels, see "[About alert severity and security severity levels](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels)."