Skip to main content

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

CodeQL CLI を使って、ソフトウェア プロジェクトでローカルに CodeQL プロセスを実行できます。

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

CodeQL は、次の種類のリポジトリで使用できます:

エクストラクターについて

CodeQL CLI では、エクストラクターと呼ばれる特別なプログラムを使って、ソフトウェア システムのソース コードからクエリを実行できるデータベースに情報を抽出します。 エクストラクターの動作をカスタマイズするには、CodeQL CLI を使ってエクストラクターの構成オプションを設定します。

エクストラクターのオプションについて

各エクストラクターでは、独自の構成オプション セットを定義します。 特定のエクストラクターで使用できるオプションを確認するには、--format=betterjson オプションを指定して、codeql resolve languages または codeql resolve extractor を実行します。 betterjson 出力形式は、エクストラクターのルート パスと追加情報を提供します。 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]*"
                }
            }
        }
    }
}

エクストラクターのオプションの名前と説明は、extractor_options の下に一覧表示されます。 各オプションには、次のフィールドを含めることができます。

  • title (必須): オプションのタイトル
  • description (必須): オプションの説明
  • type (必須): オプションの種類。次の値を指定できます。
    • string: オプションに 1 つの文字列値を指定できることを示します
    • array: オプションに文字列値のシーケンスを指定できることを示します
    • object: オプションそのものではなく、他のオプションやオプション グループを含む可能性があるグループであることを示します
  • pattern (省略可能): オプションのすべての値が一致する正規表現パターン。 この正規表現パターンで表現されない、または表現できないオプション値に対して、エクストラクターによって追加の制約が課される場合があることにご注意ください。 このような制約が存在する場合は、[説明] フィールドで説明されます。
  • properties (省略可能): オプション グループ内のエクストラクター オプション名から、対応するエクストラクター オプションの説明へのマップ。 このフィールドは、オプション グループにのみ存在することができます。 たとえば、object 型のオプションです。

上の例では、エクストラクターによって 2 つのオプションが宣言されています。

  • option1 は、[a-z]+ に一致する値を持つ string オプションである
  • group1.option2 は、[1-9][0-9]\* に一致する値を持つ array オプションである

CodeQL CLI を使用してエクストラクター オプションを設定する

CodeQL CLI では、エクストラクターを直接または間接的に呼び出すサブコマンドでのエクストラクター オプションの設定がサポートされています。 そのコマンドを次に示します。

  • codeql database create
  • codeql database start-tracing
  • codeql database trace-command
  • codeql database index-files

これらのサブコマンドを実行する場合は、--extractor-option CLI オプションを使ってエクストラクター オプションを設定できます。 次に例を示します。

  • codeql database create --extractor-option java.option1=abc ...
  • codeql database start-tracing --extractor-option java.group1.option2=102 ...

--extractor-option には、extractor_option_name=extractor_option_value という形式の引数が 1 つだけ必要です。 extractor_option_name は、エクストラクターの名前 (この例では java) の後にピリオド、さらにエクストラクター オプションの名前 (この例では option1 または group1.option2 のいずれか) が続きます。 extractor_option_value は、エクストラクター オプションに割り当てられている値です。 この値は、エクストラクター オプションの正規表現パターンと一致する必要があり (存在する場合)、改行文字を含めることはできません。

--extractor-option を使用して、存在しないエクストラクター オプションを割り当てるとエラーになります。

CodeQL CLI は、同じ呼び出しで複数の --extractor-option オプションを受け付けます。 string エクストラクター オプションを複数回設定すると、最後のオプション値により前のすべてのオプションが上書きされます。 配列エクストラクター オプションを複数回設定すると、すべてのオプション値が順番に連結されます。

エクストラクター名なしでエクストラクター オプション名を指定することもできます。 次に例を示します。

  • codeql database create --extractor-option option1=abc ...
  • codeql database start-tracing --extractor-option group1.option2=102 ...

エクストラクター名を指定しない場合、エクストラクター オプションの設定は、指定された名前でオプションを宣言するすべてのエクストラクターに適用されます。 上記の例では、最初のコマンドにより、java エクストラクターと、option1 のオプションを持つすべてのエクストラクターに対してエクストラクター オプション option1abc に設定します。たとえば、option1 エクストラクター オプションがそのエクストラクターに対して存在する場合は、cpp エクストラクターです。

ファイルからのエクストラクター オプションの設定

ファイルを使ってエクストラクター オプションを設定することもできます。 --extractor-option を受け入れる CodeQL CLI サブコマンドは --extractor-options-file も受け入れます。これは、YAML ファイルへのパスの必須引数 (拡張子は .yaml または .yml) または JSON ファイル (拡張子は .json) を持ちます。 次に例を示します。

  • codeql database create --extractor-options-file options.yml ...
  • codeql database start-tracing --extractor-options-file options.json ...

各オプション ファイルには、入れ子になったマップのツリー構造が含まれています。 ルートにはエクストラクター マップ キーがあり、その下にはエクストラクター名に対応するマップ キーがあります。 3 番目のレベルから、エクストラクター オプションとオプション グループがあります。

JSON の場合:

{
     "extractor" : {
        "java": {
            "option1" : "abc",
            "group1" : {
                "option2" : [ 102 ]
            }
        }
    }
}

YAML の場合:

extractor:
    java:
        option1: "abc"
        group1:
            option2: [ 102 ]

エクストラクター オプションの string 値は、文字列または数値である必要があります (これは、さらに処理される前に文字列に変換されます)。

エクストラクター オプションの array 値は、文字列または数値の配列である必要があります。

オプション グループ (型 object の) の値は、入れ子になったエクストラクター オプションとオプション グループを含むマップである必要があります。

各エクストラクター オプションの値は、エクストラクター オプションの正規表現パターンと一致する必要があり (存在する場合)、改行文字を含めることはできません。

存在しないエクストラクター オプションを割り当てるとエラーになります。 特別な __allow_unknown_properties ブール型フィールドを使用して、CodeQL CLI が不明なエクストラクター オプションを無視するようにすることができます。 たとえば、次のオプション ファイルは、CodeQL CLI に対して、group1 の下の不明なエクストラクター オプションとオプション グループをすべて無視するように求めています。

extractor:
    java:
        option1: "abc"
        group1:
            __allow_unknown_properties: true
            option2: [ 102 ]

--extractor-options-file は複数回指定できます。 エクストラクター オプションの割り当ては、次の順序で処理されます。

  1. --extractor-options-file によって指定されたすべてのエクストラクター オプション ファイルは、コマンド ラインに表示される順序で処理されます。次に、
  2. --extractor-option によって指定されたすべてのエクストラクター オプションの割り当ては、コマンド ラインに表示される順序で処理されます

割り当てが行われる際に使用されるのが --extractor-option か、--extractor-options-file か、2 つの組み合わせかに関わらず、同じエクストラクター オプションが複数回設定された場合の動作は、同じルールによって制御されます。 string エクストラクター オプションを複数回設定すると、最後のオプション値により前のすべての値が上書きされます。 array エクストラクター オプションを複数回設定すると、すべてのオプション値が順番に連結されます。