Skip to main content

database init

[プラミング] 空の CodeQL データベースを作成します。

この機能を使用できるユーザーについて

GitHub CodeQL は、インストール時にユーザーごとにライセンスされます。 CodeQL は、ライセンスの制限の下で特定のタスクでのみ使用できます。 詳しくは、「CodeQL CLI について」を参照してください。

GitHub Advanced Security ライセンスがある場合は、CodeQL を使用して、自動分析、継続的インテグレーション、継続的デリバリーを行うことができます。 詳しくは、「GitHub Advanced Security について」を参照してください。

この記事の内容

このコンテンツでは、CodeQL CLI の最新リリースについて説明します。 このリリースについて詳しくは、 https://github.com/github/codeql-cli-binaries/releases をご覧ください。

以前のリリースの、このコマンドで使えるオプションを詳しく確認するには、ターミナルで --help オプションを指定してコマンドを実行してください。

構文

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 データベースを作成します。

まだ生の QL データセットは存在しないが、抽出ステップを実行する準備ができている CodeQL データベースのスケルトン構造を作成します。 このコマンドが完了したら、1 つ以上の codeql database trace-command コマンドを実行し、続いて codeql database finalize を実行して、クエリ用にデータベースを準備します。

(この処理の一部として行われるのは、適切な言語パックの保存先を解決し、それをデータベース メタデータに格納することです。これにより、各抽出コマンドで再実行する必要はありません。 抽出操作の途中でエクストラクターを切り替えることは、いずれにしても無効です。)

[オプション]

主なオプション

<database>

[必須] 作成する CodeQL データベースのパス。 このディレクトリは作成され、既に存在していては "なりません" (ただし、その親は必要です)。__

--db-cluster オプションを指定すると、これはデータベース自体ではなく、同じソース ルートから構築された複数の言語のデータベースを "含む" ディレクトリになります。__

このディレクトリは、構築プロセスが干渉する場所に存在しないことが重要です。 たとえば、Maven プロジェクトの target ディレクトリは適切な選択肢ではありません。

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

[必須] ソース コードのルート ディレクトリ。 多くの場合、これはチェックアウト ルートになります。 その中のファイルは、このデータベースのプライマリ ソース ファイルと見なされます。 一部の出力形式では、このディレクトリからの相対パスによってファイルが参照されます。

--[no-]overwrite

[詳細設定] データベースが既に存在する場合、失敗するのではなく、データベースを削除し、このコマンドを続行します。 このオプションは、データベース ディレクトリ全体を再帰的に削除する可能性があるため、注意して使用する必要があります。

--codescanning-config=<file>

[詳細設定] CodeQL データベースの作成方法と後の手順で実行するクエリについてのオプションを指定した Code Scanning 構成ファイルを読み取ります。 この構成ファイルの形式について詳しくは、「をカスタマイズして、コード スキャンの詳細設定を行う」を参照してください。 後の手順でこのファイルからクエリを実行するには、他のクエリを指定せずに codeql database analyze を呼び出します。

--[no-]db-cluster

1 つのデータベースを作成する代わりに、異なる言語のデータベースからなる "クラスター" を作成します。そのそれぞれは、コマンド ラインで指定したディレクトリのサブディレクトリです。

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

新しいデータベースが分析に使用される言語。

検索パスで見つかったプラグ可能な言語エクストラクターの一覧を取得するには、codeql resolve languages を使用します。

--db-cluster オプションを指定している場合は、これを複数回使用できます。または、値をコンマ区切りの言語のリストにすることができます。

このオプションを省略すると、分析対象のソース ルートが GitHub リポジトリのチェックアウトである場合は、CodeQL CLI で GitHub API が呼び出され、分析する言語を自動的に決定することが試みられます。 これを行うには、環境変数 GITHUB_TOKEN で、または --github-auth-stdin オプションを使用して標準入力経由で GitHub PAT トークンを指定する必要があることに注意してください。

--build-mode=<mode>

データベースの作成に使用されるビルド モード。

分析する言語に基づいてビルド モードを選択します。

none: ソース ルートを構築せずにデータベースが作成されます。 JavaScript/TypeScript、Python、Ruby で使用できます。

autobuild: ソース ルートを自動的にビルドしようとすると、データベースが作成されます。 C/C++、C#、Go、Java/Kotlin、Swift で使用できます。

