Como personalizar a análise com pacotes CodeQL

Observação: a funcionalidade de gerenciamento de pacote do CodeQL, incluindo pacotes do CodeQL, está em versão beta no momento e sujeita a alterações. Durante a versão beta, os pacotes CodeQL estão disponíveis apenas usando pacotes GitHub – o Container registry. Para usar essa funcionalidade beta, instale a versão mais recente do pacote da CodeQL CLI de: https://github.com/github/codeql-action/releases.

Sobre os pacotes do CodeQL

Os pacotes do CodeQL são usados para criar, compartilhar, gerar dependência e executar consultas e bibliotecas do CodeQL. Os pacotes do CodeQL contêm consultas, arquivos de biblioteca, conjuntos de consultas e metadados. Você pode personalizar suas análises do CodeQL baixando pacotes criados por outras pessoas e executando-os em sua base de código.

Existem três tipos de pacotes do CodeQL: pacotes de consultas, pacotes de bibliotecas e pacotes de modelos.

Os pacotes de consulta contêm um conjunto de consultas pré-compiladas que podem ser avaliadas em um banco de dados do CodeQL. Os pacotes de consultas foram projetados para serem executados. Quando um pacote de consultas é publicado, ele inclui todas as dependências transitivas e representações pré-compiladas de cada consulta, além das fontes de consulta. Isso garante a execução consistente e eficiente das consultas no pacote.
Os pacotes de biblioteca são projetados para serem usados por pacotes de consultas (ou outros pacotes de biblioteca) e não contêm consultas. As bibliotecas não são compiladas separadamente.
Pacotes de modelos podem ser usados para expandir análises do code scanning para reconhecer bibliotecas e estruturas para as quais não há suporte por padrão. Pacotes de modelos estão atualmente em versão beta e sujeitos a alterações. Durante o beta, os pacotes de modelo estão disponíveis para análise Java/Kotlin e C# no nível do repositório. Para obter mais informações sobre como criar seus próprios pacotes de modelo, confira "Como criar e trabalhar com pacotes do CodeQL".

Os pacotes padrão do CodeQL para todas as linguagens com suporte estão publicados no Container registry. Se você instalou a CodeQL CLI da maneira padrão, usando o pacote da CodeQL CLI, os pacotes de consulta principais já foram baixados e já estão disponíveis. São elas:

codeql/cpp-queries
codeql/csharp-queries
codeql/go-queries
codeql/java-queries
codeql/javascript-queries
codeql/python-queries
codeql/ruby-queries
codeql/swift-queries

Você também pode usar a CodeQL CLI para criar seus próprios pacotes do CodeQL, adicionar dependências a pacotes e instalar ou atualizar dependências. Para obter mais informações, confira "Como criar e trabalhar com pacotes do CodeQL".

Você pode publicar os pacotes do CodeQL que criou, usando a CodeQL CLI. Para obter mais informações sobre a publicação e o download de pacotes do CodeQL, consulte "Publicar e usar pacotes do CodeQL".

Fazendo o download e usando pacotes de consulta de CodeQL

O pacote de CodeQL CLI inclui consultas mantidas por especialistas de GitHub, pesquisadores de segurança e contribuidores da comunidade. Se você quiser executar consultas desenvolvidas por outras organizações, os pacotes de consulta do CodeQL fornecem uma maneira eficiente e confiável de baixar e executar consultas, enquanto os pacotes de modelo (beta) podem ser usados para expandir análises do code scanning para reconhecer bibliotecas e estruturas que não têm suporte por padrão. Para obter mais informações sobre pacotes de consulta, confira "Sobre a varredura de código com CodeQL". Para informações sobre como escrever seus próprios pacotes de modelos, consulte "Como criar e trabalhar com pacotes do CodeQL".

Antes de usar um pacote de consultas do CodeQL para analisar um banco de dados, você deve baixar os pacotes necessários do GitHub Container registry. Isso pode ser feito usando o sinalizador --download como parte do comando codeql database analyze ou executando codeql pack download. Se um pacote não estiver disponível publicamente, você precisará usar um GitHub App ou um personal access token para fazer a autenticação. Para obter mais informações e um exemplo, confira "Como carregar os resultados da análise do CodeQL no GitHub".

Opção	Obrigatório	Uso
`<scope/name@version:path>`		Especifique o escopo e o nome de um ou mais pacotes de consulta CodeQL para fazer o download usando uma lista separada por vírgulas. Opcionalmente, inclua a versão para fazer o download e descompactar. Por padrão, a versão mais recente deste pacote foi baixada. Opcionalmente, inclua um caminho para um conjunto de consultas, diretórios ou consultas a serem executadas. Se nenhum caminho for incluído, execute as consultas padrão deste pacote.
`--github-auth-stdin`		Passe a CLI pelo GitHub App ou o personal access token já criado para autenticação com a API REST de GitHub do repositório de segredo por meio da entrada padrão. Isso não será necessário se o comando tiver acesso a uma variável de ambiente `GITHUB_TOKEN` definida com esse token.

Observação: se você especificar uma versão específica de um pacote de consultas a ser usada, lembre-se de que a versão especificada pode acabar ficando muito antiga em relação à versão mais recente do CodeQL para garantir um uso eficiente. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, reavalie quais versões fixar sempre que atualizar a CodeQL CLI que você está usando.

Para obter mais informações sobre a compatibilidade de pacotes, confira "Publicar e usar pacotes do CodeQL".

Exemplo básico do download e uso de pacotes de consulta

Este exemplo executa o comando codeql database analyze com a opção --download para:

