Repo sync

content/code-security/concepts/code-scanning/codeql/codeql-query-packs.md

@@ -43,6 +43,8 @@ The standard {% data variables.product.prodname_codeql %} packs for all supporte
   * `codeql/ruby-queries`
   * `codeql/swift-queries`
 
+For more information about compatibility between published query packs and different {% data variables.product.prodname_codeql %} releases, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility).
+
 You can also use the {% data variables.product.prodname_codeql_cli %} to create your own {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies.
 
 You can publish {% data variables.product.prodname_codeql %} packs that you have created, using the {% data variables.product.prodname_codeql_cli %}. For more information on publishing and downloading {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs).

content/code-security/concepts/code-scanning/index.md

@@ -17,5 +17,6 @@ children:
   - /about-code-scanning-alerts
   - /setup-types
   - /about-integration-with-code-scanning
+  - /sarif-files
   - /codeql
 ---

content/code-security/concepts/code-scanning/sarif-files.md

@@ -0,0 +1,31 @@
+---
+title: About SARIF files for code scanning
+shortTitle: SARIF files
+intro: SARIF files convert third-party analyses into alerts on {% data variables.product.github %}.
+topics:
+  - Code Security
+  - Code scanning
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+contentType: concepts
+---
+
+>[!NOTE] If you use default setup for {% data variables.product.prodname_code_scanning %}, or an advanced setup that involves using {% data variables.product.prodname_actions %} to run the {% data variables.product.prodname_codeql %} action, then you don't need to interact with SARIF files. Scan results are uploaded and parsed as {% data variables.product.prodname_code_scanning %} alerts automatically.
+
+SARIF stands for _Static Analysis Results Interchange Format_. This is a JSON-based standard for storing results from static analysis tools.
+
+If you use a **third-party analysis tool or CI/CD system** to scan code for vulnerabilities, you can generate a SARIF file and upload it to {% data variables.product.github %}. {% data variables.product.github %} will parse the SARIF file and show alerts using the results in your repository as a part of the {% data variables.product.prodname_code_scanning %} experience.
+
+{% data variables.product.github %} uses properties in the SARIF file to display alerts. For example, the `shortDescription` and `fullDescription` appear at the top of a {% data variables.product.prodname_code_scanning %} alert. The `location` allows {% data variables.product.github %} to show annotations in your code file.
+
+This article explains how SARIF files are used on {% data variables.product.github %}. If you're new to SARIF and want to learn more, see Microsoft's [`SARIF tutorials`](https://github.com/microsoft/sarif-tutorials) repository.
+
+## Version requirements
+
+{% data variables.product.prodname_code_scanning_caps %} supports a subset of the [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) JSON schema. Ensure that SARIF files from third-party tools use this version.
+
+## Upload methods
+
+You can upload a SARIF file using {% data variables.product.prodname_actions %}, the {% data variables.product.prodname_code_scanning %} API, or the {% data variables.product.prodname_codeql_cli %}. The best upload method depends on how you generate the SARIF file. For more information, see [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github).

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests.md

@@ -35,7 +35,7 @@ If the lines of code changed in the pull request generate {% data variables.prod
 * The **Files changed** tab of the pull request
 
 > [!NOTE]
-> {% data variables.product.prodname_code_scanning_caps %} displays alerts in pull requests only when all the lines of code identified by the alert exist in the pull request diff. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#specifying-the-location-for-source-files).
+> {% data variables.product.prodname_code_scanning_caps %} displays alerts in pull requests only when all the lines of code identified by the alert exist in the pull request diff. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#source-file-locations).
 
 {% ifversion code-scanning-autofix %}
 

content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/uploading-a-sarif-file-to-github.md

@@ -28,18 +28,16 @@ contentType: how-tos
 
 {% data reusables.code-scanning.enterprise-enable-code-scanning %}
 
-## About SARIF file uploads for {% data variables.product.prodname_code_scanning %}
+If you use a third-party analysis tool or CI/CD system to scan code for vulnerabilities, you can generate SARIF file and upload it to {% data variables.product.github %}. The best upload method depends on how you generate the SARIF file.
 
-{% data variables.product.prodname_dotcom %} creates {% data variables.product.prodname_code_scanning %} alerts in a repository using information from Static Analysis Results Interchange Format (SARIF) files. SARIF files can be uploaded to a repository using the API or {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system).
-
-You can generate SARIF files using many static analysis security testing tools, including {% data variables.product.prodname_codeql %}. The results must use SARIF version 2.1.0. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning).
-
-You can upload the results using {% data variables.product.prodname_actions %}, the {% data variables.product.prodname_code_scanning %} API, or the {% data variables.product.prodname_codeql_cli %}. The best upload method will depend on how you generate the SARIF file, for example, if you use:
+For example, if you use:
 
 * {% data variables.product.prodname_actions %} to run the {% data variables.product.prodname_codeql %} action, there is no further action required. The {% data variables.product.prodname_codeql %} action uploads the SARIF file automatically when it completes analysis.
-* {% data variables.product.prodname_actions %} to run a SARIF-compatible analysis tool, you could update the workflow to include a final step that uploads the results (see below).
-* The {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} in your CI system, you can use the CLI to upload results to {% data variables.product.prodname_dotcom %} (for more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)).
-* A tool that generates results as an artifact outside of your repository, you can use the {% data variables.product.prodname_code_scanning %} API to upload the file (for more information, see [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)).
+* {% data variables.product.prodname_actions %} to run a SARIF-compatible analysis tool, you could update the workflow to include a final step that uploads the results. See [Uploading a {% data variables.product.prodname_code_scanning %} analysis with {% data variables.product.prodname_actions %}](#uploading-a-code-scanning-analysis-with-github-actions).
+* The {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} in your CI system, you can use the CLI to upload results to {% data variables.product.prodname_dotcom %}. See [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system).
+* A tool that generates results as an artifact outside of your repository, you can use the {% data variables.product.prodname_code_scanning %} API to upload the file. See [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data).
+
+By default, {% data variables.product.prodname_code_scanning %} expects one SARIF results file per analysis for a repository. If you want to upload more than one set of results for a commit in a repository, you must identify each set of results as a unique set.
 
 {% ifversion fpt or ghec %}
 
@@ -61,7 +59,7 @@ For more information, see the [`upload-sarif` action](https://github.com/github/
 
 The `upload-sarif` action can be configured to run when the `push` and `scheduled` event occur. For more information about {% data variables.product.prodname_actions %} events, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows).
 
-If your SARIF file doesn't include `partialFingerprints`, the `upload-sarif` action will calculate the `partialFingerprints` field for you and attempt to prevent duplicate alerts. {% data variables.product.prodname_dotcom %} can only create `partialFingerprints` when the repository contains both the SARIF file and the source code used in the static analysis. For more information about preventing duplicate alerts, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#providing-data-to-track-code-scanning-alerts-across-runs).
+If your SARIF file doesn't include `partialFingerprints`, the `upload-sarif` action will calculate the `partialFingerprints` field for you and attempt to prevent duplicate alerts. {% data variables.product.prodname_dotcom %} can only create `partialFingerprints` when the repository contains both the SARIF file and the source code used in the static analysis. For more information about preventing duplicate alerts, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#data-for-preventing-duplicated-alerts).
 
 {% data reusables.code-scanning.upload-sarif-alert-limit %}
 
@@ -150,9 +148,21 @@ jobs:
           sarif_file: results.sarif
 ```
 
+## Uploading more than one SARIF file for a commit
+
+By default, {% data variables.product.prodname_code_scanning %} expects one SARIF results file per analysis for a repository. Consequently, when you upload a second SARIF results file for a commit, it is treated as a replacement for the original set of data. You may want to upload two different SARIF files for one analysis if, for example, your analysis tool generates a different SARIF file for each language it analyzes or each set of rules it uses. If you want to upload more than one set of results for a commit in a repository, you must identify each set of results as a unique set.
+
+When you upload multiple SARIF files for a commit, you must indicate a "category" for each analysis. The way to specify a category varies according to the analysis method:
+* Using the {% data variables.product.prodname_codeql_cli %} directly, pass the `--sarif-category` argument to the `codeql database analyze` command when you generate SARIF files. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli#about-generating-code-scanning-results-with-the-codeql-cli).
+* Using {% data variables.product.prodname_actions %} with `codeql-action/analyze`, the category is set automatically from the workflow name and any matrix variables (typically, `language`). You can override this by specifying a `category` input for the action, which is useful when you analyze different sections of a monorepo in a single workflow.
+* Using {% data variables.product.prodname_actions %} to upload results from other static analysis tools, then you must specify a `category` input if you upload more than one file of results for the same tool in one workflow. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions).
+* If you are not using either of these approaches, you must specify a unique `runAutomationDetails.id` in each SARIF file to upload. For more information about this property, see [`runAutomationDetails` object](#runautomationdetails-object).
+
+If you upload a second SARIF file for a commit with the same category and from the same tool, the earlier results are overwritten. However, if you try to upload multiple SARIF files for the same tool and category in a single {% data variables.product.prodname_actions %} workflow run, the misconfiguration is detected and the run will fail.
+
 ## Further reading
 
-* [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads)
+* [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads)
 * [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)
 * [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history)
 * [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)

content/code-security/how-tos/scan-code-for-vulnerabilities/integrate-with-existing-tools/using-code-scanning-with-your-existing-ci-system.md

@@ -59,4 +59,4 @@ Once you have analyzed your code, produced SARIF results, and ensured you can au
 
 For specific details on uploading your results to {% data variables.product.github %} using the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github).
 
-By default, {% data variables.product.prodname_code_scanning %} expects one SARIF results file per analysis for a repository. Consequently, when you upload a second SARIF results file for a commit, it is treated as a replacement for the original set of data. You may want to upload two different SARIF files for one analysis if, for example, your analysis tool generates a different SARIF file for each language it analyzes or each set of rules it uses. If you want to upload more than one set of results for a commit in a repository, you must identify each set of results as a unique set. The way to specify a category for a SARIF upload varies according to the analysis method. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#uploading-more-than-one-sarif-file-for-a-commit).
+By default, {% data variables.product.prodname_code_scanning %} expects one SARIF results file per analysis for a repository. Consequently, when you upload a second SARIF results file for a commit, it is treated as a replacement for the original set of data. You may want to upload two different SARIF files for one analysis if, for example, your analysis tool generates a different SARIF file for each language it analyzes or each set of rules it uses. If you want to upload more than one set of results for a commit in a repository, you must identify each set of results as a unique set. The way to specify a category for a SARIF upload varies according to the analysis method.

content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/about-the-tool-status-page.md

@@ -114,4 +114,4 @@ For integrated tools such as {% data variables.product.prodname_codeql %}, you c
 > [!NOTE]
 > If you have set up {% data variables.product.prodname_codeql %} using advanced setup and then set up default setup on the same repository, the {% data variables.code-scanning.tool_status_page %} will only show default setup.
 
-For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning) and [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads).
+For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning) and [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads).

content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/set-code-scanning-merge-protection.md

@@ -21,7 +21,7 @@ contentType: how-tos
 > [!NOTE]
 > * Merge protection with rulesets is not related to status checks. For more information about status checks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks).
 > * Merge protection with rulesets will not apply to merge queue groups or {% data variables.product.prodname_dependabot %} pull requests analyzed by default setup.
-> * All the lines of code identified by an alert must exist in the pull request diff. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#specifying-the-location-for-source-files).
+> * All the lines of code identified by an alert must exist in the pull request diff. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#source-file-locations).
 
 You can use rulesets to prevent pull requests from being merged when one of the following conditions is met:
 

content/code-security/how-tos/scan-code-for-vulnerabilities/troubleshooting/troubleshooting-sarif-uploads/file-too-large.md

@@ -31,7 +31,7 @@ A fatal error occurred: SARIF file is too large
 
 One of these errors is reported if a process attempts to upload a SARIF file that is larger than the maximum size of 10 MB. {% data variables.product.prodname_code_scanning_caps %} does not accept files above this size. There are several different ways to reduce the number of results generated for upload to {% data variables.product.prodname_code_scanning %}.
 
-You could see this error for SARIF files generated by {% data variables.product.prodname_codeql %} or by third-party analysis tools. For information about the limits on uploads, see {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#validating-your-sarif-file).
+You could see this error for SARIF files generated by {% data variables.product.prodname_codeql %} or by third-party analysis tools. For information about the limits on uploads, see {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#file-compatibility).
 
 ## Confirming the cause of the error