Эта версия GitHub Enterprise Server была прекращена 2024-09-25. Исправления выпускаться не будут даже при критических проблемах безопасности. Для повышения производительности, повышения безопасности и новых функций выполните обновление до последней версии GitHub Enterprise Server. Чтобы получить справку по обновлению, обратитесь в службу поддержки GitHub Enterprise.

Настройка анализа с помощью пакетов CodeQL

Пакеты CodeQL можно использовать для выполнения запросов CodeQL , поддерживаемых другими людьми, или для совместного использования созданных запросов CodeQL .

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

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

В этой статье

О пакетах CodeQL

Примечание. В этой статье описываются функции, доступные в пакете CodeQL CLI 2.13.5 в первоначальном выпуске GitHub Enterprise Server 3.10.

Если администратор сайта обновил версию CodeQL CLI до более новой версии, ознакомьтесь с версией GitHub Enterprise Cloud этой статьи, чтобы узнать о последних функциях.

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

Существуют два типа пакетов CodeQL пакетов: пакетов запросов и пакетов библиотек.

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

  • Пакеты библиотек предназначены для использования пакетами запросов (или другими пакетами библиотек) и не содержат сами запросы. Библиотеки не компилируются отдельно.

Стандартные пакеты данных CodeQL для всех поддерживаемых языков публикуются в Container registry. Если вы установили CodeQL CLI стандартным способом, используя пакет CodeQL CLI, основные пакеты запросов уже скачиваются и доступны для вас. В их число входят:

  • codeql/cpp-queries
  • codeql/csharp-queries
  • codeql/go-queries
  • codeql/java-queries
  • codeql/javascript-queries
  • codeql/python-queries
  • codeql/ruby-queries
  • codeql/swift-queries

Можно также использовать CodeQL CLI для создания собственных пакетов CodeQL, добавления зависимостей в пакеты и установки или обновления зависимостей. Дополнительные сведения см. в разделе Создание и работа с пакетами CodeQL.

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

Скачивание и использование пакетов запросов CodeQL

Пакет CodeQL CLI включает запросы, которые обслуживают эксперты GitHub, исследователи безопасности и участники сообщества. Если вы хотите выполнять запросы, разработанные другими организациями, пакеты запросов CodeQL предоставляют эффективный и надежный способ загрузки и запуска запросов. Дополнительные сведения о пакетах запросов см. в разделе "О проверке кода с помощью CodeQL".

Прежде чем использовать пакет запросов CodeQL для анализа базы данных, необходимо скачать все пакеты, необходимые для GitHub Container registry. Это можно сделать с помощью флага --download codeql database analyze в рамках команды или запуска codeql pack download. Если пакет недоступен, необходимо использовать GitHub App или personal access token для проверки подлинности. Дополнительные сведения и пример см. в разделе "Отправка результатов анализа CodeQL в GitHub".

ВариантОбязательное полеИспользование
<scope/name@version:path>Укажите область и имя одного или нескольких пакетов запросов CodeQL для скачивания с помощью разделенного запятыми списка. При необходимости включите версию для скачивания и распаковки. По умолчанию скачивается последняя версия пакета. При необходимости добавьте путь к запросу, каталогу или набору запросов для выполнения. Если путь не включен, выполните запросы этого пакета по умолчанию.
--github-auth-stdinПередайте интерфейс командной строки GitHub App или personal access token, созданные для проверки подлинности с помощью REST API GitHubиз хранилища секретов с помощью стандартных входных данных. Это не требуется, если команда имеет доступ к переменной среды GITHUB_TOKEN, заданной с помощью этого маркера.

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

Дополнительные сведения о совместимости пакетов см. в разделе "Публикация и использование пакетов CodeQL".

Базовый пример загрузки и использования пакетов запросов

В этом примере выполняется команда codeql database analyze с параметром --download, чтобы:

  1. Скачать последнюю версию пакета octo-org/security-queries.
  2. Скачать версию octo-org/optional-security-queries пакета, которая была бы совместима с версией 1.0.1 (в данном случае это версия 1.0.2). Дополнительные сведения о совместимости SemVer см. в документации по семантическому диапазону версий npm.
  3. Выполните все запросы по умолчанию в octo-org/security-queries.
  4. Выполнение только запроса queries/csrf.ql из octo-org/optional-security-queries
$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Прямое скачивание пакетов CodeQL

