Getting started with the CodeQL CLI

Начало работы с CodeQL CLI

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

Настройка CodeQL CLI

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

Если вы используете Linux, Windows или macOS версии 10.14 (Mojave) или более ранней версии, просто выполните указанные ниже действия. Для macOS версии 10.15 ("Catalina") или более поздних версий существуют дополнительные примечания к некоторым шагам. Если вы используете macOS в Apple Silicon (например, Apple M1), убедитесь, что установлены средства командной строки разработчика Xcode и Rosetta 2 .

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

1. Скачайте ZIP-пакет CodeQL CLI

Пакет загрузки CodeQL CLI — это ZIP-архив, содержащий средства, скрипты и различные файлы, относящиеся к CodeQL. Если у вас нет лицензии на GitHub Enterprise, скачав этот архив, вы соглашаетесь с условиями GitHub CodeQL.

Если вы используете Linux, Windows или macOS версии 10.14 (Mojave) или более ранней версии, просто скачайте ZIP-архив для нужной версии.

Если вы хотите использовать интерфейс командной строки для определенной платформы, скачайте соответствующий codeql-PLATFORM.zip файл. Кроме того, можно скачать файл codeql.zip, содержащий CLI для всех поддерживаемых платформ.

Скачивание сведений для пользователей macOS Catalina (или более поздней версии)

Если вы используете macOS версии 10.15 ("Catalina"), версии 11 ("Big Sur") или предстоящей версии 12 ("Монтерей"), необходимо убедиться, что веб-браузер не будет автоматически извлекать ZIP-файлы. Если вы используете Safari, выполните следующие действия перед загрузкой ZIP-архива CodeQL CLI:

1. Откройте Safari.
2. В меню Safari выберите Параметры....
3. Перейдите на вкладку Общие .
4. Убедитесь, что флажок Открыть "безопасные" файлы после скачивания снят.

2. Извлечение ZIP-архива

Для пользователей Linux, Windows и macOS (mojave версии 10.14 и более ранних версий) просто извлеките ZIP-архив.

Сведения о извлечении для пользователей macOS Catalina (или более новых версий)

Пользователям macOS "Catalina", "Big Sur" или "Monterey" следует выполнить следующие команды в терминале, где ${extraction-root} — это путь к каталогу, в который будет извлечен ZIP-архив CodeQL CLI:

1. mv ~/Downloads/codeql\*.zip ${extraction-root}
2. cd ${extraction-root}
3. /usr/bin/xattr -c codeql\*.zip
4. unzip codeql\*.zip

3. Запуск codeql

После извлечения можно запустить процессы CodeQL, запустив исполняемый codeql файл несколькими способами:

• Выполнив , <extraction-root>/codeql/codeqlгде <extraction-root> — это папка, в которую вы извлекли пакет CodeQL CLI.
• Добавив <extraction-root>/codeql в PATH, чтобы можно было запустить исполняемый файл просто как codeql.

На этом этапе можно выполнять команды CodeQL. Полный список команд CodeQL CLI см. в руководстве по CodeQL CLI.

4. Проверьте настройку CodeQL CLI

CodeQL CLI имеет подкоманды, которые можно выполнить, чтобы убедиться, что вы правильно настроены для создания и анализа баз данных:

• Выполните команду codeql resolve languages, чтобы узнать, какие языки доступны для создания базы данных. Будут перечислены языки, поддерживаемые по умолчанию в пакете CodeQL CLI.

• (Необязательно) Вы можете скачать некоторые пакеты "CodeQL", содержащие предварительно скомпилированные запросы, которые вы хотите выполнить. Для этого выполните команду codeql pack download <pack-name> [...pack-name], где pack-name — это имя пакета, который требуется скачать. Базовые пакеты запросов — это хорошее место для начала. К ним относятся:

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

Кроме того, можно скачать пакеты запросов во время анализа с помощью --download флага codeql database analyze команды .

Извлечение исходного кода CodeQL напрямую

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

1. Скачайте ZIP-файл CodeQL CLI

Выполните шаг 1 из предыдущего раздела.

2. Создание каталога CodeQL