manual: データベースは、手動で指定したビルド コマンドを使用してソース ルートをビルドすることによって作成されます。 C/C++、C#、Go、Java/Kotlin、Swift で使用できます。

--command を使用してデータベースを作成する場合、'--build-mode none' を追加で指定する必要はありません。

v2.16.4 以降で使用できます。

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

[詳細設定] 指定したソース ルートが存在しない場合でも先に進みます。

--[no-]begin-tracing

[詳細設定] "間接ビルド トレース" を設定するために使用できるスクリプトをいくつか作成します。これにより、明示的なビルド コマンドが使用できない場合に既存のビルド ワークフローへの統合が可能になります。 どのような場合に、どのような方法でこの機能を使用するかについては、「CodeQL 分析のためのコードの準備」のドキュメントを参照してください。

ベースライン計算のオプション

--[no-]calculate-baseline

[詳細設定] 分析対象のコードに関するベースライン情報を計算し、データベースに追加します。 既定では、これはソース ルートがファイルシステムのルートである場合を除き、有効になります。 このフラグを使用して、この動作を無効にするか、ファイルシステムのルートでも強制的に有効にすることができます。

--[no-]sublanguage-file-coverage

[GitHub.com および GitHub Enterprise Server v3.12.0 以降のみ] サブ言語のファイル カバレッジ情報を使用します。 これにより、C と C++、Java と Kotlin、JavaScript、TypeScript などの CodeQL エクストラクターを共有する言語の個別のファイル カバレッジ情報を計算、表示、エクスポートします。

v2.15.2 以降で使用できます。

エクストラクターの選択オプション

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

エクストラクター パックが見つかる可能性があるディレクトリのリスト。 ディレクトリは、エクストラクター パック自体、またはエクストラクターを直接サブディレクトリとして含むディレクトリのいずれかです。

パスに複数のディレクトリ ツリーが含まれている場合、それらの順序によってそれらの間の優先順位が定義されます。ターゲット言語が複数のディレクトリ ツリーで一致する場合、最初に指定されたものが優先されます。

CodeQL ツールチェーン自体にバンドルされているエクストラクターは常に検出されますが、個々に配布されたエクストラクターを使用する必要がある場合は、このオプションを指定する必要があります (または、より良い方法として、ユーザーごとの構成ファイルで --search-path を設定します)。

(注: Windows では、パスの区切り記号は ; です)。

GitHub API を呼び出して言語を自動検出する方法を構成するためのオプション。

-a, --github-auth-stdin

標準入力を使用して、GitHub Apps トークンまたは個人用アクセス トークンを受け入れます。

これにより、GITHUB_TOKEN 環境変数がオーバーライドされます。

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

使用する GitHub インスタンスの URL。 省略した場合、CLI でチェックアウト パスからこれを自動検出することが試みられます。これができない場合は、既定で https://github.com/ になります

パッケージ マネージャーを構成するためのオプション。

--registries-auth-stdin

<registry_url>=<token> ペアのコンマ区切りリストを渡すことで、GitHub Enterprise Server コンテナー レジストリに対して認証を行います。

たとえば、https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 を渡して、 2 つの GitHub Enterprise Server インスタンスに対して認証を行うことができます。

これを使って、CODEQL_REGISTRIES_AUTH および GITHUB_TOKEN 環境変数をオーバーライドします。 github.com コンテナー レジストリに対する認証のみが必要な場合は、代わりに、より単純な --github-auth-stdin オプションを使用して認証できます。

Windows トレースを構成するためのオプション

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

[Windows のみ] トレースを初期化するときに、名前がこの引数と一致する CodeQL CLI の親プロセスにトレーサーを挿入します。 この名前の親プロセスが複数ある場合は、プロセス ツリー内で最も下位のプロセスが選択されます。 このオプションは --trace-process-level をオーバーライドするため、両方を渡した場合は、このオプションのみが使用されます。

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

[Windows のみ] トレース初期化時、現在のプロセスからこれだけ上位にトレーサーを挿入します。0 は、CodeQL CLI を呼び出すプロセスに対応します。 引数が渡されない場合の CLI のデフォルトの動作は、GitHub Actions と Azure Pipelines のいくつかの特殊なケースを使用して、呼び出しプロセスの親に挿入します。

間接ビルド トレースを構成するためのオプション

--no-tracing

[詳細設定] 指定したコマンドをトレースしません。代わりに、必要なすべてのデータを直接生成するために使用します。

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

[詳細設定] トレーサー構成ファイルのパス。 ビルド トレーサーの動作を変更するために使用できます。 ビルド コマンドの一部として実行されるコンパイラ プロセスを選び、他のツールの実行をトリガーするために使用できます。 エクストラクターにより、ほとんどの状況で機能する既定のトレーサー構成ファイルが提供されます。

抽出の動作を制御するオプション: 間接トレース環境にのみ適用

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

CodeQL エクストラクターのオプションを設定します。 extractor-option-name は、extractor_name.group1.group2.option_name または group1.group2.option_name という形式にする必要があります。 extractor_option_name がエクストラクター名で始まる場合、指定したエクストラクターはオプション group1.group2.option_name を宣言する必要があります。 それ以外の場合、オプション group1.group2.option_name を宣言するエクストラクターにはオプションが設定されます。 value は、改行を含まない任意の文字列にすることができます。

このコマンド ライン オプションを繰り返し使用して、複数のエクストラクター オプションを設定できます。 同じエクストラクター オプションに複数の値を指定した場合、動作は、エクストラクター オプションで想定されている型によって異なります。 文字列オプションでは、指定した最後の値が使用されます。 配列オプションでは、指定したすべての値が順番に使用されます。 このコマンド ライン オプションを使用して指定したエクストラクター オプションは、--extractor-options-file で指定したエクストラクター オプションの後に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。 ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクター オプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

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

エクストラクター オプションのバンドル ファイルを指定します。 エクストラクター オプション バンドル ファイルは、エクストラクター オプションを設定する JSON ファイル (拡張子 .json) または YAML ファイル (拡張子 .yaml または .yml) です。 ファイルには最上位レベルのマップ キー 'extractor' があり、その下にエクストラクター名が第 2 レベルのマップ キーとして含まれている必要があります。 それ以降のレベルのマップは入れ子になったエクストラクター グループを表し、文字列と配列のオプションは、文字列と配列の値を持つマップ エントリです。

エクストラクター オプション バンドル ファイルは、指定した順序で読み取られます。 異なるエクストラクター オプション バンドル ファイルで同じエクストラクター オプションを指定した場合、その動作はエクストラクター オプションで想定されている型によって異なります。 文字列オプションでは、指定した最後の値が使用されます。 配列オプションでは、指定したすべての値が順番に使用されます。 このコマンド ライン オプションを使用して指定したエクストラクター オプションは、--extractor-option で指定したエクストラクター オプションよりも前に処理されます。

codeql database init または codeql database begin-tracing に渡した場合、オプションは間接トレース環境にのみ適用されます。 ワークフローで codeql database trace-command の呼び出しも行う場合は、必要に応じてオプションも渡す必要があります。

各エクストラクターによって宣言されたオプションの一覧を表示する方法など、CodeQL エクストラクター オプションについて詳しくは、https://codeql.github.com/docs/codeql-cli/extractor-options を参照してください。

共通オプション

-h, --help

このヘルプ テキストを表示します。

-J=<opt>

[詳細設定] コマンドを実行している JVM にオプションを指定します

(スペースを含むオプションは正しく処理されないことに注意してください)。

-v, --verbose

出力される進行状況メッセージの数を段階的に増やします。

-q, --quiet

出力される進行状況メッセージの数を段階的に減らします。

--verbosity=<level>

[詳細設定] 詳細レベルを、errors、warnings、progress、progress+、progress++、progress+++ のいずれかに明示的に設定します。 -v-q がオーバーライドされます。

--logdir=<dir>

[詳細設定] タイムスタンプと実行中のサブコマンドの名前を含む生成された名前を使用して、指定されたディレクトリ内の 1 つまたは複数のファイルに詳細なログを書き込みます

(完全に制御できる名前でログ ファイルを書き込むには、代わりに --log-to-stderr を指定し、必要に応じて stderr をリダイレクトします)。

--common-caches=<dir>

[[詳細設定] ダウンロードした QL パックやコンパイル済みクエリ プランなど、CLI の複数の実行間に保持される、ディスク上でキャッシュされたデータの場所を制御します。 明示的に設定されない場合、既定ではユーザーのホーム ディレクトリに名前が付けられた .codeql ディレクトリになります。まだ存在しない場合は作成されます。

v2.15.2 以降で使用できます。