Saída SARIF da CLI do CodeQL

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 obter mais informações de como selecionar um formato de arquivo para os resultados da análise, confira o comando database analyze na documentação do CodeQL.

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 do 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:

• Nenhum campo marcado como "Sempre" que está sendo gerado seja removido.

• As circunstâncias sob as quais os campos "Opcionais" são gerados possam 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	Quando isso é gerado?	Observações
$schema	Sempre	Fornece um link para o esquema SARIF.
version	Sempre	A versão do SARIF usada para gerar a saída.
runs	Sempre	Uma matriz que contém um só objeto de execução, para uma linguagem.

Objeto run

Nome da propriedade JSON	Quando isso é gerado?	Observações
tool	Sempre	–
originalUriBaseIds	Sempre	Um dicionário de uriBaseIds para artifactLocations que representa os locais originais no computador de análise. No mínimo, isso conterá o %SRCROOT% uriBaseId, que representa o local raiz no computador de análise do código-fonte do projeto analisado. Cada artifactLocation uma conterá as propriedades uri e description.
artifacts	Sempre	Uma matriz que contém pelo menos um objeto de artefato para cada arquivo referenciado em um resultado.
results	Sempre	–
newLineSequences	Sempre	–
columnKind	Sempre	–
properties	Sempre	O dicionário de propriedades conterá o semmle.formatSpecifier, que identifica o especificador de formato passado à CodeQL CLI.

Objeto tool

Nome da propriedade JSON	Quando isso é gerado?	Observações
driver	Sempre	–

Objeto toolComponent

Nome da propriedade JSON	Quando isso é gerado?	Observações
name	Sempre	Definido 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	Sempre	Definido como “GitHub”.
version	Sempre	Definido como a versão de lançamento do CodeQL, por exemplo, "2.0.0".
rules	Sempre	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	Quando isso é gerado?	Observações
id	Sempre	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	Sempre	Conterá a propriedade @id especificada na consulta. Confira a propriedade id acima para obter um exemplo.
shortDescription	Sempre	Conterá a propriedade @name especificada na consulta que define a regra.
fullDescription	Sempre	Conterá a propriedade @description especificada na consulta que define a regra.
defaultConfiguration	Sempre	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	Quando isso é gerado?	Observações
location	Sempre	Um objeto artifactLocation.
index	Sempre	O índice do objeto artifact.
contents	Opcionalmente	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	Quando isso é gerado?	Observações
uri	Sempre	–
index	Sempre	–
uriBaseId	Opcionalmente	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 ao 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	Quando isso é gerado?	Observações
ruleId	Sempre	Confira a descrição da propriedade id no objeto reportingDescriptor (da regra).
ruleIndex	Sempre	–
message	Sempre	Uma mensagem que descreve os problemas que ocorrem neste local. Essa mensagem pode ser um SARIF "Mensagem com espaço reservado", contendo links que se referem a locais na propriedade relatedLocations.
locations	Sempre	Uma matriz que contém um só objeto location.
partialFingerprints	Sempre	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	Opcionalmente	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	Opcionalmente	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	Opcionalmente	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	Quando isso é gerado?	Observações
physicalLocation	Sempre	–
id	Opcionalmente	Os objetos location que aparecem na matriz relatedLocations de um objeto resultpodem conter a propriedade id.
message	Opcionalmente	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	Quando isso é gerado?	Observações
artifactLocation	Sempre	–
region	Opcionalmente	Se o physicalLocation determinado existir em um arquivo de texto, como um arquivo de código-fonte, a propriedade region poderá estar presente.
contextRegion	Opcionalmente	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	Quando isso é gerado?	Observações
startLine	Sempre	–
startColumn	Opcionalmente	Não incluído se for igual ao valor padrão 1.
endLine	Opcionalmente	Não incluído se idêntico a startLine.
endColumn	Sempre	–
snippet	Opcionalmente	–

Para regiões de deslocamento e comprimento de caracteres, as seguintes propriedades serão definidas:

Nome da propriedade JSON	Quando isso é gerado?	Observações
charOffset	Opcionalmente	Fornecido se startLine, startColumn, endLine e endColumn não forem preenchidos.
charLength	Opcionalmente	Fornecido se startLine, startColumn, endLine e endColumn não forem preenchidos.
snippet	Opcionalmente	–

Objeto codeFlow

Nome da propriedade JSON	Quando isso é gerado?	Observações
threadFlows	Sempre	–

Objeto threadFlow

Nome da propriedade JSON	Quando isso é gerado?	Observações
locations	Sempre	–

Objeto threadFlowLocation

Nome da propriedade JSON	Quando isso é gerado?	Observações
location	Sempre	–