Como criar bancos de dados do CodeQL

Sobre a criação de bancos de dados do CodeQL

Antes de analisar o código usando o CodeQL, você precisa criar um banco de dados do CodeQL contendo todos os dados necessários para executar consultas no código. Você pode criar bancos de dados do CodeQL usando a CodeQL CLI ou baixá-los do GitHub.com.

A análise do CodeQL depende da extração de dados relacionais do código e do uso deles para criar um banco de dados do CodeQL. Os bancos de dados do CodeQL contêm todas as informações importantes sobre uma base de código, que podem ser analisadas executando consultas do CodeQL. O GitHub cria e armazena bancos de dados do CodeQL para um grande número de projetos de código aberto. Para obter mais informações, confira "Como baixar bancos de dados do CodeQL por meio do GitHub.com".

Você também pode criar bancos de dados do CodeQL usando a CodeQL CLI. Antes de gerar um banco de dados do CodeQL, você precisa:

• Instalar e configurar a CodeQL CLI. Para obter mais informações, confira "Introdução à CodeQL CLI".
• Conferir a versão da base de código que você deseja analisar. O diretório deve estar pronto para ser criado, com todas as dependências já instaladas.

Para obter informações de como usar a CodeQL CLI em um sistema de CI de terceiros para criar resultados a serem exibidos no GitHub como alertas de verificação de código, confira Como configurar a CodeQL CLI no sistema de CI. Para obter informações de como habilitar a verificação de código do CodeQL usando o GitHub Actions, confira Como configurar a verificação de código em um repositório.

Em execuçãocodeql database create

Os bancos de dados do CodeQL são criados executando o seguinte comando na raiz de check-out do projeto:

codeql database create <database> --language=<language-identifier>

É preciso especificar:

• <database>: é um caminho para o novo banco de dados a ser criado. Esse diretório será criado quando você executar o comando. Não é possível especificar um diretório existente.
• --language: o identificador da linguagem em que o banco de dados será criado. Quando usado com --db-cluster, a opção aceita uma lista separada por vírgulas ou pode ser especificada mais de uma vez. O CodeQL dá suporte à criação de bancos de dados para as seguintes linguagens:

Linguagem	Identificador
C/C++	cpp
C#	csharp
Go	go
Java	java
JavaScript/TypeScript	javascript
Python	python
Ruby	ruby

Você poderá especificar opções adicionais dependendo do local do arquivo de origem, se o código precisar ser compilado e se quiser criar bancos de dados do CodeQL para mais de uma linguagem:

• --source-root: a pasta raiz dos arquivos de origem primários usados na criação do banco de dados. Por padrão, o comando pressupõe que o diretório atual é o diretório raiz. Use essa opção para especificar outro local.
• --db-cluster: use para bases de código de várias linguagens quando quiser criar bancos de dados para mais de uma linguagem.
• --command: usado quando você cria um banco de dados para uma ou mais linguagens compiladas. Omitido quando as únicas linguagens solicitadas são Python e JavaScript. Isso especifica os comandos de build necessários para invocar o compilador. Os comandos são executados na pasta atual ou no local --source-root, quando especificado. Se você não incluir um --command, o CodeQL tentará detectar o sistema de build automaticamente usando um construtor automático interno.
• --no-run-unnecessary-builds: usado com --db-cluster para suprimir o comando de build de linguagens em que a CodeQL CLI não precisa monitorar o build (por exemplo, Python e JavaScript/TypeScript).

Você pode especificar opções de extrator para personalizar o comportamento de extratores que criam bancos de dados do CodeQL. Para obter mais informações, confira "Opções de extratores".

Para obter detalhes completos de todas as opções que você pode usar ao criar bancos de dados, confira "database create".

Progresso e resultados

Erros serão relatados se houver problemas com as opções especificadas. Para linguagens interpretadas, o progresso da extração é exibido no console. Para cada arquivo de origem, ele relata se a extração foi bem-sucedida ou falhou. Para linguagens compiladas, o console exibirá a saída do sistema de build.

Quando o banco de dados for criado com êxito, haverá um novo diretório no caminho especificado no comando. Se você usou a opção --db-cluster para criar mais de um banco de dados, um subdiretório será criado para cada linguagem. Cada diretório de banco de dados do CodeQL contém vários subdiretórios, incluindo os dados relacionais (necessários para análise) e um arquivo de origem. Uma cópia dos arquivos de origem feita durante a criação do banco de dados, que é usado para exibir resultados de análise.

Como criar bancos de dados para linguagens não compiladas

A CodeQL CLI inclui extratores para criar bancos de dados para as linguagens não compiladas JavaScript (e TypeScript), Python e Ruby. Esses extratores são invocados automaticamente quando você especifica JavaScript, Python ou Ruby como a opção --language ao executar database create. Ao criar bancos de dados para essas linguagens, você precisa garantir que todas as dependências adicionais estejam disponíveis.

