Salida SARIF de la CLI de CodeQL

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 la información sobre el comando database analyze en la documentación de CodeQL.

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 CodeQL	Tipo de formato	Cambios
2.0.0	sarifv2.1.0	Primera 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:

• No se quitará ningún campo generado marcado como "Siempre".

• Las circunstancias en las que se generan los campos "opcionales" 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	¿Cuándo se genera?	Notas
$schema	Siempre	Proporciona un vínculo al esquema SARIF.
version	Siempre	La versión de SARIF usada para generar la salida.
runs	Siempre	Una matriz que contiene un único objeto de ejecución para un lenguaje.

Objecto run

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
tool	Siempre	–
originalUriBaseIds	Siempre	Un diccionario de uriBaseIds para objetos artifactLocation que representan las ubicaciones originales en la máquina de análisis. Como mínimo, contendrá el objeto uriBaseId de %SRCROOT%, que representa la ubicación raíz en la máquina de análisis del código fuente del proyecto analizado. Cada objeto artifactLocation contendrá las propiedades uri y description.
artifacts	Siempre	Una matriz que contiene al menos un objeto artifact para cada archivo al que se hace referencia en un resultado.
results	Siempre	–
newLineSequences	Siempre	–
columnKind	Siempre	–
properties	Siempre	El 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	¿Cuándo se genera?	Notas
driver	Siempre	–

Objecto toolComponent

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
name	Siempre	Propiedad 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í.
organization	Siempre	Propiedad establecida en "GitHub".
version	Siempre	Propiedad establecida en la versión de CodeQL, por ejemplo, "2.0.0".
rules	Siempre	Matriz 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	¿Cuándo se genera?	Notas
id	Siempre	Contendrá 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.
name	Siempre	Contendrá la propiedad @id especificada en la consulta. Consulta la propiedad id más arriba para obtener un ejemplo.
shortDescription	Siempre	Contendrá la propiedad @name especificada en la consulta que define la regla.
fullDescription	Siempre	Contendrá la propiedad @description especificada en la consulta que define la regla.
defaultConfiguration	Siempre	Un 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	¿Cuándo se genera?	Notas
location	Siempre	Objeto artifactLocation.
index	Siempre	El índice del objeto artifact.
contents	Opcionalmente	Si 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	¿Cuándo se genera?	Notas
uri	Siempre	–
index	Siempre	–
uriBaseId	Opcionalmente	Si 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	¿Cuándo se genera?	Notas
ruleId	Siempre	Consulta la descripción de la propiedad id en el objeto reportingDescriptor (para reglas).
ruleIndex	Siempre	–
message	Siempre	Un 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.
locations	Siempre	Una matriz que contiene un único objeto location.
partialFingerprints	Siempre	Diccionario 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.
codeFlows	Opcionalmente	Esta 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.
relatedLocations	Opcionalmente	Esta 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.
suppressions	Opcionalmente	Si 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	¿Cuándo se genera?	Notas
physicalLocation	Siempre	–
id	Opcionalmente	Los objetos location que aparecen en la matriz relatedLocations de un objeto resultpueden contener la propiedad id.
message	Opcionalmente	Los 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	¿Cuándo se genera?	Notas
artifactLocation	Siempre	–
region	Opcionalmente	Si el objeto physicalLocation especificado existe en un archivo de texto, como un archivo de código fuente, entonces la propiedad region puede estar presente.
contextRegion	Opcionalmente	Puede 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	¿Cuándo se genera?	Notas
startLine	Siempre	–
startColumn	Opcionalmente	No se incluye si es igual al valor predeterminado 1.
endLine	Opcionalmente	No se incluye si es igual a startLine.
endColumn	Siempre	–
snippet	Opcionalmente	–

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

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
charOffset	Opcionalmente	Si no se rellenan las propiedades startLine, startColumn, endLine y endColumn.
charLength	Opcionalmente	Si no se rellenan las propiedades startLine, startColumn, endLine y endColumn.
snippet	Opcionalmente	–

Objecto codeFlow

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
threadFlows	Siempre	–

Objecto threadFlow

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
locations	Siempre	–

Objecto threadFlowLocation

Nombre de la propiedad JSON	¿Cuándo se genera?	Notas
location	Siempre	–