Если вы хотите скачать пакет CodeQL без его немедленного запуска, можно использовать команду codeql pack download. Это полезно, если вы хотите избежать доступа к Интернету при выполнении запросов CodeQL. При выполнении анализа CodeQL можно указать пакеты, версии и пути так же, как и в предыдущем примере:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Скачивание пакетов CodeQL из нескольких реестров контейнеров GitHub

Если пакеты CodeQL находятся в нескольких реестрах контейнеров, необходимо указать CodeQL CLI, где найти каждый пакет. Дополнительные сведения см. в разделе Настройка расширенной настройки для сканирования кода.

Указание запросов, выполняемых в пакете CodeQL

Описатели запросов используются codeql database analyze и другими командами, которые работают с набором запросов. Полная форма описателя запроса:scope/name@range:path

  • scope/name — это полное имя пакета CodeQL.
  • range— это диапазон semver.
  • path — это путь к одному запросу, каталогу с запросами или файлу набора запросов.

При указании scope/nameзначения range и path необязательными. Если опущена range последняя версия указанного пакета, используется. Если не указано, path используется набор запросов по умолчанию указанного пакета.

Это path может быть один из: .ql файл запроса, каталог, содержащий один или несколько запросов, или .qls файл набора запросов. Если не указано имя пакета, необходимо указать pathимя пакета, которое будет интерпретировано относительно рабочего каталога текущего процесса. Шаблоны glob не поддерживаются.

Если указать и то scope/name , и pathдругое path не может быть абсолютным. Он считается относительным к корню пакета CodeQL .

Примеры описателей запросов

  • codeql/python-queries — Все запросы в наборе запросов по умолчанию последней codeql/python-queries версии пакета.

  • codeql/python-queries@1.2.3 — Все запросы в наборе запросов по умолчанию версии 1.2.3 codeql/python-queries пакета.

  • codeql/python-queries@~1.2.3 — Все запросы в наборе запросов по умолчанию последней версии codeql/python-queries пакета, >= 1.2.3 и < 1.3.0.

  • codeql/python-queries:Functions — Все запросы в каталоге в Functions последней codeql/python-queries версии пакета.

  • codeql/python-queries@1.2.3:Functions — Все запросы в каталоге Functions в версии 1.2.3 codeql/python-queries пакета.

  • codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls — Все запросы в каталоге codeql-suites/python-code-scanning.qls в версии 1.2.3 codeql/python-queries пакета.

  • suites/my-suite.qls — все запросы в suites/my-suite.qls файле относительно текущего рабочего каталога.

Совет

Набор запросов по умолчанию стандартных пакетов запросов CodeQL codeql-suites/<lang>-code-scanning.qls. Несколько других полезных наборов запросов также можно найти в каталоге codeql-suites каждого пакета. Например, codeql/cpp-queries пакет содержит следующие наборы запросов:

  • cpp-code-scanning.qls — Запросы сканирования стандартного кода для C++. Набор запросов по умолчанию для этого пакета.

  • cpp-security-extended.qls — Запросы из набора по умолчанию cpp-code-scanning.qls для C++, а также запросы с более низкой степенью серьезности и точностью.

  • cpp-security-and-quality.qls — запросы из cpp-security-extended.qls, а также возможности обслуживания и запросов надежности.

Источники этих наборов запросов можно просмотреть в репозитории CodeQL . Наборы запросов для других языков похожи.

Сведения о опубликованных пакетах

При публикации пакета для использования в анализе codeql pack create или codeql pack publish команда проверяет, завершен ли содержимое, а также добавляет в него дополнительные фрагменты содержимого:

  • Для пакетов запросов копия каждого пакета библиотеки, от которой она зависит, в точных версиях, с которыми она была разработана. Пользователям пакета запросов не нужно скачивать эти пакеты библиотек отдельно.

  • Для пакетов запросов предварительно скомпилированные представления каждого из запросов. Они выполняются быстрее, чем компилировать источник QL для запроса при каждом анализе.

Большинство этих данных находятся в каталоге с именем .codeql в опубликованном пакете, но предварительно скомпилированные запросы находятся в файлах с суффиксом .qlx рядом с .ql источником для каждого запроса. При анализе базы данных с запросом из опубликованного пакета CodeQL загружает эти файлы вместо .ql источника. Если необходимо изменить содержимое опубликованного __ пакета, обязательно удалите все .qlx файлы, так как они могут предотвратить изменения в .ql файлах.