Skip to main content

Esta versão do GitHub Enterprise será descontinuada em 2023-01-18. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, segurança aprimorada e novos recursos, atualize para a última versão do GitHub Enterprise. Para obter ajuda com a atualização, entre em contato com o suporte do GitHub Enterprise.

Executando um executor de CodeQL no seu sistema de CI

Use o CodeQL runner para executar a CodeQL code scanning em um sistema de integração contínua de terceiros.

A Code scanning está disponível para os repositórios pertencentes à organização no GitHub Enterprise Server. Esse recurso exige uma licença do GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Note: The CodeQL runner is being deprecated. On GitHub Enterprise Server 3.0 and greater, you can install CodeQL CLI version 2.6.3 to replace CodeQL runner.

For more information, see the CodeQL runner deprecation. For information on migrating to CodeQL CLI, see "Migrating from the CodeQL runner to CodeQL CLI."

Note: Your site administrator must enable code scanning for your GitHub Enterprise Server instance before you can use this feature. For more information, see "Configuring code scanning for your appliance."

Sobre o CodeQL runner

O CodeQL runner é uma ferramenta que você pode usar para executar a code scanning no código que está processando em um sistema de CI (integração contínua) de terceiros. Code scanning é 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. Quaisquer problemas identificados pela análise são exibidos em GitHub Enterprise Server. Para obter informações, confira "Sobre a code scanning com o CodeQL".

Em muitos casos, é mais fácil configurar CodeQL code scanning usando CodeQL CLI diretamente no seu sistema de CI.

Como alternativa, você pode usar GitHub Actions para executar code scanning em GitHub Enterprise Server. Para obter informações, confira "Como configurar a code scanning para um repositório".

O CodeQL runner é uma ferramenta de linha de comando que executa a análise do CodeQL em um checkout de um repositório do GitHub. Você adiciona o executor ao sistema de terceiros e chama o executor para analisar o código e carregar os resultados no GitHub Enterprise Server. Estes resultados são exibidos como alertas do code scanning no repositório.

Observação:

  • O CodeQL runner está disponível para os clientes com uma licença do Advanced Security.

Como baixar o CodeQL runner

Baixe o CodeQL runner em https://HOSTNAME/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 geralmente não exige nenhuma alteração nas permissões.

Como adicionar o CodeQL runner ao seu sistema de CI

Depois de baixar o CodeQL runner e verificar se ele pode ser executado, você deverá disponibilizar o executor para cada servidor de CI que pretende usar para a code scanning. Por exemplo, você pode configurar cada servidor para que copie o executor de um local central interno. Como alternativa, você poderia usar a API REST para obter o executor diretamente do GitHub, por exemplo:

wget https://HOSTNAME/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 GitHub App ou um personal access token para uso do CodeQL runner. Você precisa usar um token de acesso com o escopo repo ou um GitHub App com a permissão de gravação em security_events e permissões de leitura em metadata e em contents. Para obter informações, confira "Como criar GitHub Apps" e "Como criar um personal access token".
  • Acesso ao pacote do CodeQL associado a esta versão do CodeQL runner. Este pacote contém consultas e bibliotecas necessárias para a análise de CodeQL mais o CLI de CodeQL, que é usado internamente pelo executor. Para obter informações, confira "CLI do CodeQL".

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

  1. Permita que os servidores de CI acessem https://HOSTNAME/github/codeql-action para que o CodeQL runner possa baixar o pacote automaticamente.
  2. Baixe/extraia manualmente o pacote, armazene-o com outros recursos centrais e use o sinalizador --codeql-path para especificar a localização do pacote em chamadas para inicializar o CodeQL runner.

Como chamar o CodeQL runner

Você deve chamar o CodeQL runner na localização 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 do CodeQL para cada linguagem a ser analisada. Estas bases de dados são preenchidas e analisadas por comandos subsequentes.
  2. analyze, necessário para preencher os bancos de dados do CodeQL, analisá-los e carregar os resultados no GitHub Enterprise Server.

