Como personalizar a análise com pacotes CodeQL

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 dois tipos de pacotes do CodeQL: pacotes de consultas e pacotes de bibliotecas.

• 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 um cache de compilação. 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 e não há nenhum cache de compilação incluído quando o pacote é publicado.

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

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. Para obter mais informações sobre pacotes de consulta, confira "Sobre a varredura de código com 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.

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:

1. Baixar a versão mais recente do pacote octo-org/security-queries.
2. 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.
3. Execute todas as consultas padrão em octo-org/security-queries.
4. 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 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.