JavaScript e TypeScript

A criação de bancos de dados para JavaScript não requer dependências adicionais, mas se o projeto incluir arquivos TypeScript, você precisará instalar o Node.js 6.x ou posterior. Na linha de comando, você pode especificar --language=javascript para extrair arquivos JavaScript e TypeScript:

codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database

Aqui, especificamos um caminho --source-root, que é o local em que a criação do banco de dados é executada, mas não é necessariamente a raiz de check-out da base de código.

Por padrão, os arquivos nos diretórios node_modules e bower_components não são extraídos.

Python

Ao criar bancos de dados para Python, você precisa:

• Ter o Python 3 instalado e disponível para o extrator do CodeQL.
• Ter a versão do Python usada pelo código instalada.
• Ter acesso ao sistema de gerenciamento de empacotamento pip e poder instalar todos os pacotes dos quais a base de código depende.
• Ter instalado o módulo pip virtualenv.

Na linha de comando, você precisa especificar --language=python. Por exemplo:

codeql database create --language=python <output-folder>/python-database

Isso executa o subcomando database create da raiz de check-out do código, gerando um novo banco de dados Python em <output-folder>/python-database.

Ruby

A criação de bancos de dados para Ruby não requer dependências adicionais. Na linha de comando, você precisa especificar --language=ruby. Por exemplo:

codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database

Aqui, especificamos um caminho --source-root, que é o local em que a criação do banco de dados é executada, mas não é necessariamente a raiz de check-out da base de código.

Como criar bancos de dados para linguagens compiladas

Para linguagens compiladas, o CodeQL precisa invocar o sistema de build necessário para gerar um banco de dados, portanto, o método de build precisa estar disponível para a CLI.

Como detectar o sistema de build

A CodeQL CLI inclui construtores automáticos para código C/C++, C#, Go e Java. Os construtores automáticos do CodeQL permitem que você crie projetos para linguagens compiladas sem especificar comandos de build. Quando um construtor automático é invocado, o CodeQL examina a origem para obter evidências de um sistema de build e tenta executar o conjunto ideal de comandos necessários para extrair um banco de dados.

Um construtor automático é invocado automaticamente quando você executa codeql database create para uma --language compilada sem incluir uma opção --command. Por exemplo, para uma base de código Java, bastaria executar:

codeql database create --language=java <output-folder>/java-database

Se uma base de código usa um sistema de build padrão, a dependência de um construtor automático geralmente é a maneira mais simples de criar um banco de dados. Para fontes que exigem etapas de build não padrão, talvez seja necessário definir explicitamente cada etapa na linha de comando.

Como especificar comandos de build

Os exemplos a seguir foram projetados para dar uma ideia de alguns dos comandos de build que você pode especificar para linguagens compiladas.

• Projeto C/C++ criado usando make:

  codeql database create cpp-database --language=cpp --command=make
  

• Projeto C# criado usando dotnet build:

  É bom adicionar /t:rebuild para garantir que todo o código seja criado ou fazer um dotnet clean anterior (o código que não foi criado não será incluído no banco de dados do CodeQL):

  codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
  

• Projeto Go criado usando a variável de ambiente CODEQL_EXTRACTOR_GO_BUILD_TRACING=on:

  CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go
  

• Projeto Go criado usando um script de build personalizado:

  codeql database create go-database --language=go --command='./scripts/build.sh'
  

• Projeto Java criado usando o Gradle:

  # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL:
  codeql database create java-database --language=java --command='gradle --no-daemon clean test'
  

• Projeto Java criado usando o Maven:

  codeql database create java-database --language=java --command='mvn clean install'
  

• Projeto Java criado usando o Ant:

  codeql database create java-database --language=java --command='ant -f build.xml'
  

• Projeto criado usando o Bazel:

  # Navigate to the Bazel workspace.
  
  # Before building, remove cached objects
  # and stop all running Bazel server processes.
  bazel clean --expunge
  
  # Build using the following Bazel flags, to help CodeQL detect the build:
  # `--spawn_strategy=local`: build locally, instead of using a distributed build
  # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code
  # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache
  codeql database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results //path/to/package:target'
  
  # After building, stop all running Bazel server processes.
  # This ensures future build commands start in a clean Bazel server process
  # without CodeQL attached.
  bazel shutdown
  

• Projeto criado usando um script de build personalizado:

  codeql database create new-database --language=<language> --command='./scripts/build.sh'
  

Esse comando executa um script personalizado que contém todos os comandos necessários para compilar o projeto.

Como usar o rastreamento de build indireto

Se os construtores automáticos da CodeQL CLI para linguagens compiladas não funcionarem com seu fluxo de trabalho de CI e você não puder encapsular invocações de comandos de build com codeql database trace-command, use o rastreamento de build indireto para criar um banco de dados do CodeQL. Para usar o rastreamento de build indireto, o sistema de CI precisa ser capaz de definir variáveis de ambiente personalizadas para cada ação de build.

