Использование редактора моделей CodeQL

О CodeQL редакторе моделей

С помощью моделей вы можете расширить анализCodeQLCodeQL, чтобы распознавать пользовательские библиотеки и фреймворки, code scanning используемые вашей кодовой базой, которые по умолчанию не поддерживаются. С помощью CodeQL редактора моделей вы можете создавать собственные наборы моделей. Редактор моделей позволяет моделировать вызовы внешних зависимостей в приложении или полностью моделировать все общедоступные точки входа и выхода во внешней зависимости.

Для получения дополнительной информации о кастомизации code scanning анализа с помощью наборов моделей смотрите Изменение конфигурации настройки по умолчанию и Параметры настройки рабочих процессов для сканирования кода.

Когда вы открываете редактор модели, он анализирует выбранную CodeQL базу данных и определяет, где приложение использует внешние API и все публичные методы. Внешний (или сторонний) API — это любой API, который не входит в CodeQL выбранную вами базу данных.

Редактор моделей имеет два разных режима:

• Режим приложения (представление по умолчанию): редактор перечисляет каждый внешний фреймворк, используемый выбранной CodeQL базой данных. При развертывании платформы отображается список всех вызовов и из внешнего API с параметрами, доступными для потока данных модели с помощью каждого вызова. Этот режим наиболее полезен для улучшения CodeQL результатов для конкретной кодовой базы.

• Режим зависимостей: Редактор определяет все общедоступные API в выбранной CodeQL базе данных. Это представление поможет вам с помощью моделирования каждого общедоступного API, который предоставляет база кода. Когда вы завершите моделирование всего API, вы сможете сохранить модель и использовать её для улучшения CodeQL анализа всех кодовых баз, использующих зависимость.

Остальная часть этой статьи посвящена практическим аспектам моделирования зависимостей с помощью CodeQL редактора моделей. Для технической информации см. разделы «Настройка моделей библиотек для Java и Kotlin», «Настройка моделей библиотек для Python», «Настройка моделей библиотек для Ruby», «Настройка моделей библиотек для C# » в документации CodeQL по языку.

Отображение CodeQL редактора моделей

1. Откройте рабочее CodeQL пространство в VS Code. Например, vscode-codeql-starter рабочая область. Если вы используете начальную рабочую область, обновите ql подмодул, main чтобы убедиться, что у вас есть запросы, используемые для сбора данных для редактора моделей.

2. В , нажмите QLVisual Studio Codeв левой боковой панели, чтобы отобразить расширениеCodeQL.

3. В просмотре «Базы данных» выберите CodeQL базу данных, из которой хотите моделировать.

4. В режиме CodeQL «Method Modeling» нажмите Start modeling, чтобы отобразить редактор моделей. В качестве альтернативы VS Code Command Palette используйте команду CodeQL: Open Model Editor (Beta ).

5.        CodeQL Редактор моделей запускает серию телеметрических запросов для идентификации API в коде, а редактор отображается в новой вкладке.
   

6. После завершения запросов телеметрии в редакторе отображаются api, которые были определены.

Моделирование вызовов базы кода для внешних API

Обычно этот подход используется, когда рассматриваешь конкретную кодовую базу, где хочется повысить точность CodeQL результатов. Это полезно, когда кодовая база использует фреймворки или библиотеки, не поддерживаемые CodeQL, и если исходный код фреймворка или библиотеки не включен в анализ.

В этом разделе приводится open source Java проект под названием «sofa-jraft» в качестве примера. Опыт моделирования вызовов внешних API, написанных на других скомпилированных языках, аналогичен.

1. В Visual Studio Code, выберите CodeQL базу данных, для которой хотите улучшить CodeQL покрытие.

2. Отобразите CodeQL редактор моделей. По умолчанию редактор выполняется в режиме приложения, поэтому отображается список внешних API, используемых выбранной базой кода.

   

3. Щелкните, чтобы развернуть внешний API и просмотреть список вызовов из базы кода во внешнюю зависимость.

   

4. Щелкните View , связанный с вызовом или методом API, чтобы показать, где он используется в базе кода.

5. Файл, содержащий первый вызов из вашей кодовой базы в API, открывается, и отображается CodeQLVS Code вид «Использование методов» (где обычно отображаются «Проблемы» и «Терминал»). Просмотр «Использование методов» содержит CodeQL список всех вызовов вашего кода в API, сгруппированных по методам. Вы можете щелкнуть каждый из них, чтобы решить, как моделировать использование метода.

6. Когда вы определили, как моделировать использование метода, можно выбрать другой тип модели. Нажмите на выпадающее меню в разделе «Тип модели» в CodeQL режиме «Method Modeling» CodeQL расширения. Это изменение автоматически отражается в редакторе основных моделей.

