Sobre a saída SARIF
O SARIF foi projetado para representar a saída de uma ampla gama de ferramentas de análise estática, e há muitos recursos na especificação SARIF que são considerados "opcionais". Este documento detalha a saída produzida ao usar o tipo de formato sarifv2.1.0, que corresponde à especificação SARIF v2.1.0.csd1. Para saber mais sobre como selecionar um formato de arquivo para os resultados da análise, confira database analyze.
Especificação e esquema do SARIF
Este artigo deve ser lido junto com a especificação detalhada do SARIF. Para obter mais informações sobre a especificação e o esquema do SARIF, confira a documentação da especificação do SARIF.
Observações sobre a alteração
Alterações entre versões
| Versão CodeQL | Tipo de formato | Alterações |
|---|---|---|
| 2.0.0 | sarifv2.1.0 | Primeira versão desse formato. |
Alterações futuras na saída
A saída produzida para um determinado tipo de formato específico (por exemplo, sarifv2.1.0) poderá ser alterada em versões futuras do CodeQL. Vamos nos esforçar para manter a compatibilidade com versões anteriores para os consumidores do SARIF gerado, garantindo que:
-
Campos marcados como sempre sendo gerados nunca serão removidos.
-
Para campos marcados como nem sempre sendo gerados, as circunstâncias sob as quais os campos são gerados podem ser alteradas. Os consumidores da saída SARIF do CodeQL devem contar com a presença ou a ausência desses campos.
Novos campos de saída podem ser adicionados em versões futuras no mesmo tipo de formato. Eles não são considerados como uma quebra da compatibilidade com versões anteriores e os consumidores devem contar com a presença de campos recém-adicionados.
Novos tipos de argumento de formato podem ser adicionados em versões futuras do CodeQL. Por exemplo, para dar suporte a novas versões do SARIF. Eles não têm garantia de compatibilidade com versões anteriores, a menos que isso seja documentado explicitamente.
Objetos SARIF gerados
Isso detalha cada componente SARIF que pode ser gerado, juntamente com circunstâncias específicas. Omitimos todas as propriedades que nunca são geradas.
Objeto sarifLog
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
$schema | Fornece um link para o esquema SARIF. | |
version | A versão do SARIF usada para gerar a saída. | |
runs | Uma matriz que contém um só objeto de execução, para uma linguagem. |
Objeto run
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
tool | Nenhum | |
artifacts | Uma matriz que contém pelo menos um objeto de artefato para cada arquivo referenciado em um resultado. | |
results | Nenhum | |
newLineSequences | Nenhum | |
columnKind | Nenhum | |
properties | O dicionário de propriedades conterá o semmle.formatSpecifier, que identifica o especificador de formato passado à CodeQL CLI. |
Objeto tool
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
driver | Nenhum |
Objeto toolComponent
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
name | Defina isso como "Cadeia de ferramentas de linha de comando do CodeQL" para saída das ferramentas da CodeQL CLI. Observe que, se a saída foi gerada usando uma ferramenta diferente, um name diferente será relatado e o formato poderá não ser o descrito aqui. | |
organization | Defina isso como "GitHub". | |
version | Defina isso como a versão de lançamento do CodeQL, por exemplo, "2.0.0". | |
rules | A matriz de objetos reportingDescriptor que representa as regras. Essa matriz conterá, no mínimo, todas as regras que foram executadas durante essa análise, mas poderá conter regras que estavam disponíveis, mas não foram executadas. Para obter mais detalhes sobre como habilitar consultas, confira defaultConfiguration. |
Objeto reportingDescriptor (para regra)
Os objetos reportingDescriptor podem ser usados em vários locais na especificação do SARIF. Quando um reportingDescriptor é incluído na matriz de regras de um objeto toolComponent, ele tem as propriedades a seguir.
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
id | Conterá a propriedade @id especificada na consulta que define a regra, que geralmente está no formato language/rule-name (por exemplo cpp/unsafe-format-string). Se sua organização definir a propriedade @opaqueid na consulta, ela será usada. | |
name | Conterá a propriedade @id especificada na consulta. Confira a propriedade id acima para obter um exemplo. | |
shortDescription | Conterá a propriedade @name especificada na consulta que define a regra. | |
fullDescription | Conterá a propriedade @description especificada na consulta que define a regra. | |
defaultConfiguration | Um objeto reportingConfiguration, com a propriedade habilitada definida como true ou false, e uma propriedade de nível definida de acordo com a propriedade @severity especificada na consulta que define a regra. Omitido se a propriedade @severity não for especificada. |
Objeto artifact
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
location | Um objeto artifactLocation. | |
index | O índice do objeto artifact. | |
contents | Se os resultados forem gerados usando o sinalizador --sarif-add-file-contentse o código-fonte estiver disponível no momento em que o arquivo SARIF for gerado, a propriedade contents será preenchida com um objeto artifactContent, com a propriedade text definida. |
Objeto artifactLocation
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
uri | Nenhum | |
index | Nenhum | |
uriBaseId | Se o arquivo for relativo a algum local abstrato conhecido, como o local de origem raiz no computador de análise, essa opção será definida. |
Objeto result
A composição dos resultados depende das opções fornecidas para CodeQL. Por padrão, os resultados são agrupados por uma cadeia de caracteres de formato de mensagem exclusiva e um local primário. Portanto, dois resultados que ocorrem no mesmo local com a mesma mensagem subjacente aparecerão como um só resultado na saída. Esse comportamento pode ser desabilitado usando o sinalizador --ungroup-results e, nesse caso, nenhum resultado será agrupado.
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
ruleId | Confira a descrição da propriedade id no objeto reportingDescriptor (da regra). | |
ruleIndex | Nenhum | |
message | Uma mensagem que descreve os problemas que ocorrem neste local. Essa mensagem pode ser uma "mensagem com espaço reservado" SARIF, contendo links que se referem a locais na propriedade relatedLocations. | |
locations | Uma matriz que contém um só objeto location. | |
partialFingerprints | Um dicionário de tipos de impressão digital nomeados para a impressão digital. Isso conterá, no mínimo, um valor para o primaryLocationLineHash, que fornece uma impressão digital com base no contexto do local primário. | |
codeFlows | Essa matriz poderá ser preenchida com um ou mais objetos codeFlow se a consulta que define a regra desse resultado for @kind path-problem. | |
relatedLocations | Essa matriz será preenchida se a consulta que define a regra desse resultado tiver uma mensagem com opções de espaço reservado. Cada local exclusivo é incluído uma vez. | |
suppressions | Se o resultado for suprimido, ele conterá um só objeto suppression, com a propriedade @kind definida como IN_SOURCE. Se esse resultado não for suprimido, mas houver pelo menos um resultado com supressão, isso será definido como uma matriz vazia. Caso contrário, isso não será definido. |
Objeto location
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
physicalLocation | Nenhum | |
id | Os objetos location que aparecem na matriz relatedLocations de um objeto resultpodem conter a propriedade id. | |
message | Os objetos location poderão conter a propriedade message se:– Aparecerem na matriz relatedLocations de um objeto result que possa conter a propriedade message.– Aparecem na propriedade threadFlowLocation.location. |
Objeto physicalLocation
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
artifactLocation | Nenhum | |
region | Se o physicalLocation determinado existir em um arquivo de texto, como um arquivo de código-fonte, a propriedade region poderá estar presente. | |
contextRegion | Poderá estar presente se esse local tiver um snippet associado. |
Objeto region
Há dois tipos de objeto region produzidos pelo CodeQL:
-
Regiões de deslocamento de linha/coluna
-
Regiões de deslocamento e comprimento de caracteres
Qualquer região produzida pelo CodeQL pode ser especificada em qualquer formato e os consumidores devem conseguir lidar com qualquer tipo.
Para regiões de deslocamento de linha/coluna, as seguintes propriedades serão definidas:
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
startLine | Nenhum | |
startColumn | Não incluído se for igual ao valor padrão 1. | |
endLine | Não incluído se idêntico a startLine. | |
endColumn | Nenhum | |
snippet | Nenhum |
Para regiões de deslocamento e comprimento de caracteres, as seguintes propriedades serão definidas:
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
charOffset | Fornecido se startLine, startColumn, endLine e endColumn não forem preenchidos. | |
charLength | Fornecido se startLine, startColumn, endLine e endColumn não forem preenchidos. | |
snippet | Nenhum |
Objeto codeFlow
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
threadFlows | Nenhum |
Objeto threadFlow
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
locations | Nenhum |
Objeto threadFlowLocation
| Nome da propriedade JSON | Sempre gerado? | Observações |
|---|---|---|
location | Nenhum |