CodeQL 用のデータベースを準備する

  • 5 分

CodeQL は、コードをデータのように扱います。 コードベースから抽出したクエリ可能なデータを使用してデータベースを作成します。 その後、このデータベースに対して CodeQL クエリを実行して、セキュリティの脆弱性、バグ、その他のエラーを特定できます。 独自のクエリを記述することも、GitHub の研究者やコミュニティの共同作成者によって記述された標準の CodeQL クエリを実行することもできます。

このユニットでは、データベースを作成する方法について説明します。 この手順は、コードを分析する前に必要です。 コードに対してクエリを実行するために必要なすべてのデータを含む CodeQL データベースを作成する必要があります。

CodeQL 分析は、コードからリレーショナル データを抽出し、それを使用して CodeQL データベースを構築することに依存します。 これらのデータベースには、コードベースに関するすべての重要な情報が含まれています。

CodeQL CLI スタンドアロン製品を使用して、コードを分析し、コードベースのデータベース表現を生成できます。 データベースの準備ができたら、データベースに対してクエリを実行するか、一連のクエリを実行して、静的分析結果交換形式 (SARIF) で一連の結果を生成できます。

CodeQL のデータベース準備

CodeQL データベースを生成する前に、CodeQL CLI をインストールして設定する必要があります。 その後、分析するコードベースのバージョンを確認する必要があります。

コンパイル済み言語の場合、ディレクトリをビルドする準備が整い、すべての依存関係が既にインストールされている必要があります。 CodeQL では、まず、コードベース内の各ソース ファイルの 1 つのリレーショナル表現を抽出してデータベースを作成します。 このデータベースを使用してコードを分析します。

解釈された言語の場合、エクストラクターはソース コードで直接実行されます。 この機能により、コードベースを正確に表現し、依存関係を解決できます。

コードベースからのソース ファイルの抽出は、コンパイルされた言語の通常のビルド プロセスを監視することによって機能します。 CodeQL は、コンパイラを呼び出してソース ファイルを処理するたびに、ソース ファイルのコピーを作成します。 各ソース ファイルを使用して、ソース コードに関するすべての関連情報が収集されます。

CLI のセットアップ

CodeQL CLI を設定するには、次の手順に従います。

1. CodeQL CLI バンドルの .zip パッケージをダウンロードする

バンドルされたパッケージをダウンロードして、CodeQL CLI とクエリをインストールすることをお勧めします。 この方法は、CLI とクエリを個別にダウンロードするのではなく、互換性とパフォーマンスの向上に役立ちます。

CodeQL CLI ダウンロード パッケージは、ツール、スクリプト、およびさまざまな CodeQL 固有のファイルを含む .zip アーカイブです。 バンドルには、CodeQL CLI、CodeQL GitHub リポジトリからのクエリとライブラリの互換性のあるバージョン、および含まれるクエリのプリコンパイル済みバージョンが含まれます。

  1. CodeQL パブリック リポジトリの [リリース] ページに移動します。
  2. [アセット] でプラットフォーム固有のバンドルをダウンロードします。

[ リリース ] ページでは、以前のバージョンの CodeQL バンドルのダウンロードと共に、リリースの変更ログを表示することもできます。 必要に応じて、サポートされているすべてのプラットフォームの CLI を含む codeql-bundle.tar.gzをダウンロードできます。

2. .zip アーカイブを抽出する

Linux、Windows、または macOS を使用している場合は、任意のディレクトリに .zip アーカイブを抽出できます。

macOS Catalina (またはそれ以降) のユーザーは、さらに手順を実行する必要があります。 詳細については、 CLI の概要に関する CodeQL ドキュメントを参照してください。

3. CodeQL プロセスを実行する

抽出後、次のいずれかの手順を実行して、 codeql 実行可能ファイルを使用して CodeQL プロセスを実行します。

  • <extraction-root>/codeql/codeqlを実行します。ここで、<extraction-root>は CodeQL CLI パッケージを抽出したフォルダーです。
  • <extraction-root>/codeql エントリにPATHを追加して、実行可能ファイルをcodeqlとして実行できるようにします。

CodeQL コマンドを実行できるようになりました。

CLI セットアップの検証

CodeQL CLI サブコマンドを実行して、CLI を正しく設定し、データベースを分析できることを確認できます。

  • codeql resolve packs (codeql にPATHを追加した場合) を実行して、CLI で検索できる CodeQL パックを表示します。 それ以外の場合は、/<extraction-root>/codeql/codeql resolve packs を使用します。 このコマンドは、前の手順で示した CodeQL CLI バンドルに含まれる CodeQL パックの名前を <extraction-root>として表示します。

    CodeQL CLI で想定される言語の CodeQL パックが見つからない場合は、CodeQL CLI のスタンドアロン コピーではなく、CodeQL バンドルをダウンロードしたことを確認してください。

  • codeql resolve languagesを実行して、CodeQL CLI パッケージで既定でサポートされている言語を表示します。

データベースの作成

プロジェクトのチェックアウト ルートから次のコマンドを実行して、CodeQL データベースを作成します。

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

コマンド内で:

  • <database>を、作成する新しいデータベースへのパスに置き換えます。
  • <language-identifier>を、データベースの作成に使用している言語の識別子に置き換えます。 この識別子を --db-cluster と共に使用してコンマ区切りのリストを受け入れるか、複数回指定できます。

