提取器选项

可用的提取器选项

每个提取器都有自己的一套配置选项，用于从源代码构建可查询的 CodeQL 数据库。要了解特定提取器提供了哪些选项，可以运行以下任意命令：

codeql resolve languages --format=betterjson
codeql resolve extractor --language=LANGUAGE --format=betterjson

betterjson 输出格式提供提取器的根路径以及其它附加信息。codeql resolve extractor --language=LANGUAGE --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：表示该选项只能接受单个字符串值
- array：表示该选项可以接受一系列字符串值
- object：表示它本身不是选项，而是一个分组，可能包含其他选项或选项组
pattern（可选）：所有该选项的取值必须匹配的正则表达式模式。请注意，提取器可能会对选项值施加额外约束，这些约束在正则表达式之外，通常会在描述字段中说明。
properties（可选）：一个映射，键为选项组内的提取器选项名称，值为对应选项的描述。此字段只能出现在选项组（即 object 类型）中。

在上面的示例中，提取器声明了两个选项：

option1 是一个 string 选项，取值需匹配 [a-z]+
group1.option2 是一个 array 选项，取值需匹配 [1-9][0-9]*

设置提取器选项的命令

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 的参数。

extractor_option_name 为提取器名称（本例中为 java），后跟一个句点，再接选项名称（本例中为 option1 或 group1.option2）。
extractor_option_value 为要分配给该选项的值。该值必须匹配选项的正则表达式模式（若存在），且不得包含换行符。

使用 --extractor-option 为不存在的提取器选项赋值会导致错误。

CodeQL CLI 在一次调用中可以接受多个 --extractor-option。如果多次设置同一个 string 类型的选项，最后一次的值会覆盖之前的所有值。如果多次设置同一个 array 类型的选项，所有提供的值会按顺序拼接。

也可以在不写提取器名称的情况下指定选项名。例如：

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

如果未指定提取器名称，选项设置会应用于所有声明了该选项名称的提取器。以上示例中，第一个命令会把 option1 设置为 abc，对 java 提取器以及任何同样拥有 option1 选项的提取器（例如 cpp）生效，只要该提取器真的定义了 option1。

提取器选项的文件格式

也可以通过文件来设置提取器选项。接受 --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 ...

每个选项文件包含一个嵌套映射的树形结构。根层是提取器映射键，其下的键对应提取器名称。从第三层开始，出现的是提取器选项和选项组。

在 JSON 中

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

在 YAML 中

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

string 类型的提取器选项值必须是字符串或数字（数字将在后续处理前转换为字符串）。

array 类型的提取器选项值必须是字符串或数字构成的数组。

选项组（object 类型）的值必须是映射，可以包含嵌套的提取器选项和选项组。

每个提取器选项的值必须匹配该选项的正则表达式模式（若存在），且不得包含换行符。

为不存在的提取器选项赋值会导致错误。可以通过使用特殊的布尔字段 __allow_unknown_properties 让 CodeQL CLI 忽略未知的提取器选项。例如，以下选项文件要求 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，还是两者的组合。如果多次设置同一个 string 类型的选项，最后一次的值会覆盖之前的所有值；如果多次设置同一个 array 类型的选项，所有提供的值会按顺序拼接。

谁可以使用此功能？

本文内容

可用的提取器选项

设置提取器选项的命令

提取器选项的文件格式