提取器选项

关于提取器

CodeQL CLI 使用称为提取器的特殊程序将软件系统源代码中的信息提取到可查询的数据库中。您可以通过 CodeQL CLI 设置提取器配置选项来自定义提取器的行为。

每个提取器都定义了自己的配置选项集。要了解特定提取器有哪些可用选项，您可以运行 codeql resolve languages 或 codeql resolve extractor 并使用 --format=betterjson 选项。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 是一个 string 选项，其值匹配 [a-z]+
group1.option2 是一个 array 选项，其值匹配 [1-9][0-9]\*

使用 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 提取器选项，则最后一个选项值会覆盖所有先前的选项值。如果多次设置 array 提取器选项，则所有选项值将按顺序连接。

您还可以指定不带提取器名称的提取器选项名称。例如

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

如果不指定提取器名称，则提取器选项设置将应用于所有声明具有给定名称的选项的提取器。在上面的示例中，第一个命令会将提取器选项 option1 设置为 java 提取器以及每个具有 option1 选项的提取器（例如 cpp 提取器）的 abc，如果该提取器存在 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 忽略未知的提取器选项。例如，以下选项文件要求 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 设置提取器选项

从文件设置提取器选项