pt Publicamos atualizações frequentes em nossa documentação, e a tradução desta página ainda pode estar em andamento. Para obter as informações mais recentes, acesse a documentação em inglês. Se houver problemas com a tradução desta página, entre em contato conosco.

Executar varredura de código CodeQL no seu sistema de CI

Você pode usar Executor do CodeQL para executar CodeQL Varredura de código em um sistema de integração contínua de terceiros.

Varredura de código está disponível em repositórios públicos, e em repositórios privados pertencentes a organizações com uma licença de Segurança Avançada. Para obter mais informações, consulte "produtos de GitHub

Neste artigo

Observação: Os Executor do CodeQL está atualmente em fase beta e sujeito a alterações.

Usar CodeQL Varredura de código com o seu sistema CI existente

Se você usar um sistema de integração contínua ou de entrega/implantação contínua (CI/CD) diferente de GitHub Actions, você pode usar o seu sistema existente para executar a análise CodeQL de GitHub e enviar os resultados para GitHub. Para fazer isso, use Executor do CodeQL.

Sobre o Executor do CodeQL

Varredura de código é um recurso que você usa para analisar o código em um repositório de GitHub para localizar vulnerabilidades de segurança e erros de codificação. Todos os problemas identificados pela análise são exibidos em GitHub. Para obter informações, consulte "Sobre Varredura de código.

Você pode usar Executor do CodeQL para executar o Varredura de código no código que você está processando em um sistema de integração contínua (CI) de terceiros. Como alternativa, você pode usar GitHub Actions para executar Varredura de código em GitHub. Para obter informações, consulte "Habilitar Varredura de código para um repositório".

O Executor do CodeQL é uma ferramenta de linha de comando que executa a análise de CodeQL em um checkout de um repositório do GitHub. Você adiciona o executor ao seu sistema de terceiros e, em seguida, chama o executor para analisar o código e fazer o upload dos resultados para o GitHub. Estes resultados são exibidos como alertas do Varredura de código no repositório.

Fazer o download do Executor do CodeQL

Você pode fazer o download do Executor do CodeQL em https://github.com/github/codeql-action/releases. Em alguns sistemas operacionais, talvez você precise alterar as permissões para o arquivo baixado antes de executá-lo.

No Linux:

chmod +x codeql-runner-linux

No macOS:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

No Windows, o arquivo codeql-runner-win.exe normalmente não exige alteração de permissões.

Adicionar Executor do CodeQL ao seu sistema de CI

Após concluído o download do Executor do CodeQL e verificado que pode ser executado, você deve disponibilizar o executor para cada servidor de CI que você pretende usar para Varredura de código. É importante notar que cada servidor de CI que você pretende usar para Varredura de código deve ter o Executor do CodeQL. Você pode configurar cada servidor para copiar o executor a partir de um local central interno ou você pode usar a API REST para obter o executor direto do GitHub, por exemplo:

wget https://github.com/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

Além disso, cada servidor de CI também precisa:

  • Um Aplicativos do GitHub ou um token de acesso pessoal para Executor do CodeQL usar. Para repositórios privados, o token deve ter o escopo do repositório. Para público, o token precisa apenas dos escopos public_repo e repo:security_events. Para obter informações, consulte "Criar Aplicativos do GitHub" e "Criar um token de acesso pessoal".
  • Acesso ao pacote de CodeQL associado a esta versão do Executor do CodeQL. Este pacote contém CLI de CodeQL, consultas e bibliotecas necessárias para a análise de CodeQL. Para obter informações, consulte "CLI de CodeQL".

As opções para fornecer acesso ao pacote deCodeQL são:

  1. Permitir o acesso dos servidores de CI ao GitHub.com para que o Executor do CodeQL possa fazer o download do pacote automaticamente.
  2. Fazer o download/extrair manualmente o pacote, armazená-lo com outros recursos centrais e usar o sinalizador --codeql-path para especificar a localização do pacote nas chamadas para inicializar o Executor do CodeQL.

Chamar Executor do CodeQL

