Объявление GitHub об отказе от универсального пакета CodeQL напоминает о важном принципе: обновление сканирования безопасности — это не просто смена версии зависимости. CodeQL Action, пакет CLI, пакеты запросов, платформа раннера, режим сборки и разрешения на загрузку результатов образуют единую систему. Если одна из этих границ меняется, успешно завершившийся рабочий процесс всё равно может скрывать пропущенные языки, изменившиеся результаты или неполные доказательства.
В статье представлен практический QA-подход для расширенной настройки CodeQL. Стандартная настройка на раннерах GitHub в основном управляется самим GitHub. Наиболее веские доказательства при миграции нужны командам, которые закрепляют версии инструментов, используют собственные пакеты, собственные раннеры или расширенные рабочие процессы.
1. Разделите изменяемые компоненты
Перед изменением рабочего процесса разграничьте следующие компоненты:
- Версия CodeQL Action управляет интеграцией с рабочим процессом. Сейчас GitHub указывает
v4как последнюю поддерживаемую основную версию, аv3— как ещё поддерживаемую. В расширенных настройках обычно следует использовать поддерживаемый тег основной версии либо намеренно сопровождать закреплённую ревизию. - Версия CodeQL CLI и пакета определяет анализатор и набор инструментов, используемых при запуске. Она не совпадает с версией CodeQL Action.
- Пакеты запросов содержат запросы и библиотеки для отдельных языков. Пользовательская конфигурация может добавлять зависимости, которых нет в стандартном наборе.
- Платформа раннера включает операционную систему, архитектуру процессора, установленные инструменты сборки, сетевой доступ и состояние кеша.
- Режим сборки определяет, как CodeQL создаёт базу данных. Режимы
none,autobuildиmanualподдерживают разные языки и связаны с разными рисками; правильный выбор зависит от репозитория. - Загрузка SARIF публикует результаты анализа в системе сканирования кода. Успешный анализ без ожидаемой загрузки, категории или разрешений не является полноценным результатом для продуктивной среды.
Объявление об универсальном пакете касается способа распространения. Оно не означает, что во всех репозиториях необходимо одинаково менять рабочие процессы. Сначала задокументируйте фактически используемую конфигурацию.
2. Проведите инвентаризацию текущей настройки
Создайте краткую запись о миграции для каждого рабочего процесса CodeQL:
- Зафиксируйте все ссылки
github/codeql-action/*и укажите, используют ли они тег основной версии, тег релиза или SHA коммита. - Зафиксируйте входной параметр
tools, если он используется, и другие способы явного выбора версии CodeQL. - Зафиксируйте метки и архитектуры раннеров, включая собственные раннеры.
- Укажите анализируемые языки и режим сборки для каждого языка.
- Укажите пользовательские файлы конфигурации, наборы запросов, пакеты моделей и загружаемые пакеты.
- Зафиксируйте разрешения рабочего процесса, категории SARIF, сроки хранения артефактов и зависимости от правил защиты ветвей.
- Зафиксируйте сетевые ограничения, прокси-серверы, зеркала и кеши, участвующие в загрузке пакетов CodeQL или пакетов запросов.
Такая инвентаризация предотвращает распространённую ошибку: команда тестирует упрощённый пример, хотя продуктивная среда зависит от пользовательского пакета запросов или раннера с ограничениями.
3. Создайте сопоставимую базовую версию
Запустите существующую конфигурацию на фиксированном коммите и сохраните достаточно доказательств, чтобы впоследствии объяснить различия. Зафиксируйте:
- Итоговый статус рабочего процесса и отдельных шагов.
- Версии CodeQL Action и CodeQL, указанные в журналах.
- Фактически инициализированные языки и режимы сборки.
- Успешность создания базы данных и завершения анализа.
- Файлы SARIF или категории загруженных результатов.
- Идентификаторы предупреждений и затронутые участки кода с группировкой по правилу и серьёзности.
- Время выполнения, поведение при загрузке и релевантные сведения о кеше.
- Журналы и хеши артефактов, необходимые для воспроизведения сравнения.
Не используйте полное совпадение количества предупреждений как единственный критерий приёмки. Новая версия анализатора или пакета запросов может обоснованно добавлять, удалять или переклассифицировать результаты. Важно понять каждое различие и определить, является ли оно приемлемым.
4. Запустите контролируемую конфигурацию-кандидат
По возможности используйте для кандидата тот же коммит, конфигурацию, тестовые данные и класс раннера. Изменяйте только одну переменную миграции за раз. Начните с неблокирующей ветви или канареечного запуска по расписанию, сравните доказательства и только затем меняйте обязательную проверку в продуктивной среде.
Компактный канареечный рабочий процесс с расширенной настройкой может сохранять SARIF без публикации:
name: CodeQL canary
on:
workflow_dispatch:
permissions:
contents: read
jobs:
analyze:
continue-on-error: true
runs-on: ubuntu-latest
strategy:
matrix:
language: [javascript-typescript, python]
steps:
- uses: actions/checkout@v4
- uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
- uses: github/codeql-action/analyze@v4
with:
category: "/language:${{ matrix.language }}"
output: sarif-results
upload: never
- uses: actions/upload-artifact@v4
if: always()
with:
name: codeql-sarif-${{ matrix.language }}
path: sarif-resultsЭтот фрагмент намеренно неполон: для компилируемых языков может потребоваться autobuild или явно заданная команда сборки, а рабочему процессу в продуктивной среде может понадобиться разрешение security-events: write. Канареечная проверка должна воспроизводить реальную конфигурацию репозитория, а не слепо копировать универсальный пример.
5. Определите критерии приёмки до продвижения
Миграция готова только тогда, когда собранные доказательства соответствуют критериям, согласованным командами безопасности, разработки и QA. Практический контрольный набор включает следующие условия:
- Каждый обязательный язык успешно инициализируется и создаёт базу данных.
- Ожидаемые наборы запросов и пользовательские пакеты успешно разрешают зависимости.
- SARIF создаётся для каждого предусмотренного элемента матрицы.
- Новые, исчезнувшие или изменившиеся результаты прошли триаж и получили объяснение.
- Архитектура раннера и выбранный для загрузки пакет соответствуют целевой среде.
- Время выполнения и потребление ресурсов остаются в пределах документированного бюджета команды.
- Необходимые разрешения на загрузку и категории проверены в контролируемом интеграционном запуске.
- Журналы и артефакты не содержат секретов или ненужных данных исходного кода.
- Целевая версия для отката известна и по-прежнему доступна.
- Специалист одобрил результаты сравнения, а не только зелёный индикатор статуса.
6. Безопасно проверьте негативные сценарии
Негативное тестирование следует проводить в одноразовом репозитории, на изолированном раннере или в конфигурации пробного запуска. Не нарушайте намеренно работу процесса в продуктивной среде сканирования безопасности.
- Выберите неподдерживаемую или недоступную версию инструмента и убедитесь, что настройка завершается с ошибкой и предоставляет полезные диагностические данные.
- Проверьте архитектуру раннера, для которой невозможно получить ожидаемый артефакт выпуска, используя контролируемую сетевую заглушку вместо изменения URL продуктивной среды.
- Подключите несовместимый пользовательский пакет и убедитесь, что сообщение об ошибке указывает на проблему разрешения пакета.
- Заблокируйте загрузку в изолированном сетевом тесте и убедитесь, что рабочий процесс не сообщает об успехе и не использует повторно непроверенный артефакт.
- Удалите
security-events: writeиз тестового рабочего процесса и убедитесь, что попытка загрузки завершается ошибкой, а локальный файл SARIF остаётся доступным для анализа. - Повредите или пропустите ожидаемый шаг сборки и убедитесь, что ошибка создания базы данных или анализа хорошо заметна.
- Запустите два элемента матрицы с разными категориями и убедитесь, что их результаты не объединяются без уведомления.
Точный текст ошибки не является стабильным контрактом. Проверяйте категорию сбоя, завершившийся ошибкой шаг, сохранённые диагностические данные и отсутствие ложного сигнала об успехе.
7. Где помогает автоматизация
Автоматизация полезна для повторяемого сбора и сравнения данных:
- Сохраняйте метаданные рабочего процесса и версии анализатора в машиночитаемом манифесте.
- Нормализуйте SARIF и сравнивайте правила, отпечатки, участки кода и уровни серьёзности.
- Проверяйте, что для каждого ожидаемого языка и категории создан артефакт.
- Контролируйте сроки хранения доказательств и проверяйте загруженные журналы на наличие секретов.
- Выявляйте неожиданное увеличение времени выполнения или объёма загрузки.
- Создавайте задачу для проверки при изменении результатов.
Экспертная оценка остаётся необходимой. Новое предупреждение может быть ценным улучшением обнаружения, а исчезнувшее — опасной регрессией. Одного количества результатов недостаточно ни для одного из этих выводов.
8. Пять вопросов для рецензента
- Какой компонент CodeQL изменился: Action, пакет CLI, пакет запросов, раннер, режим сборки или разрешения?
- Создана ли базовая версия на том же коммите и в репрезентативной среде раннера?
- Можно ли связать каждый изменившийся результат с правилом, участком кода и артефактом кандидата?
- Были ли охвачены пользовательские пакеты, собственные раннеры и сценарии с ограниченным сетевым доступом?
- Возможен ли откат без возврата к уже неподдерживаемой конфигурации?
9. Руководство по устранению неполадок
- Не удаётся загрузить пакет: проверьте платформу раннера, сетевую политику, прокси-сервер, выбранное значение
toolsи доступные артефакты текущего релиза. - Исчез язык: проверьте идентификатор языка, формирование элементов матрицы, поддержку режима сборки и журналы инициализации базы данных.
- Собственные запросы завершаются ошибкой: проверьте зависимости пакета и протестируйте тот же файл конфигурации, который используется в продуктивной среде.
- Файл SARIF существует, но предупреждения не отображаются: проверьте настройку
upload, разрешения, значенияcategory, доступность сканирования кода для репозитория и журналы загрузки. - Изменилось количество предупреждений: сравните записи SARIF по правилам и участкам кода; не скрывайте различия изменением базовой версии.
- Канареечная проверка выполняется дольше: прежде чем определять причину, отдельно измерьте время загрузки, сборки, создания базы данных, выполнения запросов и публикации результатов.
10. Чек-лист релиза
- Инвентаризация проверена и сохранена вместе с изменением.
- Базовая версия и кандидат используют один и тот же репрезентативный коммит.
- Проверены обязательные языки, раннеры, режимы и пользовательские пакеты.
- Различия SARIF прошли триаж квалифицированного специалиста.
- Негативные сценарии блокируют продвижение при сбое и сохраняют диагностические данные.
- Разрешения и категории загрузки проверены.
- Бюджеты времени выполнения и ресурсов согласованы.
- Секреты и конфиденциальные данные исходного кода исключены из доказательств.
- Целевая версия и ответственный за откат задокументированы.
- После продвижения в продуктивную среду выполнена минимальная проверка работоспособности.
Заключение
Самая безопасная миграция CodeQL основана на доказательствах. Рассматривайте изменение пакета как изменение средства контроля безопасности: определите границы, сравните фиксированную базовую версию с контролируемым кандидатом, проверьте сценарии сбоев и сохраните артефакты, которые сможет изучить другой специалист. Автоматизация собирает доказательства, а люди решают, приемлемо ли изменившееся поведение системы безопасности.
Оставить комментарий
Поделитесь своим мнением о статье. Регистрация не требуется.
Комментарии
Загрузка комментариев…