Soporte de SARIF para escaneo de código

Acerca del soporte de SARIF

SARIF (Formato de Intercambio de Resultados de Análisis Estático, por sus siglas en inglés) es un Estándar de OASIS que define un formato de archivo de salida. El estándar SARIF se utiliza para optimizar la manera en el que las herramientas de análisis estático comparten sus resultados. Escaneo de código es compatible con un subconjunto del modelo SARIF 2.1.0 JSON.

Para cargar un archivo SARIF desde un motor de análisis estático de código desde un tercero, necesitaras asegurarte de que los archivos cargados utilicen la versión SARIF 2.1.0. GitHub analizará el archivo SARIF y mostrará las alertas utilizando los resultados en tu repositorio como parte de la experiencia del escaneo de código. Para obtener más información, consulta la sección "Cargar un archivo SARIF a GitHub". Para obtener más información acerca del modelo SARIF 2.1.0, consulta sari-schema-2.1.0.json.

Si tu archivo SARIF no incluye partialFingerprints, este campo se calculará cuando cargues el archivo SARIF utilizando GitHub Actions. Para obtener más información, consulta la sección "Configurar el escaneo de código para un repositorio" o "Ejecutar el escaneo de código de CodeQL en tu sistema de IC".

GitHub utiliza propiedades en el archivo SARIF para mostrar alertas. Por ejemplo, la shortDescription y fullDescription aparecen hasta arriba de una alerta de escaneo de código. La location permite a GitHub mostrar anotaciones en tu archivo de código. Para obtener más información, consulta la sección "Administrar las alertas de escaneo de código para tu repositorio".

Si SARIF es nuevo para ti y quieres aprender más, consulta el repositorio SARIF tutorials de Microsoft.

Prevenir alertas duplicadas utilizando huellas dactilares

Cada vez que el flujo de trabajo de GitHub Actions ejecuta un nuevo escaneo de código, los resultados de cada ejecución se procesan y se agregan alertas al repositorio. Para prevenir las alertas duplicadas para el mismo problema, escaneo de código utiliza huellas dactilares para empatara los resultados a través de diversas ejecuciones para que solo aparezcan una vez en la última ejecución para la rama seleccionada. Esto hace posible empatar las alertas con la línea de código correcta cuando se editan los archivos.

GitHub uses the partialFingerprints property in the OASIS standard as an input in the computation of whether two results are logically identical. Specifically, the primaryLocationLineHash is used as a stable intra-file location, which is combined with the repository, file path, and rule data to form the full identity. Para obtener más información, consulta la sección "partialFingerprints property" en la documentación de OASIS.

Los archivos SARIF que crea el Flujo de trabajo de análisis de CodeQL o los que utilizan el Ejecutor de CodeQL incluyen datos de huellas digitales. Si cargas un archivo SARIF utilizando la acción upload-sarif y no se encuentran estos datos, GitHub intentará poblar el campo partialFingerprints desde los archivos de origen. Para obtener más información acerca de cargar los resultados, consulta la sección "Cargar un archivo SARIF a GitHub".

Si cargaste un archivo SARIF sin datos de huella digital utilizando la terminal de la API de /code-scanning/sarifs, se procesarán y se mostrarán las alertas del escaneo de código, pero los usuarios podrían ver alertas duplicadas. Para evitar el ver alertas duplicadas, debes calcular los datos de la huella digital y llenar la propiedad de partialFingerprints antes de que cargues el archivo SARIF. Puede que el script que utiliza la acción upload-sarif te sea útil como punto de inicio: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. Para obtener más información sobre la API, consulta la sección "Cargar un análisis como datos de SARIF".

Validar tu archivo SARIF

Puedes verificar si un archivo SARIF es compatible con el escaneo de código si lo pruebas contra las reglas de ingestión de GitHub. Para obtener más información, visita el Validador de archivos SARIF de Microsoft.

Propiedades compatibles de archivo de salida SARIF

Si utilizas un motor de análisis de código diferente a CodeQL, puedes revisar las propiedades SARIF compatibles para optimizar cómo aparecerán los resultados de tu análisis en GitHub.

Puedes cargar cualquier archivo de salida SARIF 2.1.0 válido, sin embargo, escaneo de código utilizará únicamente las siguientes propiedades compatibles.