Baixar a versão mais recente do pacote octo-org/security-queries.
Baixar uma versão do pacote octo-org/optional-security-queries que seja compativel com a versão 1.0.1 (nesse caso, é a versão 1.0.2). Para obter mais informações sobre compatibilidade semver, confira a documentação do intervalo de versão semântica do npm.
Execute todas as consultas padrão em octo-org/security-queries.
Executar somente a consulta queries/csrf.ql de octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Download direto de pacotes CodeQL

Se você quiser baixar um pacote CodeQL sem executá-lo imediatamente, poderá usar o comando codeql pack download. Isso será útil se você quiser evitar acessar a Internet ao executar consultas CodeQL. Ao executar a análise CodeQL, você pode especificar pacotes, versões e caminhos da mesma forma que no exemplo anterior:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Baixar pacotes do CodeQL de vários registros de contêiner do GitHub

Se os pacotes do CodeQL residirem em vários registros de contêiner, você precisará instruir a CodeQL CLI onde localizar cada pacote. Para obter mais informações, confira "Como personalizar sua configuração avançada para a verificação de código".

Como especificar quais consultas devem ser executadas em um pacote do CodeQL

Os especificadores de consulta são usados por codeql database analyze e outros comandos que operam em um conjunto de consultas. A forma completa de um especificador de consulta é scope/name@range:path, em que:

scope/name é o nome qualificado de um pacote do CodeQL.
range é um intervalo semver.
path é um caminho do sistema de arquivos para uma só consulta, um diretório que contém consultas ou um arquivo de conjunto de consultas.

Quando você especifica scope/name, range e path são opcionais. Se você omitir um range, a versão mais recente do pacote especificado será usada. Se você omitir um path, o conjunto de consultas padrão do pacote especificado será usado.

O pode path ser um dos seguintes: um arquivo de consulta .ql, um diretório que contém uma ou mais consultas ou um arquivo de conjunto de consultas .qls. Se você omitir um nome de pacote, precisará fornecer um path, que será interpretado em relação ao diretório de trabalho do processo atual. Não há suporte para padrões glob.

Se você especificar scope/name e path, o path não poderá ser absoluto. Ele é considerado relativo à raiz do pacote do CodeQL.

Especificadores de consulta de exemplo

codeql/python-queries – Todas as consultas no pacote de consultas padrão da versão mais recente do pacote codeql/python-queries.
codeql/python-queries@1.2.3 – Todas as consultas no pacote de consultas padrão da versão 1.2.3 do pacote codeql/python-queries.
codeql/python-queries@~1.2.3 – Todas as consultas no conjunto de consultas padrão da versão mais recente do pacote codeql/python-queries que são >= 1.2.3 e < 1.3.0.
codeql/python-queries:Functions – Todas as consultas no diretório Functions na versão mais recente do pacote codeql/python-queries.
codeql/python-queries@1.2.3:Functions – Todas as consultas no diretório Functions da versão 1.2.3 do pacote codeql/python-queries.
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls – Todas as consultas no diretório codeql-suites/python-code-scanning.qls da versão 1.2.3 do pacote codeql/python-queries.
suites/my-suite.qls – Todas as consultas no arquivo suites/my-suite.qls relativas ao diretório de trabalho atual.

Dica

O conjunto de consultas padrão dos pacotes de consultas padrão do CodeQL são codeql-suites/<lang>-code-scanning.qls. Vários outros pacotes de consultas úteis também podem ser encontrados no diretório codeql-suitesde cada pacote. Por exemplo, o pacote codeql/cpp-queries contém os seguintes conjuntos de consultas:

cpp-code-scanning.qls – Consultas de verificação de código padrão para C++. O conjunto de consultas padrão desse pacote.
cpp-security-extended.qls – Consultas do conjunto padrão cpp-code-scanning.qls para C++, além de consultas de gravidade e precisão inferiores.
cpp-security-and-quality.qls – Consultas de cpp-security-extended.qls, além de consultas de capacidade de manutenção e confiabilidade.

Você pode ver as fontes desses conjuntos de consultas no repositório do CodeQL. Os pacotes de consultas para outras linguagens são semelhantes.

Usando pacotes de modelo para analisar chamadas a dependências personalizadas

Você pode incluir pacotes de modelos publicados em uma análise do code scanning com a opção --model-packs. Por exemplo:

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --model-packs my-repo/my-java-model-pack \
  --output=/temp/my-company.sarif codeql/java-queries

Neste exemplo, as consultas relevantes no pacote de consultas padrão codeql/java-queries usarão as informações de dependência do pacote de modelos, my-repo/my-java-model-pack, para verificar vulnerabilidades no código que chama essas dependências.

Você pode especificar vários pacotes de modelos publicados em uma análise.

Para obter mais informações sobre como gravar seus próprios pacotes de modelos, consulte "Como criar e trabalhar com pacotes do CodeQL".

Sobre pacotes publicados

Quando um pacote é publicado para uso em análises, o comando codeql pack create ou codeql pack publish verifica se o conteúdo está completo e também adiciona mais conteúdo a ele:

Para pacotes de consulta, uma cópia de cada um dos pacotes de biblioteca dos quais eles dependem, nas versões precisas com as quais eles foram desenvolvidos. Os usuários do pacote de consultas não precisarão baixar esses pacotes de biblioteca separadamente.
Para pacotes de consulta, representações pré-compiladas de cada uma das consultas. É mais rápido executá-las do que compilar a origem do QL para a consulta em cada análise.

A maioria desses dados está localizada em um diretório chamado .codeql no pacote publicado, mas as consultas pré-compiladas estão em arquivos com um sufixo .qlx ao lado da origem .ql de cada consulta. Ao analisar um banco de dados com uma consulta de um pacote publicado, o CodeQL carregará esses arquivos em vez da origem do .ql. Se você precisar modificar o conteúdo de um pacote publicado, remova todos os arquivos .qlx, pois eles podem impedir que as modificações nos arquivos .ql entrem em vigor.