Você deve chamar Executor do CodeQL no local de checkout do repositório que deseja analisar. Os dois comandos principais são:

  1. init necessário para inicializar o executor e criar um banco de dados de CodeQL para que cada linguagem seja analisada. Estas bases de dados são preenchidas e analisadas por comandos subsequentes.
  2. análise necessário para preencher os bancos de dados CodeQL, analisá-los e fazer o upload dos resultados para GitHub.

Para ambos os comandos, você deve especificar a URL de GitHub, o repositório OWNER/NAME e os aplicativos GitHub ou o token de acesso pessoal para usar na autenticação. Você também precisa especificar a localização do pacote do CodeQL, a menos que o servidor de CI tenha acesso para baixá-lo diretamente do repositório github/codeql-action em GitHub.com.

Você pode configurar o local onde o Executor do CodeQL armazena o pacote do CodeQL para futuras análises em um servidor usando o sinalizador --tools-dir e onde armazena arquivos temporários durante a análise usando --temp-dir.

Para visualizar a referência de linha de comando para o executor, use o sinalizador -h. Por exemplo, para listar todos os comandos executados: codeql-runner-OS -h ou para listar todos os sinalizadores disponíveis para o comando init executado: codeql-runner-OS init -h (em que OS varia de acordo com o executável que você está usando). Para obter mais informações, consulte "Configurar o Varredura de código no seu sistema de CI".

Exemplo básico

Este exemplo executa a análise do CodeQL em um servidor de Linux CI para o repositório octo-org/example-repo hospedado em https://github.com. O processo é muito simples porque o repositório contém apenas linguagens que podem ser analisadas diretamente pelo CodeQL, sem ser criado (ou seja, Go, JavaScript, Python e TypeScript).

  1. Confira o repositório a ser analisado.

  2. Mova para o diretório para o local onde o repositório está reservado.

  3. Inicialize Executor do CodeQL e crie banco de dados do CodeQL para as linguagens detectadas.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Banco de dados do CodeQL criado em /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. Preencha os bancos de dados de Executor do CodeQL, analise-os e faça o upload dos resultados para GitHub.

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.com --github-auth TOKEN
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

O servidor tem acesso para fazer o download do pacote de CodeQL diretamente do repositório github/codeql-action no GitHub.com. Portanto, não há necessidade de usar o sinalizador --codeql-path. Quando a análise for concluída, o Executor do CodeQL faz o upload dos resultados para a visualização de Varredura de código. Para obter mais informações, consulte "Gerenciar alertas de Varredura de código para o seu repositório".

Exemplo de linguagem compilada

Este exemplo é semelhante ao exemplo anterior. No entanto, desta vez, o repositório tem o código em C/C++, C# ou Java. Para criar um banco de dados de CodeQL para essas linguagens, o CLI precisa monitorar a criação. No final do processo de inicialização, o executor informa o comando que você precisa configurar o ambiente antes de criar o código. Você precisa executar esse comando antes de chamar o processo de criação normal da CI e, em seguida, executar o comando analisar.

  1. Confira o repositório a ser analisado.

  2. Mova para o diretório para o local onde o repositório está reservado.

  3. Inicialize Executor do CodeQL e crie banco de dados do CodeQL para as linguagens detectadas.

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
    > ...
    > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
      and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
      Exporte essas variáveis para processos futuros para que o CodeQL possa monitorar a compilação, por exemplo, executando "
      . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. Execute o script gerado pela ação init para configurar o ambiente para monitorar a criação.

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. Crie o código.

  6. Preencha os bancos de dados de CodeQL, analise-os e faça o upload dos resultados para o GitHub.

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo-2
        --github-url https://github.com --github-auth TOKEN
        --commit ae7b655ef30b50fb726ae7b3daa79571a39d194d --ref refs/heads/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo-2/code-scanning/sarifs - 202 in 573ms
    > Successfully uploaded results

Observação: Se você usar uma criação conteinerizada, você deverá executar o Executor do CodeQL no contêiner em que ocorre a tarefa de criação.

Leia mais

Esse documento ajudou você?

Privacy policy

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.