Создайте каталог, в котором можно разместить интерфейс командной строки, а также все нужные запросы и библиотеки. Например, $HOME/codeql-home.

Встроенные операции поиска интерфейса командной строки автоматически ищут файлы, используемые при создании и анализе базы данных, во всех каталогах уровня. Хранение этих компонентов в собственном каталоге предотвращает поиск несвязанных одноуровневых каталогов с интерфейсом командной строки, обеспечивая доступность всех файлов без указания дополнительных параметров в командной строке.

3. Получите локальную копию запросов CodeQL

Репозиторий CodeQL содержит запросы и библиотеки, необходимые для анализа CodeQL всех поддерживаемых языков. Клонируйте копию этого репозитория в codeql-home.

По умолчанию корень клонированного репозитория будет называться codeql. Переименуйте эту папку codeql-repo , чтобы избежать конфликта с CodeQL CLI, который будет извлечен на шаге 4. Если вы используете Git в командной строке, вы можете клонировать и переименовать репозиторий за один шаг, выполнив команду git clone git@github.com:github/codeql.git codeql-repo в папке codeql-home .

В этом репозитории запросы и библиотеки организованы в пакеты CodeQL. Вместе с самими запросами пакеты CodeQL содержат важные метаданные, которые сообщают CodeQL CLI, как обрабатывать файлы запросов. Дополнительные сведения см. в разделе Сведения о пакетах CodeQL.

4. Извлечение из ZIP-архива

Для пользователей Linux, Windows и macOS (mojave версии 10.14 и более ранних версий) просто извлеките ZIP-архив в каталог, созданный на шаге 2.

Например, если путь к копии репозитория CodeQL — $HOME/codeql-home/codeql-repo, извлеките cli в $HOME/codeql-home/.

5. Запустите codeql

См . шаг 3 из предыдущего раздела.

6. Проверьте настройку CodeQL CLI

CodeQL CLI имеет подкоманды, которые можно выполнить, чтобы убедиться, что вы правильно настроены для создания и анализа баз данных:

• Выполните команду codeql resolve languages, чтобы узнать, какие языки доступны для создания базы данных. Будут перечислены языки, поддерживаемые по умолчанию в пакете CodeQL CLI.
• Выполните команду codeql resolve qlpacks , чтобы показать, какие пакеты CodeQL может найти CLI. Отобразятся имена всех пакетов CodeQL, непосредственно доступных CodeQL CLI. Сюда должны входить:
• Пакеты запросов для каждого поддерживаемого языка, например codeql/{language}-queries. Эти пакеты содержат стандартные запросы, которые будут выполняться для каждого анализа.
• Пакеты библиотек для каждого поддерживаемого языка, например codeql/{language}-all. Эти пакеты содержат библиотеки запросов, такие как потоки управления и библиотеки потока данных, которые могут быть полезны для записи запросов.
• Примеры пакетов для каждого поддерживаемого языка, например codeql/{language}-examples. Эти пакеты содержат полезные фрагменты CodeQL, которые могут оказаться полезными для записи запросов.
• Устаревшие пакеты, обеспечивающие совместимость пользовательских запросов и библиотек, созданных с помощью старых продуктов, с вашей версией CodeQL.

Использование двух версий CodeQL CLI

Если вы хотите использовать новейшие функции CodeQL для выполнения запросов или тестов CodeQL, но также хотите подготовить базы данных, совместимые с определенной версией CodeQL сканирования кода на GitHub Enterprise Server, может потребоваться установить две версии CLI. Рекомендуемая установка каталога зависит от того, какие версии вы хотите установить:

• Если обе версии — 2.0.2 (или более поздние), вы можете распаковыть оба архива CLI в одном родительском каталоге.
• Если хотя бы одна из версий — 2.0.1 (или более ранняя), распакованые архивы CLI не могут находиться в одном родительском каталоге, но могут совместно использовать один и тот же каталог бабушки и дедушки. Например, если вы распаковываете версию 2.0.2 в $HOME/codeql-home/codeql-cli, более раннюю версию следует распаковать в $HOME/codeql-older-version/old-codeql-cli. Здесь общий бабушка и дедушка является каталогом $HOME .