次のオプションを指定することもできます。 これらのオプションは、ソース ファイルの場所、コードをコンパイルする必要があるかどうか、または複数の言語用に CodeQL データベースを作成するかどうかによって異なります。

  • --source-rootを使用して、データベース作成用のプライマリ ソース ファイルのルート フォルダーを識別します。
  • 複数の言語のデータベースを作成する場合は、複数の言語のコードベースに --db-cluster を使用します。
  • 1 つ以上のコンパイル済み言語のデータベースを作成する場合は、 --command を使用します。 Python と JavaScript のみを使用している場合は、このオプションは必要ありません。
  • --no-run-unnecessary-buildsと--db-clusterを使用して、CodeQL CLI でビルドを監視する必要がない言語のビルド コマンドを抑制します。

データベースを正常に作成すると、コマンドで指定されたパスに新しいディレクトリが表示されます。 --db-cluster オプションを使用して複数のデータベースを作成した場合は、言語ごとにサブディレクトリが作成されます。

各 CodeQL データベース ディレクトリには、分析に使用されるリレーショナル データやソース アーカイブなど、複数のサブディレクトリが含まれています。 ソース アーカイブは、データベースを作成した時点で作成されたソース ファイルのコピーです。 CodeQL では、分析結果を表示するために使用されます。

抽出器

エクストラクターは、CodeQL データベースの構築元となる各入力ファイルのリレーショナル データとソース参照を生成するツールです。 CodeQL でサポートされる各言語には、1 つのエクストラクターがあります。 この構造により、抽出プロセスが可能な限り正確になります。

各エクストラクターでは、独自の構成オプション セットを定義します。 codeql resolve extractor --format=betterjson入力すると、次の例のようにデータが書式設定されます。

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

言語のエクストラクターで使用できるオプションを確認するには、「 codeql resolve languages --format=betterjson または codeql resolve extractor --format=betterjson」と入力します。 betterjson出力形式には、エクストラクターのルートやその他の言語固有のオプションも用意されています。

CodeQL データベース内のデータ

CodeQL データベースは、分析に必要なすべてのデータを含む 1 つのディレクトリです。 このデータには、リレーショナル データ、コピーされたソース ファイル、およびデータ内の相互関係を指定する言語固有のデータベース スキーマが含まれます。 CodeQL は、抽出後にこのデータをインポートします。

CodeQL データベースは、コードベースから抽出された特定の言語のクエリ可能なデータのスナップショットを提供します。 このデータは、コードの完全な階層表現です。 これには、抽象構文ツリー、データ フロー グラフ、および制御フロー グラフの表現が含まれます。

データベースは、複数言語のコードベースに対して一度に 1 つの言語で生成されます。 各言語には、独自の一意のデータベース スキーマがあります。 スキーマは、抽出プロセス中の最初の字句分析と CodeQL による複雑な分析の間のインターフェイスを提供します。

CodeQL データベースには、次の 2 つのメイン テーブルが含まれています。

  • expressions テーブルには、CodeQL がビルド プロセス中に分析したソース コード内のすべての式の行が含まれています。
  • statements テーブルには、CodeQL がビルド プロセス中に分析したソース コード内のすべてのステートメントの行が含まれています。

CodeQL ライブラリは、これらの各テーブルに抽象化レイヤーを提供するクラスを定義します。 このレイヤーには、関連する補助テーブル Expr と Stmtが含まれます。

CodeQL の不足の可能性

コード スキャン ワークフローでのデータベースの作成には、いくつかの不足が考えられます。 このセクションでは、GitHub CodeQL アクションの使用について具体的に説明します。

autobuildの言語マトリックスを使用して、マトリックスに一覧表示されているコンパイル済みの各言語をビルドする必要があります。 マトリックスを使用して、サポートされている複数のバージョンのプログラミング言語、オペレーティング システム、またはツールのジョブを作成できます。

マトリックスを使用しない場合、 autobuild は、リポジトリ内の最も多くのソース ファイルを使用して、サポートされているコンパイル済み言語のビルドを試みます。 Go 以外のコンパイル済み言語の分析は、多くの場合、分析手順を実行する前にコードをビルドするための明示的なコマンドを指定しない限り失敗します。

autobuildステップの動作は、言語エクストラクターが実行されているオペレーティング システムによって異なります。 autobuildの手順では、オペレーティング システムに基づいて言語に適したビルド方法を自動的に検出しようとします。 この動作により、コンパイルされた言語で信頼性の低い結果が得られる可能性があり、多くの場合、実行が失敗する可能性があります。

コードスキャンワークフロー ファイル内で、分析の前に実行されるビルドステップを構成することをお勧めします。これは、autobuild がコンパイル済みの言語をビルドしようとする代わりに行います。 これにより、ワークフロー ファイルは、システムとプロジェクトのビルド要件に合わせて調整され、より信頼性の高いスキャンが可能になります。

autobuildでは、特定の言語と手順の詳細を確認できます。

VS Code 拡張機能

VS Code 1.39 以降を使用している限り、Visual Studio Code (VS Code) と CodeQL 拡張機能を使用してクエリをコンパイルして実行できます。 Visual Studio Code Marketplace から、または CodeQL VSIX ファイルをダウンロードして、拡張機能をダウンロードできます。

この拡張機能では、 PATH で見つかったインストール済みの CLI (使用可能な場合) が使用されます。 そうでない場合、拡張機能は CLI の実行可能ファイルへのアクセスを自動的に管理します。 自動管理により、CLI は CodeQL 拡張機能と互換性があります。