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 saber mais sobre como selecionar um formato de arquivo para os resultados da análise, confira análise de banco de dados.

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	Changes
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 retroativa 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 do CodeQL SARIF devem ser robustos à 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 quaisquer condições específicas. Omitimos todas as propriedades que nunca são geradas.

Objeto `sarifLog`

Nome da propriedade JSON	Sempre gerado?	Anotaçõ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 automaticamente?	Anotações
`tool`		None
`artifacts`		Uma matriz que contém pelo menos um objeto de artefato para cada arquivo referenciado em um resultado.
`results`		None
`newLineSequences`		None
`columnKind`		None
`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?	Anotações
`driver`		None

Objeto `toolComponent`

Nome da propriedade JSON	Sempre é gerado?	Anotaçõ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 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?	Anotaçõ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?	Anotações
`location`		Um `artifactLocation` objeto.
`index`		O índice do objeto `artifact`.
`contents`		Se os resultados forem gerados usando o sinalizador `--sarif-add-file-contents`e 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?	Anotações
`uri`		None
`index`		None
`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 string de formato de mensagem única e localização primária. 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?	Anotações
`ruleId`		Confira a descrição da propriedade `id` no objeto `reportingDescriptor` (da regra).
`ruleIndex`		None
`message`		Uma mensagem que descreve os problemas que ocorrem neste local. Essa mensagem pode ser uma SARIF "Message with placeholder", contendo links que se referem a locais na propriedade `relatedLocations`.
`locations`		Uma matriz que contém um só objeto `location`.
`partialFingerprints`		Um dicionário que mapeia tipos de impressão digital nomeados para sua respectiva impressão digital. Isso conterá, no mínimo, um valor para o `primaryLocationLineHash`, que fornece uma marca digital com base no contexto da localização primária.
`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?	Anotações
`physicalLocation`		None
`id`		Os objetos `location` que aparecem na matriz `relatedLocations` de um objeto `result`podem 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?	Anotações
`artifactLocation`		None
`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 offset e comprimento de caracteres

Qualquer região produzida pelo CodeQL pode ser especificada em qualquer um dos formatos, e os consumidores devem ser capazes de lidar com ambos os tipos.

Para regiões de deslocamento de linha/coluna, as seguintes propriedades serão definidas:

Nome da propriedade JSON	Constantemente gerado?	Anotações
`startLine`		None
`startColumn`		Não incluído se for igual ao valor padrão 1.
`endLine`		Não incluído se idêntico a `startLine`.
`endColumn`		None
`snippet`		None

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

Nome da propriedade JSON	Sempre gerado?	Anotaçõ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`		None

Objeto `codeFlow`

Nome da propriedade JSON	Sempre gerado?	Anotações
`threadFlows`		None

Objeto `threadFlow`

Nome da propriedade JSON	Está sempre gerado?	Anotações
`locations`		None

Objeto `threadFlowLocation`

Nome da propriedade JSON	É sempre gerado?	Anotações
`location`		None

Quem pode usar esse recurso?

Neste artigo