Параметры средства извлечения

Сведения о средствах извлечения

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 параметр средства извлечения несколько раз, последнее значение параметра перезапишет все предыдущие значения. Если задать параметр средства извлечения массива несколько раз, все значения параметров объединяются по порядку.

Можно также указать имена параметров средства извлечения без имени средства извлечения. Например:

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

Если не указать имя средства извлечения, параметры средства извлечения будут применяться ко всем средствам извлечения, объявляющим параметр с заданным именем. В приведенном выше примере первая команда присваивает параметру option1 средства извлечения значение abc для java средства извлечения, а для каждого средства извлечения, который имеет параметр option1, например cpp средства извлечения, если option1 для этого средства извлечения существует параметр.

Настройка параметров средства извлечения из файлов

Вы также можете задать параметры средства извлечения с помощью файла. Подкоманды CodeQL CLI, принимаюющие --extractor-option , также принимают --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) должно быть картой, которая может содержать вложенные параметры и группы параметров средства извлечения.

Каждое значение параметра средства извлечения должно соответствовать шаблону регулярного выражения параметра средства извлечения (если он существует) и не должно содержать символов новой строки.

Назначение параметра средства извлечения, который не существует, является ошибкой. Вы можете заставить CodeQL CLI игнорировать неизвестные параметры средства извлечения с помощью специального __allow_unknown_properties логического поля. Например, следующий файл параметров просит CodeQL CLI игнорировать все неизвестные параметры средства извлечения и группы параметров в разделе group1:

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

Можно указать --extractor-options-file несколько раз. Назначения параметров средства извлечения обрабатываются в следующем порядке:

1. Все файлы параметров средства извлечения, указанные параметром --extractor-options-file , обрабатываются в том порядке, в который они отображаются в командной строке, а затем
2. Все назначения параметров средства извлечения, указанные параметром , --extractor-option обрабатываются в том порядке, в который они отображаются в командной строке.

Одни и те же правила определяют, что происходит, когда один и тот же параметр извлечения задается несколько раз, независимо от того, выполняются ли назначения с помощью --extractor-option, с помощью --extractor-options-fileили с помощью некоторого сочетания этих двух компонентов. Если задать string параметр средства извлечения несколько раз, последнее значение параметра перезапишет все предыдущие значения. Если задать array параметр средства извлечения несколько раз, все значения параметров объединяются по порядку.