Настройка расширенной настройки сканирования кода с CodeQL масштабе - Документация GitHub

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

CodeQL позволяет разработчикам создавать специализированные запросы на языке запросов CodeQL, чтобы найти конкретные проблемы в своем коде. Но что, если вы хотите провести более широкий анализ кодовой базы вашего проекта? Что делать, если вы хотите включить CodeQL в свой рабочий процесс CI/CD? Для этого GitHub предлагает расширенную настройку сканирования кода с использованием CodeQL.

Примечание: Расширенная настройка сканирования кода с CodeQL доступна только для пользователей GitHub Enterprise Server.

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

Создание файлов настроек

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

.query-languages.yml: Этот файл определяет список языков программирования, которые вы хотите анализировать с помощью CodeQL. Вы можете указать языки программирования, используя их идентификаторы, такие как 'cpp' для C++ или 'java' для Java. Этот файл является обязательным.

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

.qlpath: Этот файл определяет пути, в которых CodeQL будет искать дополнительные библиотеки с запросами. Если вы создали свои собственные запросы или используете сторонние библиотеки CodeQL, вы можете указать пути к ним в этом файле. Этот файл является необязательным.

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

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

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

Создание файла конфигурации

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

Файл конфигурации должен иметь имя .github/codeql.yml и находиться в корневом каталоге репозитория. Он может содержать следующие настройки:

• queries: в этом разделе указываются пути к файлам с запросами CodeQL, которые будут использоваться при анализе кода. Пути должны быть относительными к корневому каталогу репозитория. Можно указывать как отдельные файлы, так и целые директории.
• languages: в этом разделе указываются языки программирования, которые будут анализироваться. Для каждого языка необходимо указать путь к файлу основной конфигурации CodeQL.
• build: в этом разделе указываются дополнительные настройки для сборки проекта перед анализом кода. Например, можно указать команду для установки зависимостей или настройки переменных окружения.

Пример файла конфигурации:

queries:
- path/to/query.ql
- path/to/directory/with/queries
languages:
- language: javascript
variant: javascript/ql/src/codeql-suites/codeql-javascript.qls
build:
install:
- npm ci

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

Создание файла правил

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

Файл правил должен быть написан на языке QL (Query Language) - языке запросов, который используется в CodeQL. В этом файле вы можете определить свои собственные правила или использовать готовые правила из общедоступной библиотеки.

В файле правил вы можете определить несколько типов правил:

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

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

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

Создание файла фильтров

Вы можете создать специальный файл фильтров для исключения нежелательных файлов или директорий из процесса сканирования. Файл фильтров поможет ускорить сканирование и сосредоточиться только на нужных частях кода.

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

Например, чтобы исключить все файлы конфигурации из сканирования, вы можете добавить следующую строку в .qlignore:

*.config

Это шаблон будет игнорировать все файлы с расширением .config. С помощью файлов фильтров вы можете определить собственные правила исключения для вашего проекта.

Настройка параметров сканирования

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

В настройках сканирования вы можете указать следующие параметры:

• Языки программирования: выберите языки программирования, на которых основан ваш проект. CodeQL поддерживает широкий спектр языков, включая Java, C#, C++, Python и другие.
• Области исследования: укажите, какие аспекты вашего кода должны быть проверены на наличие уязвимостей. Например, вы можете выбрать проверку SQL-инъекций, уязвимости безопасности сетевого соединения или возможности отказа в обслуживании.
• Правила проверки: задайте набор правил, по которым будет производиться проверка вашего кода. CodeQL предоставляет множество стандартных правил, а также возможность создания собственных правил.
• Отчетность и анализ: определите форматы отчетов и методы анализа результатов сканирования. Вы можете настроить создание XML-, JSON- или HTML-отчетов, а также использовать автоматический анализ результатов.

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

Установка целей сканирования

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

Есть несколько способов установки целей сканирования:

• Глобальные цели: цели, которые применяются ко всем проектам в организации. Они могут быть определены в общем файле конфигурации для CodeQL.
• Цели проекта: цели, которые применяются только к конкретному проекту. Они могут быть определены в файле конфигурации проекта и переопределять глобальные цели в случае необходимости.
• Цели файлов: цели, которые применяются только к определенным файлам или директориям в проекте. Они могут быть определены в файле конфигурации проекта и переопределять как глобальные, так и цели проекта.

Для указания целей сканирования в файле конфигурации можно использовать специальный синтаксис, например:

В этом примере определены две цели сканирования: src/ для кода на языке Java и tests/ для тестового кода на языке Java.

При настройке целей сканирования следует учесть следующие факторы:

• Необходимо определить цели сканирования для всех частей кода, которые требуется проверить.
• Цели сканирования должны быть точными и покрывать только нужные файлы и директории, чтобы избежать ненужного сканирования и ускорить процесс анализа кода.
• В случае необходимости можно использовать различные цели для разных типов кода (например, разные цели для исходного кода и тестового кода).

Установка целей сканирования является важным шагом при настройке расширенной настройки сканирования кода с CodeQL масштабе. Правильно определенные и настроенные цели сканирования позволят получить максимально точный результат анализа кода и выявить потенциальные уязвимости и ошибки.

Настройка уровня анализа

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

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

• Базовый уровень: При этом уровне анализа происходит быстрая проверка кода на наличие распространенных потенциально уязвимых мест. Результаты анализа представляются в виде основных метрик без дополнительной информации.
• Средний уровень: На этом уровне анализа проводится более глубокий анализ вашего кода, чтобы выявить распространенные уязвимости и проблемы безопасности. Он включает в себя расширенные метрики и дополнительные подсказки.
• Расширенный уровень: Этот уровень анализа предоставляет наиболее полную информацию о потенциальных уязвимостях и проблемах безопасности в вашем коде. Включает в себя подробные отчеты, рекомендации по устранению проблем и ресурсы для дополнительного изучения.

Для настройки уровня анализа вы можете использовать файл конфигурации .codeql, в котором можно указать предпочитаемый уровень анализа для каждого проекта или репозитория. Это позволит вам получить наиболее релевантные результаты анализа соответственно вашим потребностям.

Уровень анализа можно указать, используя ключ analysisLevel в файле .codeql:

configuration:
analysisLevel: расширенный

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

Управление временными файлами

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

По умолчанию, временные файлы генерируются во временной директории на вашей системе. Однако, вы можете настроить следующие параметры для управления временными файлами:

• codeql.tempDir: указывает путь к временной директории, где будут сохраняться временные файлы.
• codeql.tempDirPrefix: задает префикс для имени временной директории.
• codeql.tempDirSuffix: задает суффикс для имени временной директории.
• codeql.keepTemp: указывает, нужно ли сохранять временные файлы после завершения сканирования. Если этот параметр установлен в "true", временные файлы будут сохранены. Если параметр установлен в "false", временные файлы будут удалены.

Чтобы настроить эти параметры, вы можете изменить файл .codeqlrc, добавив соответствующие настройки в секцию "scanning.tempDir".

Управление временными файлами позволяет вам иметь больше контроля над вашими ресурсами и упрощает процесс управления результатами сканирования.

Интеграция с системами контроля версий

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

Для интеграции CodeQL с системой контроля версий необходимо выполнить несколько шагов. Во-первых, создайте проект CodeQL и настройте его для работы с выбранной системой. Затем укажите ссылку на репозиторий, в котором хранится ваш код. После этого выполните настройку для выбора конкретных файлов и директорий, которые вы хотите сканировать.

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

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