Objeto sarifLog

Objeto run

Escaneo de código utiliza el objeto run para filtrar los resultados por herramienta y proporcionar información acerca del origen de un resultado. El objeto run contienen el objeto componente de herramienta tool.driver, el cual contiene información acerca de la herramienta que generó el resultado. Cada run puede tener únicamente resultados para la herramienta de análisis.

Objeto reportingDescriptor

result object

Objeto location

Una ubicación dentro de un artefacto de programación, tal como un archivo en el repositorio o un archivo que se generó durante una compilación.

Objeto physicalLocation

Ejemplos de archivo de salida SARIF

Estos ejemplos de archivos de salida SARIF muestran las propiedades compatibles y los valores de ejemplo.

Ejemplo con las propiedades mínimas requeridas

Este archivo de salida SARIF tiene valores de ejemplo para mostrar las propiedades mínimas requeridas para que los resultados de escaneo de código funcionen como se espera. Si eliminas cualquier propiedad u omites valores, estos datos no se mostrarán correctamente ni se sincronizarán en GitHub.

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "rules": [
            {
              "id": "R01"
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "R01",
          "message": {
            "text": "Result text. This result does not have a rule associated."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "fileURI"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1"
          }
        }
      ]
    }
  ]
}

Ejemplo que muestra todas las propiedades compatibles con SARIF

Este archivo de salida SARIF tiene valores ejemplo para mostrar todas las propiedades de SARIF compatibles con escaneo de código.

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "semanticVersion": "2.0.0",
          "rules": [
            {
              "id": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
              "name": "js/unused-local-variable",
              "shortDescription": {
                "text": "Unused variable, import, function or class"
              },
              "fullDescription": {
                "text": "Unused variables, imports, functions or classes may be a symptom of a bug and should be examined carefully."
              },
              "defaultConfiguration": {
                "level": "note"
              },
              "properties": {
                "tags": [
                  "maintainability"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
              "name": "js/inconsistent-use-of-new",
              "shortDescription": {
                "text": "Inconsistent use of 'new'"
              },
              "fullDescription": {
                "text": "If a function is intended to be a constructor, it should always be invoked with 'new'. Otherwise, it should always be invoked as a normal function, that is, without 'new'."
              },
              "properties": {
                "tags": [
                  "reliability",
                  "correctness",
                  "language-features"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "R01"
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
          "ruleIndex": 0,
          "message": {
            "text": "Unused variable foo."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "main.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1",
            "primaryLocationStartColumnFingerprint": "4"
          }
        },
        {
          "ruleId": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
          "ruleIndex": 1,
          "message": {
            "text": "Function resolvingPromise is sometimes invoked as a constructor (for example [here](1)), and sometimes as a normal function (for example [here](2))."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/promises.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "5061c3315a741b7d:1",
            "primaryLocationStartColumnFingerprint": "7"
          },
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/ParseObject.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2281,
                  "startColumn": 33,
                  "endColumn": 55
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/LiveQueryClient.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 166
                }
              },
              "message": {
                "text": "here"
              }
            }
          ]
        },
        {
          "ruleId": "R01",
          "message": {
            "text": "Specifying both [ruleIndex](1) and [ruleID](2) might lead to inconsistencies."
          },
          "level": "error",
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 54,
                  "startColumn": 10,
                  "endLine": 55,
                  "endColumn": 25
                }
              }
            }
          ],
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 81,
                  "startColumn": 10,
                  "endColumn": 18
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 82,
                  "startColumn": 10,
                  "endColumn": 21
                }
              },
              "message": {
                "text": "here"
              }
            }
          ],
          "codeFlows": [
            {
              "threadFlows": [
                {
                  "locations": [
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "startLine": 11,
                            "endLine": 29,
                            "startColumn": 10,
                            "endColumn": 18
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        },
                        "message": {
                          "text": "Rule has index 0"
                        }
                      }
                    },
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "endColumn": 47,
                            "startColumn": 12,
                            "startLine": 12
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        }
                      }
                    }
                  ]
                }
              ]
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "ABC:2"
          }
        }
      ],
      "columnKind": "utf16CodeUnits"
    }
  ]
}