Установка CodeQL CLI в системе непрерывной интеграции

Сведения о создании результатов сканирования кода с помощью CodeQL CLI

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

Для создания результатов и их отправки в GitHub используются три разных команды:

1. database create для создания базы данных CodeQL для представления иерархической структуры каждого поддерживаемого языка программирования в репозитории.
2. database analyze для выполнения запросов по анализу каждой базы данных CodeQL и суммирования результатов в файле SARIF.
3. github upload-results для загрузки полученных файлов SARIF в GitHub, где результаты сопоставляются с ветвью или запросом на вытягивание и отображаются в виде оповещений code scanning.

Вы можете отобразить справку командной строки для любой команды, используя параметр --help.

Создание баз данных CodeQL для анализа

1. Извлеките код, который нужно проанализировать:

   • Для ветви извлеките заголовок ветви, которую необходимо проанализировать.
   • Для запроса на вытягивание извлеките фиксацию заголовка запроса на вытягивание или фиксацию слияния запроса на вытягивание, сгенерированную с помощью GitHub.

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

3. Найдите команду сборки (если таковая имеется) для базы кода. Обычно она доступна в файле конфигурации в системе CI.

4. Запустите codeql database create из корня извлечения вашего репозитория и выполните сборку базы кода.

   # Single supported language - create one CodeQL database
   codeql database create <database> --command<build> --language=<language-identifier>
   
   # Multiple supported languages - create one CodeQL database per language
   codeql database create <database> --command<build> \
         --db-cluster --language=<language-identifier>,<language-identifier>

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

Дополнительные сведения см. в разделе Создание базы данных CodeQL.

Пример использования одного языка

В этом примере создается база данных CodeQL для репозитория, извлеченного в папку /checkouts/example-repo. Он использует средство извлечения JavaScript для создания иерархического представления кода JavaScript и TypeScript в репозитории. Результирующая база данных хранится в /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Пример с несколькими языками

В этом примере создаются две базы данных CodeQL для репозитория, извлеченного в папку /checkouts/example-repo-multi. Он использует следующую информацию:

• --db-cluster для запроса анализа более чем одного языка.
• --language для указания, для каких языков следует создавать базы данных.
• --command, чтобы сообщить инструменту команду сборки для базы кода. Здесь это make.
• --no-run-unnecessary-builds чтобы сообщить инструменту о необходимости пропустить команду сборки для языков, где она не требуется (например, Python).

Результирующие базы данных хранятся в подкаталогах python и cpp в /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Анализ базы данных CodeQL

1. Создайте базу данных CodeQL (см. выше).
2. Запустите codeql database analyze в базе данных и укажите, какие пакеты и (или) запросы нужно использовать.

   codeql database analyze <database> --format=<format> \
       --output=<output>  --download <packs,queries>

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Дополнительные сведения см. в статье Анализ баз данных с помощью CodeQL CLI".

Базовый пример анализа базы данных CodeQL

В этом примере анализируется база данных CodeQL, хранящаяся в папке /codeql-dbs/example-repo, и результаты сохраняются в виде файла SARIF: /temp/example-repo-js.sarif. Он использует --sarif-category, чтобы включить в файл SARIF дополнительные сведения, определяющие результаты в виде JavaScript. Это критически важно при наличии нескольких баз данных CodeQL для анализа отдельной фиксации в репозитории.

$ codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Загрузка результатов в GitHub

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

Перед отправкой результатов в GitHub необходимо определить оптимальный способ передачи созданных ранее GitHub App или personal access token в CodeQL CLI (см. раздел Установка CodeQL CLI в системе CI). Рекомендуется проанализировать руководство по использованию системы CI для безопасного использования хранилища секретов. CodeQL CLI поддерживает следующие действия:

• Передача маркера в CLI через стандартный ввод с помощью параметра --github-auth-stdin (рекомендуется).
• Сохранение секрета в переменной среды GITHUB_TOKEN и запуск интерфейса командной строки без включения параметра --github-auth-stdin.

Если вы выбрали наиболее безопасный и надежный метод для сервера CI, выполните команду codeql github upload-results в каждом файле результатов SARIF и включите --github-auth-stdin, если только маркер не доступен в переменной среды GITHUB_TOKEN.

echo "$UPLOAD_TOKEN" | codeql github upload-results --repository=<repository-name> \
      --ref=<ref> --commit=<commit> --sarif=<file> \
      --github-auth-stdin

Дополнительные сведения см. в статье Результаты загрузки GitHub в документации по CodeQL CLI.

Базовый пример отправки результатов в GitHub

В этом примере выполняется загрузка результатов из файла SARIF temp/example-repo-js.sarif в репозиторий my-org/example-repo. Для API code scanning сообщается, что результаты необходимы для фиксации deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 в ветви main.

$ echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

Эта команда ничего не выводит, если загрузка не удалась. Командная строка возвращается после завершения загрузки и начала обработки данных. В небольших базах кода вскоре после этого вы сможете изучить оповещения code scanning в GitHub. Оповещения можно просмотреть непосредственно в запросе на вытягивание или на вкладке Безопасность для ветвей в зависимости от извлеченного кода. Дополнительные сведения см. в разделах Рассмотрение оповещений проверки кода в запросах на вытягивание и Управление оповещениями проверки кода для репозитория.

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

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

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

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

В этом примере выполняется команда 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

Это пример серии команд, которые можно использовать для анализа базы кодов с двумя поддерживаемыми языками, а затем загрузить результаты в GitHub.

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif --github-auth-stdin

# Upload the SARIF file with the Python results: 'python-results.sarif'

echo $UPLOAD_TOKEN | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif --github-auth-stdin

Устранение неполадок CodeQL CLI в системе CI

Просмотр журналов и сведений по диагностике

При анализе базы данных CodeQL с помощью набора запросов code scanning в дополнение к созданию подробной информации об оповещениях интерфейс командной строки сообщает диагностические данные с этапа создания базы данных и сводные метрики. Для репозиториев с небольшим количеством предупреждений эта информация может оказаться полезной для определения того, действительно ли в коде мало проблем или возникали ли ошибки при создании базы данных CodeQL. Для более подробного вывода из codeql database analyze используйте параметр --verbose.

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

отображает только результаты анализа на одном из проанализированных языков

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

Если вы хотите загрузить более одного набора результатов в API code scanning для фиксации в репозитории, необходимо идентифицировать каждый набор результатов как уникальный. Для репозиториев, в которых вы создаете более одной базы данных CodeQL для анализа каждой фиксации, используйте параметр --sarif-category, чтобы указать язык или другую уникальную категорию для каждого файла SARIF, который вы создаете для этого репозитория.

Проблемы с извлечением Python

Мы не рекомендуем использовать поддержку Python 2 для CodeQL CLI, в частности для этапа создания базы данных CodeQL (извлечение кода).

Если вы используете CodeQL CLI для запуска CodeQL code scanning в коде, написанном на Python, необходимо убедиться, что в системе CI установлен Python 3.

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

• Создание базы данных CodeQL
• Анализ баз данных с помощью CodeQL CLI
• Публикация и использование пакетов CodeQL