database init

Este conteúdo descreve a versão mais recente do CodeQL CLI. Para obter mais informações sobre essa versão, confira https://github.com/github/codeql-cli-binaries/releases.

Para ver os detalhes das opções disponíveis para esse comando em uma versão anterior, execute o comando com a opção --help no terminal.

Sinopse

Shell

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database>

Descrição

[Conexão] Crie um banco de dados CodeQL vazio.

Crie uma estrutura de esqueleto para um banco de dados CodeQL que ainda não tem um conjunto de dados QL bruto, mas está pronto para executar etapas do extrator. Após a conclusão desse comando, execute um ou mais comandos codeql database trace-command seguidos de codeql database finalize para preparar o banco de dados para consulta.

(Parte do que isso faz é resolver o local do pacote de linguagens apropriado e armazená-lo nos metadados do banco de dados, de modo que ele não precise ser refeito em cada comando de extração. De qualquer maneira, não é válido alternar extratores no meio de uma operação de extração.)

Opções

Opções principais

`<database>`

[Obrigatório] Caminho para o banco de dados CodeQL a ser criado. Esse diretório será criado e não deve já existir (ao contrário do pai, que precisa existir).

Se a opção --db-cluster for fornecida, isso não será um banco de dados propriamente dito, mas um diretório que conterá bancos de dados para várias linguagens criadas com base na mesma raiz de origem.

É importante que esse diretório não esteja em um local com o qual o processo de build vai interferir. Por exemplo, o diretório target de um projeto Maven não será uma opção adequada.

`-s, --source-root=<dir>`

[Obrigatório] O diretório do código-fonte raiz. Em muitos casos, essa será a raiz do check-out. Os arquivos contidos nele são considerados os arquivos de origem primários desse banco de dados. Em alguns formatos de saída, os arquivos serão referenciados pelo caminho relativo desse diretório.

`--[no-]overwrite`

[Avançado] Se o banco de dados já existir, exclua-o e prossiga com esse comando em vez de causar uma falha. Se o diretório existir, mas não se parecer com um banco de dados, um erro será gerado.

`--[no-]force-overwrite`

[Avançado] Se o banco de dados já existir, exclua-o mesmo que não se pareça com um banco de dados e prossiga com esse comando em vez de causar uma falha. Essa opção deve ser usada com cuidado, pois pode excluir recursivamente todo o diretório do banco de dados.

`--codescanning-config=<file>`

[Avançado] Leia um arquivo de configuração da verificação de código que especifica opções sobre como criar os bancos de dados CodeQL e quais consultas serão executadas nas etapas posteriores. Para obter mais detalhes sobre o formato desse arquivo de configuração, veja Personalizando a configuração avançada para varredura de código. Para executar consultas por meio desse arquivo em uma etapa posterior, invoque codeql database analyze sem nenhuma outra consulta especificada.

`--[no-]db-cluster`

Em vez de criar um banco de dados individual, crie um "cluster" de bancos de dados para linguagens diferentes, cada um deles um subdiretório do diretório fornecido na linha de comando.

`-l, --language=<lang>[,<lang>...]`

A linguagem que o novo banco de dados usará para a análise.

Use codeql resolve languages para obter uma lista dos extratores de linguagem conectáveis encontrados no caminho de pesquisa.

Quando a opção --db-cluster é fornecida, isso pode aparecer várias vezes ou o valor pode ser uma lista separada por vírgula das linguagens.

Se essa opção for omitida e a raiz de origem que estiver sendo analisada for um check-out de um repositório GitHub, a CLI do CodeQL fará uma chamada à API do GitHub para tentar determinar automaticamente as linguagens que serão analisadas. Observe que, para fazer isso, um token PAT do GitHub precisa ser fornecido na variável de ambiente GITHUB_TOKEN ou por meio da entrada padrão com a opção --github-auth-stdin.

`--build-mode=<mode>`

O modo de compilação que será usado para criar o banco de dados.

Escolha seu modo de compilação com base na linguagem que você está analisando:

none: O banco de dados será criado sem criar a raiz do código-fonte. Disponível para C#, Java, JavaScript/TypeScript, Python e Ruby.

autobuild: O banco de dados será criado ao tentar criar automaticamente a raiz do código-fonte. Disponível para C/C++, C#, Go, Java/Kotlin e Swift.

