Acerca de la salida de 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 análisis de base de datos.
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
| CodeQL versión | Tipo de formato | Changes |
|---|---|---|
| 2.0.0 | sarifv2.1.0 | Primera versión de este formato. |
Futuros cambios en la salida de datos
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 del SARIF generado y nos aseguraremos de que:
-
Los campos marcados como que siempre se generan 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 las salidas SARIF de CodeQL deben poder manejar 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.
Objeto sarifLog
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
$schema | Proporciona un vínculo al esquema SARIF. | |
version | La versión de SARIF utilizada para generar el resultado. | |
runs | Una matriz que contiene un único objeto de ejecución para un lenguaje. |
Objeto run
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
tool | Ninguno | |
artifacts | Una matriz que contiene al menos un objeto de artefacto para cada archivo referido en un resultado. | |
results | Ninguno | |
newLineSequences | Ninguno | |
columnKind | Ninguno | |
properties | El diccionario de propiedades contendrá el elemento semmle.formatSpecifier, que identifica el especificador de formato pasado a la CodeQL CLI. |
Objeto tool
| Nombre de la propiedad JSON | ¿Generado siempre? | Notas |
|---|---|---|
driver | Ninguno |
Objeto toolComponent
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
name | Configurado en "Cadena de herramientas de línea de comandos de CodeQL" para la salida de las herramientas 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 | Establecido en "GitHub". | |
version | Establecer 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 defaultConfiguration. |
Objeto reportingDescriptor (para regla)
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 genera? | 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 su organización define la propiedad @opaqueid en la consulta, esta se usará. | |
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. |
Objeto artifact
| Nombre de la propiedad JSON | ¿Siempre se generó? | Notas |
|---|---|---|
location | Un 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. |
Objeto artifactLocation
| Nombre de la propiedad JSON | ¿Se genera siempre? | Notas |
|---|---|---|
uri | Ninguno | |
index | Ninguno | |
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. |
Objeto 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 | ¿Se genera siempre? | Notas |
|---|---|---|
ruleId | Consulta la descripción de la propiedad id en el objeto reportingDescriptor (para reglas). | |
ruleIndex | Ninguno | |
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á. |
Objeto location
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
physicalLocation | Ninguno | |
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. |
Objeto physicalLocation
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
artifactLocation | Ninguno | |
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 una snippet asociada. |
Objeto region
CodeQL genera dos tipos de objeto region:
-
Regiones de desfase de línea/columna
-
Regiones de desplazamiento y longitud 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 genera? | Notas |
|---|---|---|
startLine | Ninguno | |
startColumn | No se incluye si es igual al valor predeterminado 1. | |
endLine | No se incluye si es igual a startLine. | |
endColumn | Ninguno | |
snippet | Ninguno |
Para las regiones de longitud y desplazamiento de caracteres, se establecerán las siguientes propiedades:
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
charOffset | Siempre y cuando no se rellenen las propiedades startLine, startColumn, endLine y endColumn. | |
charLength | Si no se han rellenado las propiedades startLine, startColumn, endLine y endColumn. | |
snippet | Ninguno |
Objeto codeFlow
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
threadFlows | Ninguno |
Objeto threadFlow
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
locations | Ninguno |
Objeto threadFlowLocation
| Nombre de la propiedad JSON | ¿Siempre se genera? | Notas |
|---|---|---|
location | Ninguno |