code-scanning: Add a section on rules and results (#29161)

content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md

@@ -55,6 +55,16 @@ SARIF files created by the {% data variables.product.prodname_codeql_workflow %}
 
 If you upload a SARIF file without fingerprint data using the `/code-scanning/sarifs` API endpoint, the {% data variables.product.prodname_code_scanning %} alerts will be processed and displayed, but users may see duplicate alerts. To avoid seeing duplicate alerts, you should calculate fingerprint data and populate the `partialFingerprints` property before you upload the SARIF file. You may find the script that the `upload-sarif` action uses a helpful starting point: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. For more information about the API, see "[Upload an analysis as SARIF data](/rest/reference/code-scanning#upload-an-analysis-as-sarif-data)."
 
+## Understanding rules and results
+
+SARIF files support both rules and results. The information stored in these elements is similar but serves different purposes.
+
+- Rules are an array of `reportingDescriptor` objects that are included in the `toolComponent` object. This is where you store details of the rules that are run during analysis. Information in these objects should change infrequently, typically when you update the tool.
+
+- Results are stored as a series of `result` objects under `results` in the `run` object. Each `result` object contains details for one alert in the codebase. Within the `results` object, you can reference the rule that detected the alert.
+
+When you compare SARIF files generated by analyzing different codebases with the same tool and rules, you should see differences in the results of the analyses but not in the rules.
+
 ## Validating your SARIF file
 
 <!--UI-LINK: When code scanning fails, the error banner shown in the Security > Code scanning alerts view links to this anchor.-->
@@ -98,6 +108,8 @@ Any valid SARIF 2.1.0 output file can be uploaded, however, {% data variables.pr
 
 ### `reportingDescriptor` object
 
+This is where you store details of the rules that are run during analysis. Information in these objects should change infrequently, typically when you update the tool. For more information,  see "[Understanding rules and results](#understanding-rules-and-results)" above.
+
 | Name | Description |
 |----|----|
 | `id` |  **Required.** A unique identifier for the rule. The `id` is referenced from other parts of the SARIF file and may be used by {% data variables.product.prodname_code_scanning %} to display URLs on {% data variables.product.prodname_dotcom %}. |
@@ -114,6 +126,8 @@ Any valid SARIF 2.1.0 output file can be uploaded, however, {% data variables.pr
 
 ### `result` object
 
+Each `result` object contains details for one alert in the codebase. Within the `results` object, you can reference the rule that detected the alert. For more information,  see "[Understanding rules and results](#understanding-rules-and-results)" above.
+
 {% data reusables.code-scanning.upload-sarif-alert-limit %}
 
 | Name | Description |