manual: O banco de dados será criado ao compilar a raiz de origem com o uso de um comando de compilação especificado manualmente. Disponível para C/C++, C#, Go, Java/Kotlin e Swift.

Ao criar um banco de dados com --command, não há necessidade de especificar adicionalmente '--build-mode manual'.

Disponível desde v2.16.4.

`--[no-]allow-missing-source-root`

[Avançado] Prossiga mesmo se a raiz de origem especificada não existir.

`--[no-]begin-tracing`

[Avançado] Crie alguns scripts que podem ser usados para configurar o "rastreamento de build indireto", que permite a integração aos fluxos de trabalho de build existentes quando um comando de build explícito não está disponível. Para obter informações sobre quando e como usar esse recurso, confira nossa documentação em Como preparar seu código para a análise do CodeQL.

Opções de cálculo da linha de base

`--[no-]calculate-baseline`

[Avançado] Calcule as informações de linha de base sobre o código que está sendo analisado e adicione-o ao banco de dados. Por padrão, isso é habilitado, a menos que a raiz de origem seja a raiz de um sistema de arquivos. Esse sinalizador pode ser usado para desabilitar ou forçar o comportamento a ser habilitado mesmo na raiz do sistema de arquivos.

`--[no-]sublanguage-file-coverage`

[Somente para GitHub.com e GitHub Enterprise Server v3.12.0+] Use informações de cobertura de arquivo de sub-linguagem. Isso calcula, exibe e exporta informações de cobertura de arquivos separadas para linguagens que compartilham um extrator CodeQL como C e C++, Java e Kotlin e JavaScript e TypeScript.

Disponível desde v2.15.2.

Opções de seleção do extrator

`--search-path=<dir>[:<dir>...]`

Uma lista de diretórios nos quais os pacotes de extratores podem ser encontrados. Os diretórios podem ser os próprios pacotes extratores ou diretórios que contenham extratores como subdiretórios imediatos.

Se o caminho contiver várias árvores de diretório, a ordem delas definirá a precedência entre elas: se for encontrada uma correspondência da linguagem de destino em mais de uma das árvores de diretório, a primeira fornecida vencerá.

Os extratores empacotados com a própria cadeia de ferramentas CodeQL sempre serão encontrados, mas se você precisar usar extratores distribuídos separadamente, forneça essa opção (ou, melhor ainda, configure --search-path em um arquivo de configuração por usuário).

(Observação: no Windows, o separador de caminho é ;).

Opções para configurar como chamar a API do GitHub para detectar linguagens automaticamente.

`-a, --github-auth-stdin`

Aceite um token do GitHub Apps ou um token de acesso pessoal por meio da entrada padrão.

Isso substitui a variável de ambiente GITHUB_TOKEN.

`-g, --github-url=<url>`

URL da instância do GitHub a ser usada. Se isso for omitido, a CLI tentará fazer a detecção automática dela por meio do caminho do check-out e, se isso não for possível, usará https://github.com/ como padrão

Opções para configurar o gerenciador de pacotes.

`--registries-auth-stdin`

Autentique-se nos registros de contêiner do GitHub Enterprise Server transmitindo uma lista separada por vírgula de pares <registry_url>=<token>.

Por exemplo, você pode transmitir https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 para se autenticar em duas instâncias do GitHub Enterprise Server.

Isso substitui as variáveis de ambiente CODEQL_REGISTRIES_AUTH e GITHUB_TOKEN. Se você só precisar se autenticar no registro de contêiner do github.com, poderá se autenticar usando a opção --github-auth-stdin mais simples.

Opções para configurar o rastreamento do Windows

`--trace-process-name=<process-name>`

[Somente Windows] Ao inicializar o rastreamento, injete o rastreador em um processo pai da CLI do CodeQL cujo nome corresponda a esse argumento. Se mais de um processo pai tiver esse nome, o mais baixo na árvore de processo será selecionado. Esta opção substitui --trace-process-level, ou seja, se ambas forem passadas, somente essa opção será usada.

`--trace-process-level=<process-level>`

[Somente Windows] Ao inicializar o rastreamento, injete o rastreador muitos pais acima do processo atual, com 0 correspondendo ao processo que está invocando a CLI do CodeQL. O comportamento padrão da CLI se nenhum argumento for passado é injetar no pai do processo que iniciou a chamada, com alguns casos especiais para GitHub Actions e Azure Pipelines.

