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 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:
-
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 |
|---|---|---|
$schema | Proporciona un vínculo al esquema SARIF. | |
version | La versión de SARIF usada para generar la salida. | |
runs | Una matriz que contiene un único objeto de ejecución para un lenguaje. |
Objecto run
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
tool | None | |
artifacts | Una matriz que contiene al menos un objeto artifact para cada archivo al que se hace referencia en un resultado. | |
results | None | |
newLineSequences | None | |
columnKind | None | |
properties | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
driver | None |
Objecto toolComponent
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
name | 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 | Propiedad establecida en "GitHub". | |
version | Propiedad establecida en la versión de CodeQL, por ejemplo, "2.0.0". | |
rules | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
id | 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 | Contendrá la propiedad @id especificada en la consulta. Consulta la propiedad id más arriba para obtener un ejemplo. | |
shortDescription | Contendrá la propiedad @name especificada en la consulta que define la regla. | |
fullDescription | Contendrá la propiedad @description especificada en la consulta que define la regla. | |
defaultConfiguration | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
location | Objeto artifactLocation. | |
index | El índice del objeto artifact. | |
contents | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
uri | None | |
index | None | |
uriBaseId | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
ruleId | Consulta la descripción de la propiedad id en el objeto reportingDescriptor (para reglas). | |
ruleIndex | None | |
message | 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 | Una matriz que contiene un único objeto location. | |
partialFingerprints | 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 | 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 | 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 | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
physicalLocation | None | |
id | Los objetos location que aparecen en la matriz relatedLocations de un objeto resultpueden contener la propiedad id. | |
message | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
artifactLocation | None | |
region | 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 | 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 | ¿Siempre se generó? | Notas |
|---|---|---|
startLine | None | |
startColumn | No se incluye si es igual al valor predeterminado 1. | |
endLine | No se incluye si es igual a startLine. | |
endColumn | None | |
snippet | None |
Para las regiones de longitud y desplazamiento de caracteres, se establecerán las siguientes propiedades:
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
charOffset | Si no se rellenan las propiedades startLine, startColumn, endLine y endColumn. | |
charLength | Si no se rellenan las propiedades startLine, startColumn, endLine y endColumn. | |
snippet | None |
Objecto codeFlow
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
threadFlows | None |
Objecto threadFlow
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
locations | None |
Objecto threadFlowLocation
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
location | None |