Para os dois comandos, você precisa especificar a URL do GitHub Enterprise Server, o OWNER/NAME do repositório e os GitHub Apps ou o personal access token a serem usados para autenticação. Você também precisa especificar o local do pacote do CodeQL, a menos que o servidor de CI tenha acesso para baixá-lo diretamente do repositório github/codeql-action.

Configure a localização em que o CodeQL runner armazena o pacote do CodeQL para análise futura em um servidor usando o sinalizador --tools-dir e a localização em que ele armazena os arquivos temporários durante a análise usando --temp-dir.

Para ver a referência de linha de comando do executor, use o sinalizador -h. Por exemplo, para listar todos os comandos, execute codeql-runner-OS -h, ou para listar todos os sinalizadores disponíveis para o comando init, execute codeql-runner-OS init -h (em que OS varia de acordo com o executável que está sendo usado). Para obter mais informações, confira "Como configurar a code scanning no seu sistema de CI".

Observações:

  • O upload do SARIF dá suporte a um máximo de 5.000 resultados por upload. Todos os resultados acima desse limite são ignorados. Se uma ferramenta gerar muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados referentes às regras ou às consultas mais importantes.

  • Para cada upload, o upload do SARIF dá suporte a, no máximo, 10 MB para o arquivo SARIF compactado em gzip. Todos os uploads acima desse limite são rejeitados. Se o arquivo SARIF for muito grande porque contém muitos resultados, você deverá atualizar a configuração para se concentrar nos resultados das regras ou consultas mais importantes.

Exemplo básico

Este exemplo executa a análise do CodeQL em um servidor de CI do Linux para o repositório octo-org/example-repo hospedado em https://github.example.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).

Neste exemplo, o servidor tem acesso para baixar o pacote do CodeQL diretamente do repositório github/codeql-action, ou seja, não é necessário usar o sinalizador --codeql-path.

  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 o CodeQL runner e crie bancos de dados do CodeQL para as linguagens detectadas.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. Preencha os bancos de dados do CodeQL, analise-os e carregue os resultados no GitHub Enterprise Server. Os resultados serão exibidos na guia Segurança do repositório.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  5. Para carregar os resultados da code scanning como verificações de solicitação de pull, especifique a solicitação de pull usando o sinalizador --ref. Recomendamos configurar o CodeQL runner para que ele seja executado no evento de webhook pull_request.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

Para obter mais informações sobre como ver alertas da code scanning, confira "Como fazer a triagem de alertas da verificação de código em solicitações de pull" e "Como gerenciar alertas da verificação de código para 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 normal de build de CI e executar o comando analyze.

  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 o CodeQL runner e crie bancos de dados do CodeQL para as linguagens detectadas.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth-stdin
    > 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".
      Please export these variables to future processes so that CodeQL can monitor the build, for example by running 
      ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. Obtenha o script gerado pela ação init para configurar o ambiente para monitorar o build. Observe o ponto e espaço principal no seguinte trecho do código.

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. Crie o código. No macOS, você precisa adicionar a variável de ambiente $CODEQL_RUNNER como prefixo ao comando de build. Para obter mais informações, confira "Solução de problemas do CodeQL runner no sistema de CI".

  6. Preencha os bancos de dados do CodeQL, analise-os e carregue os resultados no GitHub Enterprise Server. Os resultados serão exibidos na guia Segurança do repositório.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  7. Para carregar os resultados da code scanning como verificações de solicitação de pull, especifique a solicitação de pull usando o sinalizador --ref. Recomendamos configurar o CodeQL runner para que ele seja executado no evento de webhook pull_request.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

Para obter mais informações sobre como ver alertas da code scanning, confira "Como fazer a triagem de alertas da verificação de código em solicitações de pull" e "Como gerenciar alertas da verificação de código para seu repositório".

Observação: se você usar um build conteinerizado, precisará executar o CodeQL runner no contêiner em que a tarefa de build ocorre.

Leitura adicional