Skip to main content

Saída SARIF da CLI do CodeQL

Você pode gerar o SARIF usando a CodeQL CLI e compartilhar resultados de análise estática com outros sistemas.

Quem pode usar esse recurso?

O CodeQL do GitHub é licenciado por usuário após a instalação. Você pode usar o CodeQL somente para determinadas tarefas sob as restrições de licença. Para obter mais informações, confira "Sobre a CLI do CodeQL".

Se você tiver uma licença do GitHub Advanced Security, poderá usar o CodeQL para análise automatizada, integração contínua e entrega contínua. Para obter mais informações, confira "Sobre a Segurança Avançada do GitHub".

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 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 CodeQLTipo de formatoAlterações
2.0.0sarifv2.1.0Primeira 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 JSONSempre gerado?Observações
$schemaFornece um link para o esquema SARIF.
versionA versão do SARIF usada para gerar a saída.
runsUma matriz que contém um só objeto de execução, para uma linguagem.

Objeto run

Nome da propriedade JSONSempre gerado?Observações
toolNenhum
artifactsUma matriz que contém pelo menos um objeto de artefato para cada arquivo referenciado em um resultado.
resultsNenhum
newLineSequencesNenhum
columnKindNenhum
propertiesO dicionário de propriedades conterá o semmle.formatSpecifier, que identifica o especificador de formato passado à CodeQL CLI.

Objeto tool

Nome da propriedade JSONSempre gerado?Observações
driverNenhum

Objeto toolComponent

Nome da propriedade JSONSempre gerado?Observações
nameDefina 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.
organizationDefina isso como "GitHub".
versionDefina isso como a versão de lançamento do CodeQL, por exemplo, "2.0.0".
rulesA 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 JSONSempre gerado?Observações
idConterá 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.
nameConterá a propriedade @id especificada na consulta. Confira a propriedade id acima para obter um exemplo.
shortDescriptionConterá a propriedade @name especificada na consulta que define a regra.
fullDescriptionConterá a propriedade @description especificada na consulta que define a regra.
defaultConfigurationUm 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 JSONSempre gerado?Observações
locationUm objeto artifactLocation.
indexO índice do objeto artifact.
contentsSe 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 JSONSempre gerado?Observações
uriNenhum
indexNenhum
uriBaseIdSe 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 JSONSempre gerado?Observações
ruleIdConfira a descrição da propriedade id no objeto reportingDescriptor (da regra).
ruleIndexNenhum
messageUma 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.
locationsUma matriz que contém um só objeto location.
partialFingerprintsUm 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.
codeFlowsEssa matriz poderá ser preenchida com um ou mais objetos codeFlow se a consulta que define a regra desse resultado for @kind path-problem.
relatedLocationsEssa 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.
suppressionsSe 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 JSONSempre gerado?Observações
physicalLocationNenhum
idOs objetos location que aparecem na matriz relatedLocations de um objeto resultpodem conter a propriedade id.
messageOs 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 JSONSempre gerado?Observações
artifactLocationNenhum
regionSe o physicalLocation determinado existir em um arquivo de texto, como um arquivo de código-fonte, a propriedade region poderá estar presente.
contextRegionPoderá 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 JSONSempre gerado?Observações
startLineNenhum
startColumnNão incluído se for igual ao valor padrão 1.
endLineNão incluído se idêntico a startLine.
endColumnNenhum
snippetNenhum

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

Nome da propriedade JSONSempre gerado?Observações
charOffsetFornecido se startLine, startColumn, endLine e endColumn não forem preenchidos.
charLengthFornecido se startLine, startColumn, endLine e endColumn não forem preenchidos.
snippetNenhum

Objeto codeFlow

Nome da propriedade JSONSempre gerado?Observações
threadFlowsNenhum

Objeto threadFlow

Nome da propriedade JSONSempre gerado?Observações
locationsNenhum

Objeto threadFlowLocation

Nome da propriedade JSONSempre gerado?Observações
locationNenhum