Para criar um banco de dados do CodeQL com rastreamento de build indireto, execute o seguinte comando na raiz de check-out do projeto:

codeql database init ... --begin-tracing <database>

É preciso especificar:

• <database>: é um caminho para o novo banco de dados a ser criado. Esse diretório será criado quando você executar o comando. Não é possível especificar um diretório existente.
• --begin-tracing: cria scripts que podem ser usados para configurar um ambiente no qual os comandos de build serão rastreados.

Você pode especificar outras opções para o comando codeql database init como de costume.

O comando codeql database init vai gerar uma mensagem:

Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.

Based on your operating system, we recommend you run: ...

O comando codeql database init cria <database>/temp/tracingEnvironment com arquivos que contêm variáveis de ambiente e valores que permitirão que o CodeQL rastreie uma sequência de etapas de build. Esses arquivos são chamados de start-tracing.{json,sh,bat,ps1}. Use um desses arquivos com o mecanismo do sistema de CI para definir variáveis de ambiente de etapas futuras. Você pode:

• Ler o arquivo JSON, processá-lo e imprimir variáveis de ambiente no formato esperado pelo sistema de CI. Por exemplo, o Azure DevOps espera echo "##vso[task.setvariable variable=NAME]VALUE".
• Ou, se o sistema de CI persistir o ambiente, crie o script start-tracing apropriado para definir as variáveis do CodeQL no ambiente de shell do sistema de CI.

Crie o código. Opcionalmente, remova a definição das variáveis de ambiente usando um script end-tracing.{json,sh,bat,ps1} do diretório em que os scripts start-tracing são armazenados e depois execute o comando codeql database finalize <database>.

Depois de criar um banco de dados do CodeQL usando o rastreamento de build indireto, você pode trabalhar com ele como qualquer outro banco de dados do CodeQL. Por exemplo, analise o banco de dados e carregue os resultados no GitHub ao usar a verificação de código.

Exemplo de criação de um banco de dados do CodeQL usando o rastreamento de build indireto

O exemplo a seguir mostra como você pode usar o rastreamento de build indireto em um pipeline do Azure DevOps para criar um banco de dados do CodeQL:

steps:
    # Download the CodeQL CLI and query packs...
    # Check out the repository ...

    # Run any pre-build tasks, for example, restore NuGet dependencies...

    # Initialize the CodeQL database.
    # In this example, the CodeQL CLI has been downloaded and placed on the PATH.
    - task: CmdLine@1
       displayName: Initialize CodeQL database
      inputs:
          # Assumes the source code is checked out to the current working directory.
          # Creates a database at `<current working directory>/db`.
          # Running on Windows, so specifies a trace process level.
          script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"

    # Read the generated environment variables and values,
    # and set them so they are available for subsequent commands
    # in the build pipeline. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Set CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    # Execute the pre-defined build step. Note the `msbuildArgs` variable.
    - task: VSBuild@1
        inputs:
          solution: '**/*.sln'
          msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
          platform: Any CPU
          configuration: Release
          # Execute a clean build, in order to remove any existing build artifacts prior to the build.
          clean: True
       displayName: Visual Studio Build

    # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Clear CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    - task: CmdLine@2
       displayName: Finalize CodeQL database
       inputs:
          script: 'codeql database finalize db'

    # Other tasks go here, for example:
    # `codeql database analyze`
    # then `codeql github upload-results` ...

Como baixar bancos de dados do GitHub.com

O GitHub armazena bancos de dados do CodeQL para mais de 200 mil repositórios no GitHub.com, que você pode baixar usando a API REST. A lista de repositórios está sempre crescendo e evoluindo para garantir que ele inclua as bases de código mais interessantes para pesquisa de segurança.

Você pode verificar se um repositório tem bancos de dados do CodeQL disponíveis para download usando o ponto de extremidade /repos/<owner>/<repo>/code-scanning/codeql/databases. Por exemplo, para verificar os bancos de dados do CodeQL usando o GitHub CLI, você executaria:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/

Esse comando retorna informações sobre todos os bancos de dados do CodeQL que estão disponíveis para um repositório, incluindo a linguagem que o banco de dados representa e quando ele foi atualizado pela última vez. Se nenhum banco de dados do CodeQL estiver disponível, a resposta estará vazia.

Ao confirmar que existe um banco de dados do CodeQL para a linguagem do seu interesse, você poderá baixá-lo usando o seguinte comando:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Para obter mais informações, confira a documentação Obter um ponto de extremidade do banco de dados do CodeQL.

Antes de executar uma análise com os dados da CodeQL CLI, você precisa descompactar os bancos de dados.

Leitura adicional

• "Como analisar os projetos no CodeQL para VS Code"