Observação: o administrador do site precisa habilitar code scanning antes que você possa usar esse recurso. Se você desejar usar o GitHub Actions para fazer a varredura do seu código, o administrador do site também deverá habilitar o GitHub Actions e configurar a infraestrutura necessária. Para obter mais informações, confira "Como configurar a verificação de código do seu dispositivo".
Observação: este artigo descreve os recursos disponíveis na versão da ação do CodeQL e o pacote da CodeQL CLI associado incluído na versão inicial desta versão do GitHub Enterprise Server. Se sua empresa usa uma versão mais recente da ação CodeQL, confira a versão GitHub Enterprise Cloud deste artigo para obter informações sobre os recursos mais recentes. Para obter informações sobre como usar a versão mais recente, consulte "Como configurar a verificação de código do seu dispositivo".
Sobre a configuração do code scanning
Você pode executar code scanning em GitHub Enterprise Server, usando GitHub Actions ou a partir do seu sistema de integração contínua (CI). Para obter mais informações, confira "Escrevendo fluxos de trabalho" ou "Usando a varredura de código com seu sistema de CI existente".
Com a configuração avançada para a code scanning, você pode personalizar um fluxo de trabalho da code scanning para um controle granular sobre a sua configuração. Para obter mais informações, confira "Como definir a configuração avançada para verificação de código".
A análise de CodeQL é apenas um tipo de code scanning que você pode fazer em GitHub. GitHub Marketplace em GitHub.com contém outros fluxos de trabalho de code scanning que você pode usar. Os exemplos específicos fornecidos neste artigo estão relacionados ao arquivo sobre o Fluxo de trabalho de análise do CodeQL.
Edição de um fluxo de trabalho de code scanning
O GitHub salva os arquivos de fluxo de trabalho no diretório .github/workflows do seu repositório. Você pode encontrar um fluxo de trabalho que adicionou ao pesquisar seu nome de arquivo. Por exemplo, por padrão, o arquivo de fluxo de trabalho da code scanning do CodeQL é chamado codeql-analysis.yml.
- No seu repositório, pesquise o arquivo do fluxo de trabalho que você deseja editar.
- No canto superior direito da exibição de arquivo, para abrir o editor de fluxo de trabalho, clique em .
- Depois de editar o arquivo, clique em Iniciar confirmação e preencha o formulário "Confirmar alterações". Você pode optar por confirmar diretamente a ramificação atual ou criar uma nova ramificação e iniciar uma solicitação de pull.
Para obter mais informações sobre como editar arquivos de fluxo de trabalho, confira "Escrevendo fluxos de trabalho".
Configurar a frequência
Configure o Fluxo de trabalho de análise do CodeQL para examinar o código conforme um agendamento ou quando eventos específicos ocorrerem em um repositório.
A varredura do código a cada push para o repositório, e toda vez que um pull request é criado, isso impede que os desenvolvedores introduzam novas vulnerabilidades e erros no código. A varredura do código de forma pré-programada informa as últimas vulnerabilidades e erros de GitHub, que os pesquisadores de segurança e da comunidade, mesmo quando desenvolvedores não estão mantendo o repositório de forma ativa.
Fazer a varredura no push
Por padrão, o Fluxo de trabalho de análise do CodeQL usa o evento on:push
para disparar uma verificação de código em cada push para o branch padrão do repositório e todos os branches protegidos. Para code scanning ser acionado em um branch especificado, o fluxo de trabalho deverá existir nesse branch. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
Se você fizer a verificação durante o push, os resultados serão exibidos na guia Segurança do repositório. Para obter mais informações, confira "Avaliar alertas de verificação de código para seu repositório".
Além disso, quando uma verificação de on:push
retorna resultados que podem ser mapeados para uma solicitação de pull aberta, esses alertas aparecem automaticamente na solicitação de pull no mesmo local que os outros alertas da solicitação de pull. Os alertas são identificados por meio da comparação da análise existente do início da ramificação com a análise da ramificação de destino. Para obter mais informações sobre alertas do code scanning nas solicitações de pull, confira "Alertas de varredura de código de triagem em pull requests".
Fazer a varredura de pull requests
O Fluxo de trabalho de análise do CodeQL padrão usa o evento pull_request
para disparar uma verificação de código nas solicitações de pull direcionadas ao branch padrão. O evento pull_request
não é disparado se a solicitação de pull foi aberta por meio de um fork privado.
Para obter mais informações sobre o evento pull_request
, confira "Eventos que disparam fluxos de trabalho".
Se você examinar as solicitações de pull, os resultados serão exibidos como alertas em uma verificação de solicitação de pull. Para obter mais informações, confira "Alertas de varredura de código de triagem em pull requests".
Se você usar o gatilho pull_request
, configurado para verificar o commit de mesclagem da solicitação de pull em vez do commit de cabeçalho, ele produzirá resultados mais eficientes e precisos do que a verificação do cabeçalho do branch em cada push. No entanto, se você usar um sistema de CI/CD que não possa ser configurado para disparo em solicitações de pull, ainda poderá usar o gatilho on:push
e a code scanning mapeará os resultados para as solicitações de pull em aberto no branch e adicionará os alertas como anotações na solicitação de pull. Para obter mais informações, confira "Verificação durante o push".
Evitar varreduras desnecessárias de pull requests
Talvez você queira evitar que uma varredura de código seja disparada em solicitações de pull específicas direcionadas à ramificação padrão, independentemente dos arquivos que foram alterados. Configure isso especificando on:pull_request:paths-ignore
ou on:pull_request:paths
no fluxo de trabalho da code scanning. Por exemplo, se as únicas alterações em uma solicitação de pull forem para arquivos com as extensões de arquivo .md
ou .txt
, você poderá usar a matriz paths-ignore
a seguir.
on: push: branches: [main, protected] pull_request: branches: [main] paths-ignore: - '**/*.md' - '**/*.txt'
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
paths-ignore:
- '**/*.md'
- '**/*.txt'
Observação: on:pull_request:paths-ignore
e on:pull_request:paths
definem as condições que determinam se as ações no fluxo de trabalho serão executadas em uma pull request. Eles não determinam quais arquivos serão analisados quando as ações forem executadas. Quando uma solicitação de pull contém arquivos sem correspondência com on:pull_request:paths-ignore
ou on:pull_request:paths
, o fluxo de trabalho executa as ações e verifica todos os arquivos alterados na solicitação de pull, incluindo aqueles correspondentes a on:pull_request:paths-ignore
ou on:pull_request:paths
, a menos que eles tenham sido excluídos. Para obter informações sobre como excluir arquivos da análise, confira "Como especificar os diretórios para verificação".
Para obter mais informações sobre como usar on:pull_request:paths-ignore
e on:pull_request:paths
a fim de determinar quando um fluxo de trabalho será executado para uma solicitação de pull, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
Fazer a varredura de forma pré-programada
Se você usar o Fluxo de trabalho de análise do CodeQL padrão, o fluxo de trabalho examinará o código no repositório uma vez por semana, além das verificações disparadas pelos eventos. Para ajustar essa agenda, edite o valor cron
no fluxo de trabalho. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions".
Observação: o GitHub só executa os trabalhos agendados que estão em fluxos de trabalho no branch padrão. Alterar a programação de um fluxo de trabalho em qualquer outro branch não terá efeito até que você mescle o branch com o branch-padrão.
Exemplo
O exemplo a seguir mostra um Fluxo de trabalho de análise do CodeQL para um repositório em particular que tem um branch padrão chamado main
e um branch protegido chamado protected
.
on: push: branches: [main, protected] pull_request: branches: [main] schedule: - cron: '20 14 * * 1'
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
schedule:
- cron: '20 14 * * 1'
Este fluxo de trabalho varre:
- Cada push para a ramificação padrão e a ramificação protegida
- Cada solicitação de pull para a ramificação padrão
- A ramificação padrão a cada segunda-feira às 14h20 UTC
Especificar um sistema operacional
Observações:
-
A verificação do código Swift usa executores do macOS por padrão. Executores macOS hospedados pelo
-
O Code scanning do código Swift não é compatível com executores que fazem parte de um Actions Runner Controller (ARC), porque os executores ARC usam apenas o Linux e o Swift requer executores macOS. No entanto, você pode ter uma mistura de executores ARC e executores macOS auto-hospedados. Para obter mais informações, confira "Sobe o Controlador de Executores de Ação".
Se o código exigir um sistema operacional específico para ser compilado, configure o sistema operacional no seu Fluxo de trabalho de análise do CodeQL. Edite o valor de jobs.analyze.runs-on
para especificar o sistema operacional do computador que executa as ações da code scanning. Você especifica o sistema operacional usando um rótulo apropriado como o segundo elemento em uma matriz de dois elementos, após self-hosted
.
jobs: analyze: name: Analyze runs-on: [self-hosted, ubuntu-latest]
jobs:
analyze:
name: Analyze
runs-on: [self-hosted, ubuntu-latest]
CodeQL code scanning é compatível com as versões mais recentes do Ubunto, Windows e macOS. Os valores típicos dessa configuração são: ubuntu-latest
, windows-latest
e macos-latest
. Para obter mais informações, confira "Escolhendo o executor para um trabalho" e "Usar rótulos com os executores auto-hospedados."
Você deve garantir que o Git esteja na variável PATH em seus executores auto-hospedados. Para obter mais informações, confira "Sobre executores auto-hospedados" e "Adicionar executores auto-hospedados".
Para especificações recomendadas (RAM, núcleos de CPU e disco) para executar análises do CodeQL, confira "Recursos de hardware recomendados para executar o CodeQL".
Especificar o local para bancos de dados de CodeQL
Em geral, você não precisa se preocupar com o lugar em que o Fluxo de trabalho de análise do CodeQL coloca os bancos de dados do CodeQL, pois as etapas posteriores encontrarão automaticamente os bancos de dados criados nas etapas anteriores. No entanto, se estiver escrevendo uma etapa de fluxo de trabalho personalizado que exija que o banco de dados CodeQL esteja em um local específico do disco, por exemplo, para carregar o banco de dados como um artefato de fluxo de trabalho, especifique esse local usando o parâmetro db-location
na ação init
.
- uses: github/codeql-action/init@v3 with: db-location: '${{ github.runner_temp }}/my_location'
- uses: github/codeql-action/init@v3
with:
db-location: '${{ github.runner_temp }}/my_location'
O Fluxo de trabalho de análise do CodeQL vai esperar que o caminho fornecido em db-location
seja gravável, não exista ou seja um diretório vazio. Ao usar este parâmetro em um trabalho em execução em um executor auto-hospedado ou usando um contêiner Docker, é responsabilidade do usuário garantir que o diretório escolhido seja limpo entre execuções, ou que os bancos de dados sejam removidos depois de deixarem de ser necessários. Isto não é necessário para trabalhos em execução em executores auto-hospedados GitHub, que obtêm uma instância nova e um sistema de arquivos limpo toda vez que forem executados. Para obter mais informações, confira "Usar executores hospedados no GitHub".
Se esse parâmetro não for usado, o Fluxo de trabalho de análise do CodeQL criará os bancos de dados em uma localização temporária escolhida por ele. Atualmente, o valor padrão é ${{ github.runner_temp }}/codeql_databases
.
Alterar as linguagens que são analisadas
O CodeQL code scanning detecta automaticamente código escrito nas linguagens compatíveis.
- C/C++
- C#
- Ir
- Java/Kotlin
- JavaScript/TypeScript
- Python
- Ruby
- Swift
Observações:
- Use
java-kotlin
para analisar o código escrito em Java, Kotlin ou ambos. - Use
javascript-typescript
para analisar código escrito em Java, TypeScript ou ambos.
Para obter mais informações, confira a documentação no site do CodeQL: "Linguagens e estruturas compatíveis".
O CodeQL usa os seguintes identificadores de idioma:
Idioma | Identificador | Identificadores alternativos opcionais (se houver) |
---|---|---|
C/C++ | c-cpp | c ou cpp |
C# | csharp | |
Ir | go | |
Java/Kotlin | java-kotlin | java ou kotlin |
JavaScript/TypeScript | javascript-typescript | javascript ou typescript |
Python | python | |
Ruby | ruby | |
Swift | swift |
Nota: especificar um dos identificadores alternativos equivale a usar o identificador de idioma padrão. Por exemplo, especificar javascript
em vez de javascript-typescript
não excluirá a análise do código TypeScript. Você pode fazer isso em um fluxo de trabalho de configuração avançada com a opção --paths-ignore
. Para obter mais informações, confira "Personalizando a configuração avançada para varredura de código".
O arquivo do Fluxo de trabalho de análise do CodeQL padrão contém uma matriz chamada language
que lista as linguagens no repositório que são analisadas. O CodeQL preenche automaticamente esta matriz quando você adiciona o code scanning a um repositório. O uso da matriz language
otimiza o CodeQL a executar cada análise em paralelo. Recomendamos que todos os fluxos de trabalho adotem essa configuração devido aos benefícios de desempenho da paralelização de compilações. Para obter mais informações sobre matrizes, confira "Executando variações de trabalhos em um fluxo de trabalho".
Se o repositório contiver código em mais de uma das linguagens com suporte, você poderá escolher quais linguagens deseja analisar. Há vários motivos pelos quais você talvez queira impedir que uma linguagem seja analisada. Por exemplo, o projeto pode ter dependências em uma linguagem diferente do corpo principal do seu código e você pode preferir não ver alertas para essas dependências.
Se o seu fluxo de trabalho usar a matriz language
, o CodeQL será embutido em código para analisar apenas as linguagens da matriz. Para alterar as linguagens que você deseja analisar, edite o valor da variável de matriz. Você pode remover uma linguagem para evitar que ele seja analisado ou adicionar uma linguagem que não estava presente no repositório quando a code scanning foi configurada. Por exemplo, se o repositório inicialmente só continha o JavaScript quando a code scanning foi configurada e, posteriormente, você adicionou o código Python, você precisa adicionar o python
à matriz.
jobs: analyze: name: Analyze ... strategy: fail-fast: false matrix: language: ['javascript-typescript', 'python']
jobs:
analyze:
name: Analyze
...
strategy:
fail-fast: false
matrix:
language: ['javascript-typescript', 'python']
Se o fluxo de trabalho não contiver uma matriz chamada language
, o CodeQL será configurado para executar a análise sequencialmente. Se você não especificar as linguagens no fluxo de trabalho, o CodeQL irá detectar automaticamente e tentará analisar quaisquer linguagens compatíveis no repositório. Caso deseje escolher as linguagens que serão analisadas sem usar uma matriz, use o parâmetro languages
na ação init
.
- uses: github/codeql-action/init@v3 with: languages: c-cpp, csharp, python
- uses: github/codeql-action/init@v3
with:
languages: c-cpp, csharp, python
Definindo as severidades de alerta que causam uma falha de verificação para uma solicitação de pull
Quando você habilitar o code scanning em pull requests, a verificação falhará somente se um ou mais alertas de gravidade error
ou gravidade de segurança critical
ou high
forem detectados. A verificação será bem-sucedida se forem detectados alertas com gravidades ou gravidades de segurança mais baixas. Para bases de código importantes, convém que a verificação do code scanning falhe se algum alerta for detectado, de modo que o alerta deve ser corrigido ou descartado antes que a alteração de código seja mesclada. Para obter mais informações sobre níveis de gravidade, consulte "Sobre a gravidade de alertas e níveis de gravidade de segurança".
Você pode editar quais níveis de alertas de gravidade e gravidade de segurança causam uma falha de verificação. Para obter mais informações, confira "Editar as definições da configuração padrão".
Configurar uma categoria para a análise
Use category
para distinguir entre várias análises da mesma ferramenta e do mesmo commit, mas executadas em diferentes linguagens ou em diferentes partes do código. A categoria especificada no seu fluxo de trabalho será incluída no arquivo de resultados SARIF.
Esse parâmetro é particularmente útil se você trabalhar com monorepos e tiver vários arquivos SARIF para diferentes componentes do monorepo.
- name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v3 with: # Optional. Specify a category to distinguish between multiple analyses # for the same tool and ref. If you don't use `category` in your workflow, # GitHub will generate a default category name for you category: "my_category"
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v3
with:
# Optional. Specify a category to distinguish between multiple analyses
# for the same tool and ref. If you don't use `category` in your workflow,
# GitHub will generate a default category name for you
category: "my_category"
Se você não especificar um parâmetro category
no fluxo de trabalho, o GitHub Enterprise Server vai gerar um nome de categoria para você, com base no nome do arquivo de fluxo de trabalho que dispara a ação, o nome da ação e todas as variáveis da matriz. Por exemplo:
- O fluxo de trabalho
.github/workflows/codeql-analysis.yml
e a açãoanalyze
produzirão a categoria.github/workflows/codeql.yml:analyze
. - O fluxo de trabalho
.github/workflows/codeql-analysis.yml
, a açãoanalyze
e as variáveis da matriz{language: javascript-typescript, os: linux}
produzirão a categoria.github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux
.
O valor category
será exibido como a propriedade <run>.automationDetails.id
no SARIF v2.1.0. Para obter mais informações, confira "Suporte SARIF para a varredura de código".
A categoria especificada não substituirá os detalhes do objeto runAutomationDetails
no arquivo SARIF, se incluído.
Estendendo a cobertura do CodeQL com pacotes de modelos do CodeQL
Se sua base de código depender de uma biblioteca ou estrutura que não seja reconhecida pelas consultas padrão no CodeQL, você poderá estender a cobertura do CodeQL no seu fluxo de trabalho do code scanning especificando pacotes de modelos publicados do CodeQL. Para obter mais informações sobre como criar seus próprios pacotes de modelo, confira "Como criar e trabalhar com pacotes do CodeQL".
Observação: os pacotes de modelos do CodeQL e o editor de modelos do CodeQL estão atualmente em beta e estão sujeitos a alterações. Os pacotes de modelo são compatíveis com a análise do Java/Kotlin.
Para adicionar um ou mais pacotes de modelos do CodeQL publicados, especifique-os na entrada with: packs:
com a seção uses: github/codeql-action/init@v3
do fluxo de trabalho. Em packs
, você especifica um ou mais pacotes a serem usados e, opcionalmente, a versão que será baixada. 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
para um segredo que tenha acesso aos pacotes. Para obter mais informações, confira "Autenticação automática de token" e "Usar segredos em ações do GitHub."
- uses: github/codeql-action/init@v3 with: config-file: ./.github/codeql/codeql-config.yml queries: security-extended packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack
- uses: github/codeql-action/init@v3
with:
config-file: ./.github/codeql/codeql-config.yml
queries: security-extended
packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack
Neste exemplo, as consultas padrão serão executadas para Java, bem como as consultas de uma versão superior ou igual a 7.8.9
e inferior a 7.9.0
do pacote de consultas my-company/my-java-queries
. As dependências modeladas na versão mais recente do pacote de modelos my-repo/my-java-model-pack
estarão disponíveis para as consultas padrão e aquelas no my-company/my-java-queries
.
Executar consultas adicionais
Ao usar CodeQL para fazer a varredura do código, o mecanismo de análise de CodeQL gera um banco de dados do código e executa consultas no mesmo. A análise de CodeQL usa um conjunto-padrão de consultas, mas você pode especificar outras consultas a serem executadas, além das consultas-padrão.
Você também pode especificar as consultas que deseja excluir da análise ou incluir na análise. Isso requer o uso de um arquivo de configuração personalizado. Para obter mais informações, consulte "Como usar um arquivo de configuração personalizado" e "Como excluir consultas específicas da análise" abaixo.
Você pode executar consultas adicionais se elas fizerem parte de um pacote do CodeQL publicado no GitHub Container registry ou um pacote do armazenado em um repositório. Para obter mais informações, confira "Sobre a varredura de código com CodeQL".
As opções disponíveis para especificar as consultas adicionais que você deseja executar são:
packs
para instalar um ou mais pacotes de consulta do CodeQL e executar o conjunto de consultas padrão ou as consultas desses pacotes.queries
para especificar um arquivo .ql individual, um diretório que contém vários arquivos .ql, um arquivo de definição de pacote de consultas .qls ou qualquer combinação. Para obter mais informações sobre as definições do pacote de consultas, confira "Como criar pacotes de consultas do CodeQL".
Use packs
e queries
no mesmo fluxo de trabalho.
Usando pacotes de consultas
Para adicionar um ou mais pacotes de consultas do CodeQL, adicione uma entrada with: packs:
à seção uses: github/codeql-action/init@v3
do fluxo de trabalho. Em packs
, você especifica um ou mais pacotes a serem usados e, opcionalmente, a versão que será baixada. 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
para um segredo que tenha acesso aos pacotes. Para obter mais informações, confira "Autenticação automática de token" e "Usar segredos em ações do GitHub."
Observação: para fluxos de trabalho que geram bancos de dados do CodeQL para várias linguagens, você precisará especificar pacotes de consulta do CodeQL em um arquivo de configuração. Para obter mais informações, confira "Como especificar pacotes de consulta do CodeQL" abaixo.
No exemplo abaixo, scope
é a organização ou a conta pessoal que publicou o pacote. Quando o fluxo de trabalho é executado, os três pacotes de consulta do CodeQL são baixados do GitHub Enterprise Server e das consultas ou conjunto de consultas padrão de cada execução de pacote:
- A última versão do
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 última versão do
pack3
que é compatível com a versão 3.2.1 é baixada e todas as consultas são executadas. - A versão 4.5.6 é
pack4
baixada e somente as consultas encontradas empath/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
- 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: se você especificar uma versão específica de um pacote de consultas a ser usado, cuidado para que a versão especificada não fique muito antiga para ser usada com eficiência pelo mecanismo padrão do CodeQL usado pela ação do CodeQL. Para garantir o desempenho ideal, se você precisar especificar versões exatas do pacote de consultas, considere examinar periodicamente se a versão fixada do pacote de consultas precisa ser atualizada.
Para obter mais informações sobre a compatibilidade de pacotes, confira "Publicar e usar pacotes do CodeQL".
Como baixar pacotes do CodeQL do GitHub Enterprise Server
Se o fluxo de trabalho usa pacotes publicados em uma instalação do GitHub Enterprise Server, você precisa informar ao fluxo de trabalho onde encontrá-los. Você pode fazer isso usando a entrada registries
da ação github/codeql-action/init@v3. Essa entrada aceita uma lista de propriedades url
, packages
e token
, como é mostrado abaixo.
- uses: github/codeql-action/init@v3 with: registries: | # URL to the container registry, usually in this format - url: https://containers.GHEHOSTNAME1/v2/ # List of package glob patterns to be found at this registry packages: - my-company/* - my-company2/* # Token, which should be stored as a secret token: ${{ secrets.GHEHOSTNAME1_TOKEN }} # URL to the default container registry - url: https://ghcr.io/v2/ # Packages can also be a string packages: "*/*" token: ${{ secrets.GHCR_TOKEN }}
- uses: github/codeql-action/init@v3
with:
registries: |
# URL to the container registry, usually in this format
- url: https://containers.GHEHOSTNAME1/v2/
# List of package glob patterns to be found at this registry
packages:
- my-company/*
- my-company2/*
# Token, which should be stored as a secret
token: ${{ secrets.GHEHOSTNAME1_TOKEN }}
# URL to the default container registry
- url: https://ghcr.io/v2/
# Packages can also be a string
packages: "*/*"
token: ${{ secrets.GHCR_TOKEN }}
Os padrões de pacote na lista de registros são examinados em ordem, portanto, coloque os padrões de pacote mais específicos em primeiro lugar. Os valores de token
precisam ser um personal access token (classic) gerado pela instância do GitHub da qual você está baixando com a permissão read:packages
.
Observe o |
após o nome da propriedade registries
. Isso é importante, pois as entradas do GitHub Actions só podem aceitar cadeias de caracteres. O uso de |
converte o texto subsequente em uma cadeia de caracteres, que é analisada depois pela ação github/codeql-action/init@v3.
Usando 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.
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.
- 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 }}
- 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 }}
Os conjuntos de consulta a seguir foram criados em CodeQL code scanning e estão disponíveis para uso.
Conjunto de consultas | Descrição |
---|---|
security-extended | Consultas do pacote padrão, além de consultas de gravidade e precisão inferiores |
security-and-quality | Consultas de security-extended , além de consultas de capacidade de manutenção e confiabilidade |
Para saber mais, confira "Conjuntos de consultas CodeQL".
Cada um desses conjuntos de consultas contém um subconjunto diferente das consultas incluídas no pacote de consultas integrado CodeQL para esse idioma. Os pacotes de consultas são gerados automaticamente por meio dos metadados de cada consulta. Para obter mais informações, confira "Metadados para consultas CodeQL".
Quando você especificar um pacote de consultas, o mecanismo de análise do CodeQL executará o conjunto padrão de consultas e todas as consultas extras definidas no pacote de consultas adicionais.
Trabalhando com arquivos de configuração personalizados
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 +
. Para obter mais informações, confira "Como usar um arquivo de configuração personalizado".
No exemplo a seguir, 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
- 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
Usando um arquivo de configuração personalizado
Um arquivo de configuração personalizado é uma maneira alternativa de especificar pacotes e consultas adicionais a serem executados. Use também o arquivo para desabilitar as consultas padrão, excluir ou incluir consultas específicas e para especificar quais diretórios verificar durante a análise.
No arquivo de fluxo de trabalho, use o parâmetro config-file
da ação init
para especificar o caminho para o arquivo de configuração que você deseja usar. Este exemplo carrega o arquivo de configuração ./.github/codeql/codeql-config.yml.
- uses: github/codeql-action/init@v3 with: config-file: ./.github/codeql/codeql-config.yml
- uses: github/codeql-action/init@v3
with:
config-file: ./.github/codeql/codeql-config.yml
O arquivo de configuração pode ser localizado no repositório que você está analisando ou em um repositório externo. O uso de um repositório externo permite que você especifique opções de configuração para vários repositórios em um único local. Ao fazer referência a um arquivo de configuração localizado em um repositório externo, você poderá usar a sintaxe OWNER/REPOSITORY/FILENAME@BRANCH . Por exemplo, octo-org/shared/codeql-config.yml@main.
Se o arquivo de configuração estiver localizado em um repositório privado externo, use o parâmetro external-repository-token
da ação init
para especificar um token que tenha acesso ao repositório privado.
- uses: github/codeql-action/init@v3 with: external-repository-token: ${{ secrets.ACCESS_TOKEN }}
- uses: github/codeql-action/init@v3
with:
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
As configurações no arquivo de configuração são gravadas no formato YAML.
Especificando pacotes de consulta de CodeQL
Você especificou pacotes de consulta de CodeQL em uma matriz. Observe que o formato é diferente do formato usado pelo arquivo de fluxo de trabalho.
packs: # Use the latest version of 'pack1' published by 'scope' - scope/pack1 # Use version 1.2.3 of 'pack2' - scope/pack2@1.2.3 # Use the latest version of 'pack3' compatible with 3.2.1 - scope/pack3@~3.2.1 # Use pack4 and restrict it to queries found in the 'path/to/queries' directory - scope/pack4:path/to/queries # Use pack5 and restrict it to the query 'path/to/single/query.ql' - scope/pack5:path/to/single/query.ql # Use pack6 and restrict it to the query suite 'path/to/suite.qls' - scope/pack6:path/to/suite.qls
packs:
# Use the latest version of 'pack1' published by 'scope'
- scope/pack1
# Use version 1.2.3 of 'pack2'
- scope/pack2@1.2.3
# Use the latest version of 'pack3' compatible with 3.2.1
- scope/pack3@~3.2.1
# Use pack4 and restrict it to queries found in the 'path/to/queries' directory
- scope/pack4:path/to/queries
# Use pack5 and restrict it to the query 'path/to/single/query.ql'
- scope/pack5:path/to/single/query.ql
# Use pack6 and restrict it to the query suite 'path/to/suite.qls'
- scope/pack6:path/to/suite.qls
O formato completo para especificar um pacote de consultas é scope/name[@version][:path]
. version
e path
são opcionais. version
é o intervalo de versão semver. Se ele estiver ausente, a última versão será usada. Para obter mais informações sobre intervalos semver, confira a documentação do semver no npm.
Se tiver um fluxo de trabalho que gera mais de um banco de dados de CodeQL, você poderá especificar todos os pacotes de consulta de CodeQL para executar em um arquivo de configuração personalizado usando um mapa aninhado de pacotes.
packs: # Use these packs for JavaScript and TypeScript analysis javascript: - scope/js-pack1 - scope/js-pack2 # Use these packs for Java and Kotlin analysis java: - scope/java-pack1 - scope/java-pack2@v1.0.0
packs:
# Use these packs for JavaScript and TypeScript analysis
javascript:
- scope/js-pack1
- scope/js-pack2
# Use these packs for Java and Kotlin analysis
java:
- scope/java-pack1
- scope/java-pack2@v1.0.0
Especificar consultas adicionais
As consultas adicionais são especificadas em uma matriz queries
. Cada elemento da matriz contém um parâmetro uses
com um valor que identifica um arquivo de consulta individual, um diretório contendo arquivos de consulta ou um arquivo de definição de conjunto de consultas.
queries: - uses: ./my-basic-queries/example-query.ql - uses: ./my-advanced-queries - uses: ./query-suites/my-security-queries.qls
queries:
- uses: ./my-basic-queries/example-query.ql
- uses: ./my-advanced-queries
- uses: ./query-suites/my-security-queries.qls
Opcionalmente, você pode dar um nome a cada elemento do array, conforme mostrado nos exemplos de arquivos de configuração abaixo. Para obter mais informações sobre consultas adicionais, confira "Como executar consultas adicionais" acima.
Desativar as consultas-padrão
Se você quiser apenas executar consultas personalizadas, poderá desabilitar as consultas de segurança padrão usando disable-default-queries: true
.
Como excluir consultas específicas da análise
Você pode adicionar os filtros exclude
e include
ao seu arquivo de configuração personalizado para especificar as consultas que deseja excluir ou incluir na análise.
Isso será útil se você quiser excluir, por exemplo:
- Consultas específicas dos pacotes padrão (
security
,security-extended
esecurity-and-quality
). - Consultas específicas cujos resultados não interessam a você.
- Todas as consultas que geram avisos e recomendações.
Você pode usar filtros exclude
semelhantes aos do arquivo de configuração abaixo para excluir as consultas que deseja remover da análise padrão. No exemplo do arquivo de configuração abaixo, as consultas js/redundant-assignment
as js/useless-assignment-to-local
são excluídas da análise.
query-filters: - exclude: id: js/redundant-assignment - exclude: id: js/useless-assignment-to-local
query-filters:
- exclude:
id: js/redundant-assignment
- exclude:
id: js/useless-assignment-to-local
Para localizar a ID de uma consulta, você pode clicar no alerta da lista de alertas na guia Segurança. Isso abre a página de detalhes do alerta. O campo Rule ID
contém a ID da consulta. Para obter mais informações sobre a página de detalhes do alerta, confira "Sobre alertas de digitalização de códigos".
Dicas:
- A ordem dos filtros faz diferença. A primeira instrução de filtro exibida após as instruções sobre as consultas e os pacotes de consulta determina se as consultas são incluídas ou excluídas por padrão.
- As instruções subsequentes são executadas em ordem e as instruções que aparecem posteriormente no arquivo têm precedência sobre as instruções anteriores.
Você pode encontrar outro exemplo ilustrando o uso desses filtros na seção "Arquivos de configuração de exemplo".
Para obter mais informações sobre como usar os filtros exclude
e include
em seu arquivo de configuração personalizado, confira "Como criar conjuntos de consultas do CodeQL". Para obter informações sobre os metadados de consulta nos quais você pode filtrar, confira "Metadados para consultas CodeQL".
Especificar diretórios para serem varridos
Quando as bases de código são analisadas sem compilar o código, você pode restringir code scanning a arquivos em diretórios específicos adicionando uma matriz paths
matriz ao arquivo de configuração. Você também pode excluir os arquivos de diretórios específicos da análise ao adicionar uma matriz paths-ignore
. Você pode usar essa opção ao executar as ações de CodeQL em uma linguagem interpretada (Python, Ruby e JavaScript/TypeScript).
paths: - src paths-ignore: - src/node_modules - '**/*.test.js'
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
Observação:
- As palavras-chave
paths
epaths-ignore
, usadas no contexto do arquivo de configuração da code scanning, não devem ser confundidas com as mesmas palavras-chave quando usadas paraon.<push|pull_request>.paths
em um fluxo de trabalho. Quando são usadas para modificaron.<push|pull_request>
em um fluxo de trabalho, elas determinam se as ações serão executadas quando alguém modificar o código nos diretórios especificados. Para obter mais informações, confira "Sintaxe de fluxo de trabalho para o GitHub Actions". - Os caracteres de padrão de filtro
?
,+
,[
,]
e!
não têm suporte e serão correspondidos literalmente. **
os caracteres só podem estar no início ou no final de uma linha, ou circundados por barras, e você não pode misturar**
e outros caracteres. Por exemplo,foo/**
,**/foo
efoo/**/bar
são todas as sintaxes permitidas, mas**foo
não é. No entanto, você pode usar estrelas únicas junto com outros caracteres, conforme mostrado no exemplo. Você precisará citar qualquer coisa que contenha um caractere*
.
Em análises em que o código é compilado, caso deseje limitar code scanning a diretórios específicos no projeto, é necessário especificar as etapas adequadas de build no Workflow. Os comandos que você precisará usar para excluir um diretório da compilação dependerão do seu sistema de compilação. Para obter mais informações, confira "Verificação de código do CodeQL para linguagens compiladas".
Você pode analisar rapidamente pequenas partes de um repositório único quando modifica o código em diretórios específicos. Você precisará excluir os diretórios das etapas de build e usar as palavras-chave paths-ignore
e paths
para on.<push|pull_request>
no fluxo de trabalho.
Exemplo de arquivos de configuração
Este arquivo de configuração adiciona o conjunto de consulta security-and-quality
à lista de consultas executadas pelo CodeQL ao fazer a verificação do seu código. Para obter mais informações sobre os conjuntos de consulta disponíveis para uso, veja "Executando consultas adicionais".
name: "My CodeQL config"
queries:
- uses: security-and-quality
O seguinte arquivo de configuração desabilita as consultas-padrão e especifica um conjunto de consultas personalizadas para serem executadas. Ele também configura o CodeQL para verificar arquivos no diretório src (em relação à raiz), com exceção do diretório src/node_modules e exceto arquivos cujos nomes terminam em .test.js. Os arquivos no src/node_modules e arquivos com nomes que terminam em .test.js são, portanto, excluídos da análise.
name: "My CodeQL config"
disable-default-queries: true
queries:
- name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
uses: ./my-queries
- name: Use an external JavaScript CodeQL pack (run queries from an external repo)
uses: octo-org/javascript-codeql-pack@main
- name: Use an external query (run a single query from an external CodeQL pack)
uses: octo-org/python-codeql-pack/show_ifs.ql@main
- name: Use a query suite file (run queries from a query suite in this repo)
uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
O arquivo de configuração a seguir executa apenas consultas que geram alertas de erro de gravidade. A configuração primeiro seleciona todas as consultas padrão, todas as consultas em ./my-queries
e o pacote padrão em codeql/java-queries
, depois exclui todas as consultas que geram avisos ou recomendações.
queries:
- name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
uses: ./my-queries
packs:
- codeql/java-queries
query-filters:
- exclude:
problem.severity:
- warning
- recommendation
Especificando detalhes de configuração usando a entrada config
Se preferir especificar detalhes de configuração adicionais no arquivo de fluxo de trabalho, você poderá usar a entrada config
do comando init
da ação CodeQL. O valor dessa entrada deve ser uma cadeia de caracteres YAML que siga o formato de arquivo de configuração documentado em "Usando um arquivo de configuração personalizado" acima.
Configuração de exemplo
Esta etapa em um arquivo de fluxo de trabalho do GitHub Actions usa uma entrada config
para desabilitar as consultas padrão, adicionar o conjunto de consultas security-extended
e excluir consultas marcadas com cwe-020
.
- uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
config: |
disable-default-queries: true
queries:
- uses: security-extended
query-filters:
- exclude:
tags: /cwe-020/
Você pode usar a mesma abordagem para especificar as opções de configurações válidas no arquivo de fluxo de trabalho.
Dica:
Você pode compartilhar uma configuração em vários repositórios usando variáveis de GitHub Actions. Um benefício dessa abordagem é que você pode atualizar a configuração em um único lugar sem editar o arquivo de fluxo de trabalho.
No exemplo a seguir, vars.CODEQL_CONF
é uma variável de GitHub Actions. Seu valor pode ser o conteúdo de qualquer arquivo de configuração válido. Para obter mais informações, confira "Armazenar informações em variáveis".
- uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
config: ${{ vars.CODEQL_CONF }}
Configurar o code scanning para linguagens compiladas
Para linguagens compiladas, a ação de CodeQL compila a base de código para criar um banco de dados de CodeQL para análise. Por padrão, CodeQL usa etapas de autobuild
para identificar o método de build mais provável para a base de código. Se autobuild
falhar ou se você quiser analisar um conjunto diferente de arquivos de origem daqueles criados pelo processo de autobuild
, será necessário remova ou comente a etapa de compilação automática no fluxo de trabalho. Em seguida, remova a marca de comentário da etapa de run
e especifique manualmente o processo de compilação a ser usado. Para C/C++, C#, Go, Java, Kotlin, e Swift, CodeQL analisará qualquer código-fonte criado pelas etapas de compilação especificadas. Para obter mais informações sobre como configurar a code scanning do CodeQL para as linguagens compiladas, confira "Verificação de código do CodeQL para linguagens compiladas".
Carregar dados do code scanning no GitHub
GitHub pode exibir dados de análise de código gerados externamente por uma ferramenta de terceiros. Carregue os dados da análise de código com a ação upload-sarif
. Para obter mais informações, confira "Fazer o upload de arquivo SARIF para o GitHub".