Skip to main content

Esta versão do GitHub Enterprise será descontinuada em 2022-09-28. 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

Você pode usar CodeQL runner para executar CodeQL code scanning em um sistema de integração contínua de terceiros.

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. Para obter mais informações, confira "Sobre o GitHub Advanced Security".

Observação: o CodeQL runner está sendo preterido. No GitHub Enterprise Server 3.0 e superior, você pode instalar a CodeQL CLI versão 2.6.3 para substituir o CodeQL runner.

Para obter mais informações, confira a reprovação do executor do CodeQL. Para obter informações sobre como migrar para a CodeQL CLI, confira "Como migrar do executor do CodeQL para a CLI do CodeQL".

Observação: o administrador do site precisa habilitar a code scanning para o your GitHub Enterprise Server instance para que você possa usar esse recurso. Para obter mais informações, confira "Como configurar a code scanning para seu dispositivo".1

Sobre o CodeQL runner

O CodeQL runner é uma ferramenta que você pode usar para executar code scanning no código que você está processando em um sistema de integração contínua de terceiros (CI). 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 de 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 de Advanced Security.

Fazer o download do 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.

Adicionar CodeQL runner ao seu sistema de CI

Após fazer o download de CodeQL runner e verificar se pode ser executado, você deverá disponibilizar o executor para cada servidor de CI que você pretende usar para 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 o token de acesso pessoal do CodeQL runner a ser usado. 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 token de acesso pessoal".
  • Acesso ao pacote de 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 o local do pacote em chamadas para inicializar o CodeQL runner.

Chamar CodeQL runner

Você deve chamar CodeQL runner 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 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 token de acesso pessoal 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.

Você pode configurar o local em que o CodeQL runner armazena o pacote do CodeQL para análise futura em um servidor usando o sinalizador --tools-dir e o local 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 CodeQL runner e crie banco 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 CodeQL runner e crie banco 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 seu 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