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

С помощью CodeQL CLI можно запускать процессы CodeQL локально в проектах программного обеспечения.

Кто может использовать эту функцию?

CodeQL доступен для следующих типов репозитория:

В этой статье

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

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