Personalizar o fluxo de trabalho de varredura de código com CodeQL – parte 1

Concluído

Os fluxos de trabalho de varredura de código que usam CodeQL têm várias opções de configuração que podem ser ajustadas para atender melhor às necessidades da sua organização.

Quando você usa o CodeQL para verificar o código, o mecanismo de análise do CodeQL gera um banco de dados do código e executa consultas nele. A análise de CodeQL usa um conjunto padrão de consultas, mas você pode especificar mais consultas a serem executadas além das consultas padrão.

Você pode executar consultas extras se elas fizerem parte de um pacote CodeQL (beta) publicado no Registro de Contêiner do GitHub ou um pacote QL armazenado em um repositório.

Há duas opções para especificar quais consultas você deseja executar com a verificação de código CodeQL:

• Usar o fluxo de trabalho de verificação de código
• Usando um arquivo de configuração personalizado

Nesta unidade, você aprenderá a editar um arquivo de fluxo de trabalho para fazer referência a consultas adicionais, como usar consultas de pacotes de consulta e como combinar consultas de um arquivo de fluxo de trabalho e um arquivo de configuração personalizado.

Especificar consultas adicionais em um arquivo de fluxo de trabalho

As opções disponíveis para especificar as consultas adicionais que você deseja executar são:

• packs para instalar um ou mais pacotes de consultas do CodeQL (beta) e executar o conjunto padrão de consultas ou consultas específicas para esses pacotes.
• queries para especificar um só arquivo .ql, um diretório que contém vários arquivos .ql, um arquivo de definição de conjunto de consultas .qls ou qualquer combinação.

Você pode usar os pacotes e as consultas no mesmo fluxo de trabalho.

Não recomendamos fazer referência a conjuntos de consultas diretamente do repositório github/codeql, como github/codeql/cpp/ql/src@main. Essas consultas podem não ser compiladas com a mesma versão do CodeQL usada para suas outras consultas, o que pode levar a erros durante a análise.

Usar pacotes de consulta do CodeQL

Observação

A funcionalidade de gerenciamento de pacotes CodeQL, incluindo os pacotes do CodeQL, está atualmente em beta e está sujeita a alterações.

Para adicionar um ou mais pacotes de consulta do CodeQL (beta), adicione uma entrada with: packs: dentro da seção uses: github/codeql-action/init@v1 do fluxo de trabalho. Nos pacotes, você pode especificar um ou mais pacotes para usar e, opcionalmente, qual versão baixar. Quando você não especificar uma versão, a versão mais recente será baixada. Se você quiser usar pacotes que não estão publicamente disponíveis, precisará definir a variável de ambiente GITHUB_TOKEN como um segredo que tenha acesso aos pacotes.

No exemplo a seguir, o escopo é a organização ou a conta pessoal que publicou o pacote. Quando o fluxo de trabalho é executado, os três pacotes de consulta CodeQL são baixados do GitHub e as consultas padrão ou o conjunto de consultas de cada pacote são executados. No exemplo a seguir, cada um dos pacotes na lista será baixado com base em suas especificações:

• A versão mais recente de pack1 é baixada, e todas as consultas padrão são executadas.
• A versão 1.2.3 do pack2 é baixada e todas as consultas padrão são executadas.
• A versão mais recente de pack3, compatível com a versão 3.2.1, é baixada e todas as consultas são executadas.
• A versão 4.5.6 de pack4 é baixada e apenas as consultas encontradas em path/to/queries são executadas.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Observação

Para fluxos de trabalho que geram bancos de dados CodeQL para várias linguagens, você deve especificar os pacotes de consulta CodeQL em um arquivo de configuração.

Usar consultas em pacotes QL

Para adicionar uma ou mais consultas, adicione uma entrada with: queries: dentro da seção uses: github/codeql-action/init@v3 do fluxo de trabalho. Se as consultas estiverem em um repositório privado, use o parâmetro external-repository-token para especificar um token que tenha acesso para fazer check-out do repositório privado.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Você também pode especificar conjuntos de consulta no valor de queries. Os conjuntos de consulta são coleções de consultas, geralmente agrupadas por finalidade ou linguagem.

Os seguintes pacotes de consultas são incorporados à verificação de código CodeQL e estão disponíveis para uso.

Conjunto de consultas	Descrição
security-extended	Consultas do pacote padrão, além de consultas com menor gravidade e precisão
security-and-quality	Consultas de security-extended, além de consultas de manutenção e confiabilidade

Cada um desses pacotes de consultas contém um subconjunto diferente das consultas incluídas no pacote de consultas interno do CodeQL para essa linguagem. Os pacotes de consultas são gerados automaticamente por meio dos metadados de cada consulta.

Quando você especifica um conjunto de consultas, o mecanismo de análise do CodeQL executa as consultas contidas no conjunto para você, além do conjunto padrão de consultas.

Combinar consultas de um arquivo de fluxo de trabalho e de um arquivo de configuração personalizado

Se você também usar um arquivo de configuração para configurações personalizadas, todos os pacotes ou consultas adicionais especificados no fluxo de trabalho serão usados em vez daqueles especificados no arquivo de configuração. Caso deseje executar o conjunto combinado de pacotes ou consultas adicionais, coloque o valor de packs ou queries como prefixo do fluxo de trabalho com o símbolo +.

No seguinte exemplo, o símbolo + garante que os pacotes e as consultas adicionais especificados sejam usados junto com qualquer item especificado no arquivo de configuração referenciado:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries