注: この機能を使用するには、サイト管理者が の code scanning を有効にする必要があります。 詳しくは、「アプライアンスでの code scanning の構成」をご覧く� さい。
注: この記事では、GitHub Enterprise Server のリリース時に使用可能なバージョンの CodeQL CLIに存在する機能について説明します。 Enterprise でより新しいバージョンの CodeQL CLI を使用している� �合は、代わりに GitHub Enterprise Cloud のドキュメントを参照してく� さい。
CodeQL CLIでのCode scanningの結果の生成について
CIシステ� 内のサーバーでCodeQL CLIを利用できるようにして、確実にGitHub Enterprise Serverで認証できるようにしたなら、データを生成する準備ができています。
結果を生成してGitHub Enterprise Serverにアップロードするには、3つの異なるコマンドを使います。
database create
では、リポジトリのサポートされている各プログラミング言語の階層構� を表すために CodeQL データベースを作成します。database analyze
では、クエリを実行して各 CodeQL データベースを分析し、結果を SARIF ファイルにまとめます。github upload-results
では、結果の SARIF ファイルを GitHub Enterprise Server にアップロードします。そこで結果はブランチまたは pull request と照合され、code scanning アラートとして表示されます。
--help
注: GitHub Enterprise Server の結果の code scanning として表示する SARIF データをアップロードすることは、GitHub Advanced Security が有効にされた組織が所有するリポジトリ。 詳細については、「リポジトリのセキュリティと分析の設定を管理する」を参照してく� さい。
分析するCodeQLデータベースの作成
-
分析するコードをチェックアウトします。
- ブランチの� �合は、分析するブランチのヘッドをチェックアウトします。
- pull request の� �合は、pull request のヘッド コミットをチェックアウトするか、GitHub で生成された pull request のマージ コミットをチェックアウトします。
-
コードベースの環境を設定し、依存関係が使用可能であることを確認します。 詳細については、CodeQL CLI のドキュメントの「コンパイルされていない言語のデータベースの作成」および 「コンパイル済み言語のデータベースの作成」を参照してく� さい。
-
コードベースのビルド コマンドを見つけます (ある� �合)。 通常、これは CI システ� の構成ファイルで使用できます。
-
リポジトリのチェックアウト ルートから
codeql database create
を実行し、コードベースをビルドします。# Single supported language - create one CodeQL database codeql database create <database> --command<build> --language=<language-identifier> # Multiple supported languages - create one CodeQL database per language codeql database create <database> --command<build> \ --db-cluster --language=<language-identifier>,<language-identifier>
注: コンテナー化されたビルドを使用する� �合は、ビルド タスクが行われるコンテナーで CodeQL CLI を実行する必要があります。
オプション | 必� � | 使用法 |
---|---|---|
<database> | CodeQLデータベースを作成するディレクトリの名前と� �所を指定します。 既存のディレクトリを上書きしようとすると、コマンドは失敗します。 また --db-cluster を指定した� �合は、これが親ディレクトリであり、分析される言語ごとにサブディレクトリが作成されます。 | |
--language | データベースを作成する言語の識別子 (cpp`、`csharp`、`go`、`java`、`javascript`、 と `python のいずれか) を指定します (TypeScript コードを分析するには javascript を使用します)。 --db-cluster | |
--command | 推奨。 コードベースのビルド プロセスを呼び出すビルド コマンドまたはスクリプトを指定するために使用します。 コマンドは現在のフォルダーから、または定義されている� �合は --source-root | |
--db-cluster | 省略可能。 --language | |
--no-run-unnecessary-builds | 推奨。 CodeQL CLIがビルドをモニターする必要がない� �合に、言語のビルドコマンドを抑制するために使います(たとえばPythonやJavaScript/TypeScript)。 | |
--source-root | 省略可能。 リポジトリのチェックアウト ルートの外部で CLI を実行する� �合に使用します。 既定では、database create コマンドで現在のディレクトリがソース ファイルのルート ディレクトリであると見なされます。別の� �所を指定するためにこのオプションを使用します。 | |
--codescanning-config | 省略可能 (詳細) CodeQL データベースの作成方法と、後の手� �で実行するクエリを指定する構成ファイルがある� �合に使用します。 詳しくは、「カスタ� 構成ファイルの使用」および「database create」を参照してく� さい。 |
詳細については、CodeQL CLI のドキュメントの「CodeQL データベースの作成」を参照してく� さい。
単一言語の例
この例では、/checkouts/example-repo
でチェックアウトされたリポジトリの CodeQL データベースを作成します。 JavaScript 抽出機能を使用して、リポジトリに JavaScript および TypeScript コードの階層表現を作成します。 結果のデータベースは /codeql-dbs/example-repo
に� �納されます。
$ codeql database create /codeql-dbs/example-repo --language=javascript \
--source-root /checkouts/example-repo
> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.
複数言語の例
この例では、/checkouts/example-repo-multi
でチェックアウトされたリポジトリの CodeQL データベースを 2 つ作成します。 イベント プロセッサで使用されるものは次のとおりです。
--db-cluster
: 複数の言語の分析を要求します。--language
: データベースを作成する言語を指定します。--command
: コードベースのビルド コマンド (ここではmake
) をツールに伝えます。--no-run-unnecessary-builds
: 必要のない言語 (Python など) のビルド コマンドをスキップするようにツールに伝えます。
結果のデータベースは、/codeql-dbs/example-repo-multi
の python
および cpp
サブディレクトリに� �納されます。
$ codeql database create /codeql-dbs/example-repo-multi \
--db-cluster --language python,cpp \
--command make --no-run-unnecessary-builds \
--source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$
CodeQLデータベースの分析
- CodeQLデータベースを作成してく� さい(上記参照)。
- データベースに対して
codeql database analyze
を実行し、使用するクエリを指定します。codeql database analyze <database> --format=<format> \ --output=<output> <queries>
注: 1 つのコミットに対して複数の CodeQL データベースを分析する� �合、このコマンドによって生成されるそれぞれの結果セットに対して SARIF カテゴリを指定する必要があります。 結果をGitHub Enterprise Serverにアップロードする際には、code scanningはこのカテゴリを使ってそれぞれの言語に対する結果を別々に保存します。 この操作を忘れた� �合は、各アップロードで前の結果が上書きされます。
codeql database analyze <database> --format=<format> \
--sarif-category=<language-specifier> --output=<output> \
<queries>
オプション | 必� � | 使用法 |
---|---|---|
<database> | 分析するCodeQLデータベースを含むディレクトリのパスを指定します。 | |
<packs,queries> | 実行する CodeQL パックまたはクエリを指定します。 code scanning に使用される標準クエリを実行するには、このパラメーターを省略します。 CodeQL CLI バンドルに含まれている他のクエリ スイートを確認する� �合は、/<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites を参照してく� さい。 独自のクエリ スイートの作成については、CodeQL CLI のドキュメントの「CodeQL クエリ スイートの作成」を参照してく� さい。 | |
--format | コマンドによって生成される結果ファイルの形式を指定します。 GitHub へのアップロードの� �合、これは sarifv2.1.0 である必要があります。 詳細については、「code scanning の SARIF サポート」を参照してく� さい。 | |
--output | SARIF 結果ファイルを保存する� �所を指定します。 | |
--sarif-category | 単一データベースの分析の� �合は省略可能です。 リポジトリ内の単一コミットに対して複数のデータベースを分析する� �合に言語を定義するために必要です。 この分析の SARIF 結果ファイルに含めるカテゴリを指定します。 カテゴリは、同じツールとコミットに対する複数の分析を区別するために使用されますが、異なる言語またはコードの異なる部分で実行されます。 | |
--threads | 任意。 複数のスレッドを使用してクエリを実行する� �合に使用します。 既定値は 1 です。 クエリの実行を高速化するために、より多くのスレッドを指定できます。 スレッドの数を論理プロセッサの数に設定するには、0 を指定します。 | |
--verbose | 省略可能。 データベース作成プロセスから分析プロセスと診断データに関する詳細情� �を取得するために使用します。 |
詳細については、CodeQL CLI のドキュメントの「CodeQL CLI でのデータベースの分析」を参照してく� さい。
基本的な例
この例では、/codeql-dbs/example-repo
で� �納されている CodeQL データベースを分析し、結果を SARIF ファイル (/temp/example-repo-js.sarif
) として保存します。 --sarif-category
を使用して、結果を JavaScript として識別する追� の情� �を SARIF ファイルに含めます。 これは、リポジトリ中の単一のコミットに対して分析するCodeQLデータベースが複数ある� �合に不可� です。
$ codeql database analyze /codeql-dbs/example-repo \
javascript-code-scanning.qls --sarif-category=javascript \
--format=sarifv2.1.0 --output=/temp/example-repo-js.sarif
> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.
GitHub Enterprise Serverへの結果のアップロード
注:
-
SARIF アップロードでは、アップロードごとに最大 5,000 件の結果がサポートされます。 この制限を超える結果はすべて無視されます。 ツールで生成される結果が多すぎる� �合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。
-
SARIF アップロードでサポートされる
gzip
圧縮の SARIF ファイルの最大サイズは、アップロードごとに 10 MB となります。 この制限を超えるアップロードはすべて拒否されます。 含まれる結果が多すぎるために SARIF ファイルが大きくなりすぎた� �合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。
結果を GitHub Enterprise Server にアップロードする前に、以前に作成した GitHub Appまたは personal access token を CodeQL CLI に渡す最善の方法を決める必要があります (「CI システ� での CodeQL CLI のインストール」を参照)。 シークレット ストアの安全な使用に関する CI システ� のガイダンスを確認することをお勧めします。 CodeQL CLIは以下をサポートします。
--github-auth-stdin
オプションを使用し、標準入力を介して CLI にトークンを渡す (推奨)。- 環境変数
GITHUB_TOKEN
にシークレットを保存し、--github-auth-stdin
オプションを含めずに CLI を実行する。
CI サーバーの最も安全で信� �性の高い方法を決定した� �合は、各 SARIF 結果ファイルで codeql github upload-results
を実行し、トークンが環境変数 GITHUB_TOKEN
で使用可能でない限り、--github-auth-stdin
を含めます。
echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
--ref=<ref> --commit=<commit> --sarif=<file> \
--github-url=<URL> --github-auth-stdin
オプション | 必� � | 使用法 |
---|---|---|
--repository | データのアップロード先となるリポジトリの OWNER/NAME を指定します。 オーナーは GitHub Advanced Security のライセンスを持つ Enterprise 内の Organization でなければならず、GitHub Advanced Security はリポジトリで有効化されていなければなりません。 詳細については、「リポジトリのセキュリティと分析の設定を管理する」を参照してく� さい。 | |
--ref | チェックアウトして分析した ref の名前を指定して、結果を正しいコードと照合できるようにします。 ブランチで refs/heads/BRANCH-NAME を使用するか、pull request のヘッド コミットで refs/pull/NUMBER/head を使用するか、pull request の GitHub で生成されたマージ コミットで refs/pull/NUMBER/merge を使用します。 | |
--commit | 分析したコミットの完全な SHA を指定します。 | |
--sarif | 読み込む SARIF ファイルを指定します。 | |
--github-url | GitHub Enterprise ServerのURLを指定してく� さい。 | |
--github-auth-stdin | 任意。 GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力で CLI に渡すために使います。 このトークンを使用して設定された GITHUB_TOKEN 環境変数にコマンドがアクセスできる� �合、これは必要ありません。 |
詳細については、CodeQL CLI のドキュメントの「github upload-results」を参照してく� さい。
基本的な例
この例では、SARIF ファイル temp/example-repo-js.sarif
からリポジトリ my-org/example-repo
に結果をアップロードします。 結果が main
ブランチのコミット deb275d2d5fe9a522a0b7bd8b6b6a1c939552718
に対するものであることを code scanning API に伝えます。
$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=/temp/example-repo-js.sarif --github-url=https://github.example.com \
--github-auth-stdin
アップロードが失敗しなければ、このコマンドからの出力はありません。 コマンドプロンプトは、アップロードが完了してデータ処理が開始された時点で戻ってきます。 小さなコードベースでは、すぐ後にGitHub Enterprise Server中のcode scanningアラートを調べることができるでしょう。 チェックアウトしたコードに応じて、アラートを直接 pull request に、またはブランチの [セキュリティ] タブで表示できます。詳細については、「pull request でのcode scanning アラートのトリアージ」および「リポジトリのcode scanning アラートを管理する」を参照してく� さい。
CodeQL分析のためのCIの設定例
これは、2つのサポートされている言語を持つコードベースを分析し、結果をGitHub Enterprise Serverにアップロードするために使うことができる一連のコマンドの例です。
# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'
codeql database create codeql-dbs --source-root=src \
--db-cluster --language=java,python --command=./myBuildScript
# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'
codeql database analyze codeql-dbs/java java-code-scanning.qls \
--format=sarif-latest --sarif-category=java --output=java-results.sarif
# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'
codeql database analyze codeql-dbs/python python-code-scanning.qls \
--format=sarif-latest --sarif-category=python --output=python-results.sarif
# Upload the SARIF file with the Java results: 'java-results.sarif'
echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=java-results.sarif --github-auth-stdin
# Upload the SARIF file with the Python results: 'python-results.sarif'
echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
--ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
--sarif=python-results.sarif --github-auth-stdin
CIシステ� でのCodeQL CLIのトラブルシューティング
ログと診断情� �を見る
code scanningクエリスイートを使ってCodeQLデータベースを分析する際には、アラートに関する詳細情� �を生成するのに� えて、CLIはデータベース生成ステップからの診断情� �とサマリメトリクスを� �告します。 アラートが少ないリポジトリでは、実際にコード中の問題が少ないのか、あるいはCodeQLデータベースの生成時にエラーがあったのかを判断するのにこの情� �が役立つかもしれません。 codeql database analyze
からさらに詳しい出力を得るには、--verbose
オプションを使用します。
使用可能な診断情� �の種類について詳しくは、「code scanning ログの表示」を参照してく� さい。
Code scanningは、分析された言語の1つからの分析結果� けを表示します。
デフォルトでは、code scanningはリポジトリの分析ごとに1つのSARIF結果ファイルを期待します。 したがって、コミットから2つめのSARIF結果ファイルをアップロードすると、それはデータのオリジナルのセットの置き換えとして扱われます。
リポジトリ中の1つのコミットについての結果をcode scanning APIに複数アップロードしたい� �合は、それぞれの結果をユニークなセットとして特定しなければなりません。 コミットごとに分析する CodeQL データセットを複数作成するリポジトリでは、--sarif-category
オプションを使用して、そのリポジトリで生成するそれぞれの SARIF ファイルに言語または他の一意のカテゴリを指定します。