提取程序选项

关于提取程序

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：指示选项可以具有单个字符串值
- array：指示选项可以具有字符串值序列
- object：指示它不是选项本身，而是可能包含其他选项和选项组的分组
pattern（可选）：选项的所有值都应匹配的正则表达式模式。请注意，提取程序可能会对未采用或无法采用此正则表达式模式来表示的选项值施加其他约束。说明字段下会解释此类约束（如果存在）。
properties（可选）：从选项组中的提取程序选项名称映射到相应的提取程序选项说明。此字段只为选项组提供。例如，object 类型的选项。

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

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 形式的参数。 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 提取程序选项存在，例如 cpp 提取程序）的提取程序选项 option1 设置为 abc。

从文件设置提取程序选项

还可以通过文件设置提取程序选项。接受 --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 忽略未知提取程序选项。例如，以下选项文件要求 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 还是两者的某种组合完成的。如果多次设置 string 提取程序选项，最后一个选项值会覆盖所有以前的值。如果多次设置 array 提取程序选项，则所有选项值会按顺序连接。

谁可以使用此功能？

本文内容

关于提取程序

关于提取程序选项

使用 CodeQL CLI 设置提取程序选项

从文件设置提取程序选项