Como personalizar a análise com pacotes CodeQL

Você pode personalizar sua CodeQL análise baixando pacotes criados por outras pessoas e executando-os em sua base de código. Para obter mais informações, consulte Pacotes de consulta CodeQL.

Baixar e usar CodeQL pacotes de consulta

Antes de usar um CodeQL pacote de consultas para analisar um banco de dados, você deve baixar todos os pacotes necessários.GitHubContainer 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 ao público, você precisará usar um GitHub App ou personal access token para autenticar. Para obter mais informações e um exemplo, confira Carregando resultados da análise do CodeQL para GitHub.

Opção	Obrigatório	Uso
`<scope/name@version:path>`		Especifique o escopo e o nome de um ou mais CodeQL pacotes de consulta a serem baixados 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, a GitHub App ou a personal access token criada para autenticação com a API REST de GitHub a partir do seu armazenamento de segredos, por meio de 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 para usar, lembre-se de que a versão que você especificar pode, com o tempo, ficar antiga demais para que a versão mais recente de CodeQL consiga usá-la com eficiência. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, deverá reavaliar quais versões fixar sempre que atualizar o CodeQL CLI que está usando.

Para obter mais informações sobre a compatibilidade de pacotes, confira Referência de pacotes de consulta 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 compatível 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 CodeQL pacotes

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

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

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

Se os pacotes CodeQL estiverem em vários registros de contêineres, você deverá instruir o CodeQL CLI sobre onde encontrar cada pacote. Para obter mais informações, consulte Opções de configuração de fluxo de trabalho para verificação de código.

Especificando quais consultas serão executadas em um CodeQL pacote

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 CodeQL pacote.
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 path pode ser: 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 CodeQL Pacote.

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 consulta padrão CodeQL é 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 CodeQL repositório. 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 code scanning análise 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, CodeQL carregará esses arquivos em vez da origem .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.