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

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

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 のオプションを持つすべてのエクストラクターに対してエクストラクターオプション option1 を abc に設定します。たとえば、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 は複数回指定できます。エクストラクターオプションの割り当ては、次の順序で処理されます。

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

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

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

この記事の内容

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