エクストラクターについて
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
エクストラクター オプションを複数回設定すると、すべてのオプション値が順番に連結されます。