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

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

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