7. Остальные поля в этой строке обновляются с параметрами, доступными для выбранного типа модели:

   • Source: выберите элемент Output для модели.
   • "Приемник": выберите элемент Input для модели.
   • "Сводка потока": выберите элементы Input и Output для моделирования.

8. Определите тип потока данных для модели.

9. После завершения моделирования отобразите главный редактор моделей и нажмите кнопку "Сохранить все " или " Сохранить" (показано в правом нижнем углу каждого развернутого списка методов). Процент методов, моделироваемых в редакторе, обновляется.

Модели хранятся в вашем рабочем пространстве по адресу .github/codeql/extensions/CODEQL-MODEl-PACK, где CODEQL-MODEL-PACK — название CodeQL выбранной вами базы данных. То есть название репозитория, дефис, язык, анализируемый .CodeQL Дополнительные сведения см. в разделе Создание и работа с пакетами CodeQL.

Модели хранятся в ряде файлов расширения данных YAML, по одному для каждого внешнего API. Рассмотрим пример.

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

Моделирование общедоступного API базы кода

Этот метод обычно используется, если вы хотите моделировать платформу или библиотеку, которую ваша организация использует в нескольких базах кода. После завершения создания и тестирования модели вы можете опубликовать CodeQL пакет моделей GitHubContainer registry для всей вашей организации.

В этом разделе приводится open source Java проект под названием «sofa-jraft» в качестве примера. Опыт моделирования вызовов внешних API, написанных на других скомпилированных языках, аналогичен.

1. Выберите CodeQL базу данных, которую хотите моделировать.

2. Отобразите CodeQL редактор моделей. По умолчанию редактор выполняется в режиме приложения. Щелкните "Модель как зависимость", чтобы отобразить режим зависимостей. На экране отображаются общедоступные API платформы или библиотеки.

   

3. Щелкните, чтобы развернуть пакет и просмотреть список доступных методов.

4. Щелкните View , связанный с методом, чтобы отобразить его определение.

   

5. Когда вы определили, как моделировать метод, определите тип модели.

6. Остальные поля в этой строке обновляются с параметрами, доступными для выбранного типа модели:

   • Source: выберите элемент Output для модели.
   • "Приемник": выберите элемент Input для модели.
   • "Сводка потока": выберите элементы Input и Output для моделирования.

7. Определите тип потока данных для модели.

8. После завершения моделирования нажмите кнопку "Сохранить все " или "Сохранить " (показано в правом нижнем углу каждого развернутого списка вызовов). Процент вызовов, моделироваемых в редакторе, обновляется.

Модели хранятся в вашем рабочем пространстве по адресу .github/codeql/extensions/CODEQL-MODEL-PACK, где CODEQL-MODEL-PACK — название CodeQL выбранной вами базы данных. То есть название репозитория, дефис, язык, анализируемый .CodeQL Дополнительные сведения см. в разделе Создание и работа с пакетами CodeQL.

Модели хранятся в ряде файлов расширения данных YAML, по одному для каждого общедоступного метода. Рассмотрим пример.

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

Редактор создаст отдельный файл модели для каждого пакета, который вы моделировали.

Методы моделирования с несколькими потенциальными потоками

Некоторые методы поддерживают несколько потоков данных. Важно моделировать все потоки данных для метода, в противном случае невозможно обнаружить все потенциальные проблемы, связанные с использованием метода. Сначала вы моделироваете один поток данных для метода, а затем используйте + кнопку в строке метода, чтобы указать вторую модель потока данных.

Пакеты тестовых CodeQL моделей VS Code

Вы можете протестировать любые CodeQL созданные вами наборы VS Code моделей с помощью настройки «Running Queries: Use Extension Packs». Дополнительные сведения см. в разделе Настройка параметров. Этот метод работает как для баз данных, так и для репозиториев анализа вариантов.

• Чтобы запустить запросы в CodeQL базе данных с любыми пакетами моделей, хранящимися в каталоге рабочего пространства, обновите файл settings.json с помощью следующего:.github/codeql/extensions``"codeQL.runningQueries.useExtensionPacks": "all",

• Чтобы запускать запросы в CodeQL базе данных без использования моделевых пакетов, обновите файл settings.json следующим образом: "codeQL.runningQueries.useExtensionPacks": "none",

Если модель работает хорошо, вы увидите разницу в результатах двух разных запусков. Если вы не видите никаких различий в результатах, может потребоваться ввести известную ошибку, чтобы убедиться, что модель работает должным образом.

Дополнительные материалы

• Изменение конфигурации настройки по умолчанию
• AUTOTITLE AUTOTITLE.