Opções para configurar o rastreamento de build indireto

`--no-tracing`

[Avançado] Não rastreie o comando especificado. mas dependa dele para produzir todos os dados necessários diretamente.

`--extra-tracing-config=<tracing-config.lua>`

[Avançado] O caminho para um arquivo de configuração do rastreador. Ele pode ser usado para modificar o comportamento do rastreador de build. Ele pode ser usado para escolher processos do compilador executados como parte do comando de build e disparar a execução de outras ferramentas. Os extratores fornecerão arquivos de configuração do rastreador padrão que devem funcionar na maioria das situações.

Opções para controlar o comportamento do extrator: somente ser aplicado ao ambiente de rastreamento indireto

`-O, --extractor-option=<extractor-option-name=value>`

Defina as opções para os extratores do CodeQL. extractor-option-name deve ter o formato extractor_name.group1.group2.option_name ou group1.group2.option_name. Se extractor_option_name começar com o nome de um extrator, o extrator indicado precisará declarar a opção group1.group2.option_name. Caso contrário, qualquer extrator que declare a opção group1.group2.option_name terá a opção definida. value pode ser qualquer cadeia de caracteres que não contenha uma nova linha.

Use essa opção de linha de comando repetidamente para definir várias opções de extratores. Se você fornecer vários valores para a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas após as opções de extratores fornecidas por meio de --extractor-options-file.

Quando transmitido para codeql database init ou codeql database begin-tracing, as opções serão aplicadas somente ao ambiente de rastreamento indireto. Se o fluxo de trabalho também fizer chamadas a codeql database trace-command, as opções também precisarão ser transmitidas para ele, se desejado.

Confira https://codeql.github.com/docs/codeql-cli/extractor-options para obter mais informações sobre as opções do extrator do CodeQL, incluindo como listar as opções declaradas pelos extratores.

`--extractor-options-file=<extractor-options-bundle-file>`

Especifique os arquivos de pacote de opções de extratores. Um arquivo de pacote de opções de extratores é um arquivo JSON (extensão .json) ou um arquivo YAML (extensão .yaml ou .yml) que define as opções de extratores. O arquivo precisa ter a chave de mapa de nível superior 'extractor' e, abaixo dela, os nomes de extratores como chaves de mapa de segundo nível. Outros níveis de mapas representam grupos de extratores aninhados, e as opções de cadeia de caracteres e matriz são entradas de mapa com valores de cadeia de caracteres e matriz.

Os arquivos do pacote de opções de extratores são lidos na ordem em que são especificados. Se diferentes arquivos do pacote de opções de extratores especificarem a mesma opção de extrator, o comportamento dependerá do tipo esperado pela opção de extrator. As opções de cadeia de caracteres usarão o último valor fornecido. As opções de matriz usarão todos os valores fornecidos, em ordem. As opções de extratores especificadas com essa opção de linha de comando são processadas antes das opções de extratores fornecidas por meio de --extractor-option.

Opções comuns

`-h, --help`

Mostre este texto de ajuda.

`-J=<opt>`

[Avançado] Forneça a opção para a JVM que executa o comando.

(Use-a com cautela, pois as opções que contêm espaços não serão tratadas corretamente.)

`-v, --verbose`

Aumente incrementalmente o número de mensagens de progresso impressas.

`-q, --quiet`

Diminua incrementalmente o número de mensagens de progresso impressas.

`--verbosity=<level>`

[Avançado] Defina explicitamente o nível de detalhamento como erros, avisos, progresso, progresso+, progresso++ ou progresso+++. Substitui -v e -q.

`--logdir=<dir>`

[Avançado] Escreva logs detalhados em um ou mais arquivos no diretório fornecido, com nomes gerados que incluem carimbos de data/hora e o nome do subcomando em execução.

(Para gravar um arquivo de log com um nome sobre o qual você tem controle completo, forneça --log-to-stderr e redirecione stderr conforme desejado.)

`--common-caches=<dir>`

[Avançado] Controle a localização dos dados armazenados em cache no disco que persistirão entre várias execuções da CLI, como pacotes QL baixados e planos de consulta compilada. Se não for definido explicitamente, o padrão corresponde a um diretório intitulado .codeql no diretório inicial do usuário; que será criado se ainda não existir.

Disponível desde v2.15.2.

Quem pode usar esse recurso?

Neste artigo