Note: The Executor do CodeQL is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the Executor do CodeQL. On GitHub Enterprise Cloud, the Executor do CodeQL will be supported until March 2022. For more information, see the CodeQL runner deprecation.
Observação: Varredura de código está em beta em GitHub Enterprise Server 2.22. Para a versão geralmente disponível do varredura de código, atualize para a versão mais recente de GitHub Enterprise Server.
Observação: O administrador do site deve habilitar Varredura de código para sua instância do GitHub Enterprise Server antes de usar este recurso. Para obter mais informações, consulte "Configurar o Varredura de código para seu aplicativo ".
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. Quaisquer problemas identificados pela análise são exibidos em GitHub Enterprise Server. 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 Enterprise Server. Para obter informações, consulte "Configurar 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 Enterprise Server. Estes resultados são exibidos como alertas do Varredura de código no repositório.
Notas:
- O Executor do CodeQL está disponível para os clientes com uma licença de Segurança Avançada.
- O Executor do CodeQL não deve ser confundido com o CLI de CodeQL. O CLI de CodeQL é uma interface de linha de comando interativa que permite que você crie bancos de dados de CodeQL para pesquisa de segurança e realize consultas de CodeQL. Para obter mais informações, consulte " CLI de CodeQL".
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 fazer o download de Executor do CodeQL e verificar se pode ser executado, você deverá disponibilizar o executor para cada servidor de CI que você pretende usar para Varredura de código. 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://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 aplicativo GitHub ou um token de acesso pessoal para Executor do CodeQL usar. Você deve usar um token de acesso com o escopo do
repositório
, ou um aplicativo GitHub com a permissão de gravação desecurity_events
emetadados
e permissões de leitura deconteúdo
. 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 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, consulte "CLI de CodeQL".
As opções para fornecer acesso ao pacote deCodeQL são:
- Permite que os servidores de CI acessem https://github.com/github/codeql-action para que Executor do CodeQL possa fazer o download do pacote automaticamente.
- Espelhe o repositório
github/codeql-action
em GitHub Enterprise Server. A menos que você especifique o sinalizador , o executor verifica automaticamente o pacote neste local e no GitHub.com.--codeql-path
- Faça o download/extraia o pacote manualmente, armazene-o com outros recursos centrais e use
o sinalizador para especificar o local do pacote nas chamadas para inicializar o Executor do CodeQL.--codeql-path
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:
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.análise
necessário para preencher os bancos de dados CodeQL, analisá-los e fazer o upload dos resultados para GitHub Enterprise Server.
Para ambos os comandos, você deve especificar a URL de GitHub Enterprise Server, o repositório **OWNER/NAME e o Aplicativos do GitHub ou token de acesso pessoal para usar para autenticação. Você também precisa especificar a localização do pacote CodeQL, a menos que o servidor CI tenha acesso para fazer o download diretamente do repositório github/codeql-action
.
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
--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".
Notas:
-
SARIF upload supports a maximum of 1000 results per upload. Todos os resultados acima deste limite são ignorados. Se uma ferramenta gerar muitos resultados, você deverá atualizar a configuração para focar nos resultados para as regras ou consultas mais importantes.
-
For each upload, SARIF upload supports a maximum size of 10 MB for the
gzip
-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.
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.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 fazer o download do pacote CodeQL diretamente do repositório github/codeql-action
. Portanto, não há necessidade de usar o sinalizador --codeql-path
.
-
Confira o repositório a ser analisado.
-
Mova para o diretório para o local onde o repositório está reservado.
-
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.example.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.
-
Preencha os bancos de dados de CodeQL, analise-os e faça o upload dos resultados para GitHub Enterprise Server. Os resultados aparecerão na aba Segurança do seu repositório.
$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --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
-
Para fazer o upload dos resultados de Varredura de código como verificações de pull request, especifique do pull request usando
sinalizador. Recomendamos configurar Executor do CodeQL para que seja executado no evento de webhook--ref
pull_request
.$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --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 mais informações sobre a visualização de alertas de Varredura de código, consulte "Alertas de verificação de código triagem em pull requests" e "Gerenciar alertas de verificação de códigos 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 de criação normal da CI e, em seguida, executar o comando analisar
.
-
Confira o repositório a ser analisado.
-
Mova para o diretório para o local onde o repositório está reservado.
-
Inicialize Executor do CodeQL e crie banco de dados do CodeQL para as linguagens detectadas.
<pre><code class="hljs language-shell">$ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2 --github-url https://github.example.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 criação, por exemplo, executando
". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
-
Extraia o script gerado pela ação
iniciar
para configurar o ambiente a fim de monitorar a criação. Observe o ponto e espaço principal no seguinte trecho do código.$ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
-
Crie o código. No macOS, você precisa prefixar o comando de criação com a variável de ambiente
$CODEQL_RUNNER
. Para obter mais informações, consulte "Solução de problemas de varredura de código de CodeQL no seu sistema de CI". -
Preencha os bancos de dados de CodeQL, analise-os e faça o upload dos resultados para GitHub Enterprise Server. Os resultados aparecerão na aba Segurança do seu repositório.
$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --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
-
Para fazer o upload dos resultados de Varredura de código como verificações de pull request, especifique do pull request usando
sinalizador. Recomendamos configurar Executor do CodeQL para que seja executado no evento de webhook--ref
pull_request
.$ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth TOKEN --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 mais informações sobre a visualização de alertas de Varredura de código, consulte "Alertas de verificação de código triagem em pull requests" e "Gerenciar alertas de verificação de códigos para seu repositório".
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.