Skip to main content

GitHub AE es una versión limitada en este momento.

Salida SARIF de la CLI de CodeQL

Puedes generar una salida SARIF desde la CodeQL CLI y compartir los resultados de análisis estático con otros sistemas.

Las licencias de GitHub CodeQL se otorgan por usuario tras la instalación. Puedes usar CodeQL solo para determinadas tareas según las restricciones de las licencias. Para obtener más información, vea «Acerca de la CLI de CodeQL».

Si tienes una licencia de GitHub Advanced Security, puedes usar CodeQL para el análisis automatizado, la integración continua y la entrega continua. Para obtener más información, vea «Acerca de GitHub Advanced Security».

Acerca de la salida SARIF

SARIF es un formato diseñado para representar la salida de una amplia variedad de herramientas de análisis estático, y hay muchas características en la especificación SARIF que se consideran "opcionales". En este documento se explica la salida generada al usar el tipo de formato sarifv2.1.0, que corresponde a la especificación SARIF v2.1.0.csd1. Para obtener más información sobre cómo seleccionar un formato de archivo para los resultados del análisis, consulta "database analyze".

Especificación y esquema SARIF

Este artículo debe leerse junto con la especificación SARIF detallada. Para obtener más información sobre la especificación y el esquema SARIF, consulta la documentación sobre la especificación SARIF.

Notas de cambios

Cambios entre versiones

Versión de CodeQLTipo de formatoCambios
2.0.0sarifv2.1.0Primera versión de este formato.

Futuros cambios en la salida

La salida generada para un tipo de formato específico (por ejemplo, sarifv2.1.0) puede cambiar en futuras versiones de CodeQL. Nos esforzaremos por mantener la compatibilidad con versiones anteriores para los consumidores de la salida SARIF generada; para ello nos aseguraremos de que:

  • Los campos marcados como siempre generados nunca se quitarán.

  • En el caso de los campos marcados como no siempre generados, las circunstancias en las que se generan los campos pueden cambiar. Los consumidores de salidas SARIF de CodeQL deben ser sólidos frente a la presencia o ausencia de estos campos.

Se pueden agregar nuevos campos de salida en futuras versiones con el mismo tipo de formato; no se considera que estos campos interrumpan la compatibilidad con versiones anteriores y los consumidores deben ser sólidos frente a la adición de nuevos campos.

Se pueden agregar nuevos tipos de argumentos de formato en versiones futuras de CodeQL, por ejemplo, para admitir nuevas versiones de SARIF. Estos tipos no ofrecen ninguna garantía de compatibilidad con versiones anteriores, a menos que se indique explícitamente.

Objetos SARIF generados

Aquí se detallan los componentes SARIF que se pueden generar, así como las circunstancias específicas. Se han omitido las propiedades que no se generan nunca.

Objecto sarifLog

Nombre de la propiedad JSON¿Siempre se generó?Notas
$schemaProporciona un vínculo al esquema SARIF.
versionLa versión de SARIF usada para generar la salida.
runsUna matriz que contiene un único objeto de ejecución para un lenguaje.

Objecto run

Nombre de la propiedad JSON¿Siempre se generó?Notas
toolNone
artifactsUna matriz que contiene al menos un objeto artifact para cada archivo al que se hace referencia en un resultado.
resultsNone
newLineSequencesNone
columnKindNone
propertiesEl diccionario de propiedades contendrá el objeto semmle.formatSpecifier, que identifica el especificador de formato pasado a la CodeQL CLI.

Objecto tool

Nombre de la propiedad JSON¿Siempre se generó?Notas
driverNone

Objecto toolComponent

Nombre de la propiedad JSON¿Siempre se generó?Notas
namePropiedad establecida en "Cadena de herramientas de línea de comandos de CodeQL" para la salida de las herramientas de la CodeQL CLI. Ten en cuenta que, si la salida se ha generado mediante una herramienta diferente, se notifica una propiedad name diferente, y es posible que el formato no sea como el descrito aquí.
organizationPropiedad establecida en "GitHub".
versionPropiedad establecida en la versión de CodeQL, por ejemplo, "2.0.0".
rulesMatriz de objetos reportingDescriptor que representan reglas. Esta matriz contendrá, como mínimo, todas las reglas que se han ejecutado durante el análisis, aunque también puede contener reglas que estaban disponibles pero no se han ejecutado. Obtén más información sobre cómo habilitar las consultas en la propiedad defaultConfiguration.

Objeto reportingDescriptor (para reglas)

Los objetos reportingDescriptor se pueden usar en varios lugares en la especificación SARIF. Cuando se incluye un objeto reportingDescriptor en la matriz de reglas de un objeto toolComponent, sus propiedades son las siguientes.

Nombre de la propiedad JSON¿Siempre se generó?Notas
idContendrá la propiedad @id especificada en la consulta que define la regla, y suele tener el formato language/rule-name (por ejemplo, cpp/unsafe-format-string). Si tu organización define la propiedad @opaqueid en la consulta, se usará esta propiedad.
nameContendrá la propiedad @id especificada en la consulta. Consulta la propiedad id más arriba para obtener un ejemplo.
shortDescriptionContendrá la propiedad @name especificada en la consulta que define la regla.
fullDescriptionContendrá la propiedad @description especificada en la consulta que define la regla.
defaultConfigurationUn objeto reportingConfiguration, con la propiedad habilitada establecida en "true" o "false", y una propiedad de nivel establecida según la propiedad @severity especificada en la consulta que define la regla. Se omite si no se ha especificado la propiedad @severity.

Objecto artifact

Nombre de la propiedad JSON¿Siempre se generó?Notas
locationObjeto artifactLocation.
indexEl índice del objeto artifact.
contentsSi los resultados se generan usando la marca --sarif-add-file-contents y el código fuente está disponible en el momento en que se genera el archivo SARIF, la propiedad contents se rellena con un objeto artifactContent, con la propiedad text establecida.

Objecto artifactLocation

Nombre de la propiedad JSON¿Siempre se generó?Notas
uriNone
indexNone
uriBaseIdSi el archivo guarda relación con alguna ubicación abstracta conocida, como la ubicación del origen raíz en la máquina de análisis, se establecerá esta ubicación.

Objecto result

La composición de los resultados depende de las opciones proporcionadas a CodeQL. De forma predeterminada, los resultados se agrupan por cadena de formato de mensaje única y ubicación principal. Por lo tanto, dos resultados que se produzcan en la misma ubicación con el mismo mensaje subyacente, se mostrarán como un único resultado en la salida. Este comportamiento se puede deshabilitar mediante la marca --ungroup-results, en cuyo caso no se agrupará ningún resultado.

Nombre de la propiedad JSON¿Siempre se generó?Notas
ruleIdConsulta la descripción de la propiedad id en el objeto reportingDescriptor (para reglas).
ruleIndexNone
messageUn mensaje que describe los problemas encontrados en esta ubicación. Este mensaje puede ser un "mensaje con marcador de posición" con formato SARIF que contiene vínculos a ubicaciones de la propiedad relatedLocations.
locationsUna matriz que contiene un único objeto location.
partialFingerprintsDiccionario de tipos de huellas digitales con nombre para la huella digital. Como mínimo, contendrá un valor para primaryLocationLineHash, que proporciona una huella digital basada en el contexto de la ubicación principal.
codeFlowsEsta matriz se puede rellenar con uno o varios objetos codeFlow si la consulta que define la regla para este resultado es de tipo @kind path-problem.
relatedLocationsEsta matriz se rellenará si la consulta que define la regla para este resultado tiene un mensaje con opciones de marcador de posición. Cada ubicación única se incluye una vez.
suppressionsSi se suprime el resultado, esta propiedad contendrá un solo objeto suppression, con la propiedad @kind establecida en IN_SOURCE. Si este resultado no se suprime, pero hay al menos un resultado suprimido, esto se establecerá en una matriz vacía; de lo contrario, no se establecerá.

Objecto location

Nombre de la propiedad JSON¿Siempre se generó?Notas
physicalLocationNone
idLos objetos location que aparecen en la matriz relatedLocations de un objeto resultpueden contener la propiedad id.
messageLos objetos location pueden contener la propiedad message si:

- Aparecen en la matriz relatedLocations de un objeto result que puede contener la propiedad message.

- Aparecen en la propiedad threadFlowLocation.location.

Objecto physicalLocation

Nombre de la propiedad JSON¿Siempre se generó?Notas
artifactLocationNone
regionSi el objeto physicalLocation especificado existe en un archivo de texto, como un archivo de código fuente, entonces la propiedad region puede estar presente.
contextRegionPuede estar presente si esta ubicación tiene asociada una propiedad snippet.

Objecto region

CodeQL genera dos tipos de objeto region:

  • Regiones de desplazamiento de línea/columna

  • Regiones de longitud y desplazamiento de caracteres

Cualquier región generada por CodeQL se puede especificar en cualquiera de los dos formatos, y los consumidores deben controlar de forma sólida cualquiera de los dos tipos.

En el caso de las regiones de desplazamiento de línea/columna, se establecerán las siguientes propiedades:

Nombre de la propiedad JSON¿Siempre se generó?Notas
startLineNone
startColumnNo se incluye si es igual al valor predeterminado 1.
endLineNo se incluye si es igual a startLine.
endColumnNone
snippetNone

Para las regiones de longitud y desplazamiento de caracteres, se establecerán las siguientes propiedades:

Nombre de la propiedad JSON¿Siempre se generó?Notas
charOffsetSi no se rellenan las propiedades startLine, startColumn, endLine y endColumn.
charLengthSi no se rellenan las propiedades startLine, startColumn, endLine y endColumn.
snippetNone

Objecto codeFlow

Nombre de la propiedad JSON¿Siempre se generó?Notas
threadFlowsNone

Objecto threadFlow

Nombre de la propiedad JSON¿Siempre se generó?Notas
locationsNone

Objecto threadFlowLocation

Nombre de la propiedad JSON¿Siempre se generó?Notas
locationNone