Как модернизировать движок статического анализа, не путая изменения анализатора с регрессиями приложений.
1. Реальный риск при обновлении CodeQL
Релиз CodeQL может добавлять запросы, улучшать модели потока данных, поддерживать новые языковые версии или снижать ложные срабатывания. Например, CodeQL 2.27.1 добавил запросы на C/C++ и C#, поддержку Kotlin 2.4.20 и несколько улучшений точности. [1]
Это означает, что набор оповещений может изменяться даже при отсутствии фиксации приложения. Добавленное оповещение может выявить реальную проблему, которую пропустил старый анализатор, но также может быть ложноположительным результатом, вызванным изменённой моделью. Удаленное оповещение может означать исправленный ложноположительный результат или выявить утраченное покрытие.
Таким образом, безопасный вопрос — не «Изменилось ли количество оповещений?» Это так:
> Можем ли мы объяснить каждую существенную дельту между старым и новым анализом, сохраняя при этом под контролем исходную версию, входные данные, область запросов и правила обзора?
В этой статье используется практическая схема:
Базовое → параллельное сравнение → триажа Дельта → затвора выпуска
2. Определите контракт на обновление
Перед тем как запускать что-либо, запишите контролируемые входные данные и ожидаемые доказательства сравнения.
| Пункт контракта | Что нужно записать |
|---|---|
| Источник | Репозиторий и точный коммит SHA |
| Окружающая среда | Образ Runner, архитектура, соответствующие версии компилятора или runtime |
| Режим строительства | Нет, автосборка или ручная сборка |
| Оборудование | Комплект CodeQL или версия Action |
| Область запроса | Стандартные, расширенные по безопасности, безопасности и качества или именованные пользовательские пакеты |
| Конфигурация | Конфигурационный файл CodeQL и исключения |
| Результаты | SARIF-файлы, журналы рабочих процессов, диагностика баз данных и дельта-отчеты |
| Владелец решения | Человек или команда, которые принимают, откладывают или блокируют каждую дельту материала |
GitHub рекомендует набор CodeQL, поскольку он содержит совместимый CLI плюс стандартные пакеты запросов и библиотек. [2] [3] Рассматривайте этот пакет, конфигурацию рабочего процесса и любые пользовательские пакеты как один версионный тестовый ассет.
3. Постройте воспроизводимый базовый уровень
Выберите известный коммит и сохраните его SHA. Запустите текущую производственную конфигурацию именно на этой версии и сохраните:
- URL запуска рабочего процесса;
- версию CodeQL Action или комплект;
- выбранные языки и наборы запросов;
- режим сборки и команды сборки, когда используется ручная сборка;
- генерируемый результат SARIF;
- диагностика базы данных и соответствующие журналы извлечения;
- Последнее предупреждение сгруппировано по правилам, степени и языку.
Для скомпилированных языков важен метод создания базы данных. GitHub поддерживает разные режимы сборки, и подходящий режим зависит от языка и проекта. [4] Если текущая производственная система использует ручную сборку, используйте ту же команду сборки и зависимости для сравнения. В противном случае различие в сборке может выглядеть как различие анализатора.
Базовый уровень — это не просто «количество оповещений за прошлую неделю». Это отслеживаемый пакет, который может воспроизвести другой инженер.
4. Сравните старый и новый анализ на одном и том же коде
Создайте временную ветку обновления или изолированный рабочий процесс сравнения. Обе линии должны анализировать один и тот же коммит:
┌─ Current CodeQL configuration ─→ old.sarif
same commit + same inputs
└─ Candidate CodeQL configuration → new.sarifСохраняйте эти входные данные идентичными, если только они не являются явным предметом теста:
- совершить SHA;
- проверить глубину и подмодули;
- операционной системы и архитектуры;
- файлы блокировки зависимостей;
- создавать командные и окружающие переменные;
- политику генерированного кода;
- пути, игнорированные конфигурацией CodeQL;
- Пакеты запросов и пользовательские пакеты.
Сначала измените только кандидат-компонент — например, версию CodeQL bundle. Если версия Action и область запроса также нуждаются в изменениях, проверьте их отдельными шагами. Это облегчает выявление причины каждой дельты.
Для расширенной настройки GitHub Actions используйте поддерживаемую основную версию github/codeql-action. Проект в настоящее время рекомендует v4, а также советует командам, которые закрепляют патч-версию или фиксируют SHA, сохранять этот пин. [5]
Минимальная форма рабочего процесса выглядит так:
- uses: github/codeql-action/init@v4
with:
languages: java-kotlin
queries: security-extended
# Use autobuild or your documented manual build step here.
- uses: github/codeql-action/analyze@v4
with:
output: ../results
upload: neverЭто структурный пример, а не универсальная конфигурация. Используйте языковую матрицу, режим сборки, разрешения и область запроса, соответствующие репозиторию.
5. Создайте стабильную дельту
Результаты SARIF содержат больше, чем сообщение и номер строки. Полезный ключ сравнения должен предпочитать стабильные идентификаторы, такие как:
- идентификатор правила;
- результаты отпечатков пальцев или частичных отпечатков пальцев, когда они доступны;
- нормализованный URI артефакта;
- логическое местонахождение;
- регион как запасной вариант, а не единственная идентичность;
- Серьёзность безопасности и уровень результата.
Компактный отчёт может выглядеть так:
| Дельта | Правило | Расположение | Старое → новое | Результаты обзора |
|---|---|---|---|---|
| Добавлено | cpp/example-rule | src/net.cpp | ни → высокого | Подтверждённая проблема |
| Удалено | java/example-rule | src/db.java | Высокий → нет | Исправление запроса проверено |
| Изменено | actions/example-rule | .github/workflows/ci.yml | средний → высокий | Ожидаемое обновление модели |
| Несравненный | Правило обычая | Функция перемещена | Отпечаток пальца изменился | Требуется ручная корреляция |
Не полагайтесь только на общее количество уведомлений. Пять удалённых и пять добавленных уведомлений дают чистое изменение в нуле, представляя десять решений по пересмотру.
6. Отсортируйте все категории материалов
Добавленные находки
Для каждого нового результата спрашивайте:
- Добавил ли релиз или изменил соответствующий запрос или модель потока данных?
- Действительно ли путь кода доступен?
- Может ли небольшой прибор или тест воспроизвести указанный поток?
- Результат появляется только потому, что покрытие извлечением улучшилось?
- Является ли подавление оправданным, задокументированным и узким масштабом?
Удаленные находки
Удалённый результат требует не меньше внимания:
- Был ли старый результат известным ложноположительным?
- В примечаниях к релизу описывалось исправление точности этого правила?
- Соответствующий файл всё ещё присутствует в базе данных кандидатов?
- Старый запрос всё ещё сообщает о проблеме при работе с сопоставимыми данными?
- Был ли результат скрыт из-за изменения конфигурации или в наборе запросов?
Изменённые находки
Проверьте изменения в степени тяжести, пути, регионе, сообщении или классификации. Некоторые из них — это улучшения презентации; другие могут повлиять на политические ворота или маршрутизацию владения.
Несоответствующие находки
Отпечатки пальцев могут меняться при перемещении кода или эволюции моделей анализа. Сохраняйте категорию «несоответствия», а не навязывайте добавлять или удалять каждый результат. Затем рецензент может коррелировать по правилам, функциям и пути потока данных.
7. Проверьте покрытие извлечения и конфигурации
Чистая дельта не имеет значения, если кандидат анализировал меньше кода.
Хотя бы проверьте:
- Все ожидаемые языковые вакансии выполнялись;
- создание базы данных завершено без отказа экстрактора;
- ручные шаги сборки собирали целевые цели;
- Корни источника и игнорированные пути не изменились случайно;
- сгенерированный код и тестовый код следуют задокументированной политике;
- пользовательские пакеты запросов успешно разрешались;
- завершена загрузка результатов или создание артефактов;
- Предупреждения в диагностике баз данных были пересмотрены.
Для большого репозитория выберите несколько известных «sentinel» файлов или намеренно уязвимых тестовых фикстуров. Ожидаемые результаты быстро дают понять, что кандидат всё ещё анализирует критические пути.
Не публикуйте реальные уязвимости в публичных устройствах. Используйте синтетические примеры в контролируемом тестовом репозитории.
8. Защитите пользовательские запросы
Кастомные пакеты являются частью регрессионной поверхности. Тестируйте их независимо перед принятием обновления:
- разрешить точные версии паков;
- запускать
codeql pack installиз каталога паков; - компилировать или протестировать пользовательские запросы;
- выполнять их тесты запросов, где это возможно;
- анализировать хотя бы одну репрезентативную базу данных;
- Сравните ожидаемый набор результатов с базовым уровнем.
Пакеты CodeQL используют семантические диапазоны версий зависимостей, а файл блокировки фиксирует разрешённые зависимости. [6] Проверяйте изменения в блокировочном файле как и любое другое обновление зависимостей. Неожиданно расширенный диапазон зависимостей может сделать будущие запуски менее воспроизводимыми.
9. Проектирование гейтов выпуска по риску
Гейт запрос на слияние
Используйте лейн кандидатов в выделенном pull request-приложении на улучшения.
Блокируйте слияние, когда:
- создание или анализ базы данных не удаётся;
- отсутствует ожидаемый язык или критический путь;
- пользовательский пакет больше не разрешается или его тесты не проходят;
- новый результат высокой тяжести не имеет решения о сортировке или владельце;
- ранее подтверждённый результат высокой тяжести исчезает без объяснения.
Запланированное сравнение
Выполняйте работу параллельно по графику во время оценки обновления. Это фиксирует изменения в репозитории, которые выявляют пробелы, отсутствующие в первом сравнении. Сохраняйте тот же контракт сравнения и маркируйте полученные отчёты по коммиту SHA.
Предрелизный гейт
Перед продвижением конфигурации кандидатов:
- повторите сравнение с кандидатом на релиз;
- закрыть или явно принять каждую дельту материала;
- подтверждение необходимых проверок статуса и разрешений;
- архивировать отчёты и ссылки на рабочий процесс;
- записывайте версию отката и шаги отката;
- получите необходимое подтверждение безопасности или QA.
Пороги, такие как «не более чем на 2% меньше извлечённых файлов», могут быть полезными предупреждающими сигналами, но они зависят от конкретных проектов. Не приводите иллюстративный порог как отраслевой стандарт.
10. Обработка отказов и откат
Рабочий процесс сравнения должен работать безопасно.
- Если одна полоса не проходит, отметьте сравнение неокончательное, не пропущено.
- Если парсер SARIF не работает, сохраняйте оба raw артефакта и остановите гейт.
- Если кандидат не может разрешить пакет запросов, не возвращайтесь молча к другой версии.
- Если сборка не детерминирована, повторите обе полосы перед классификацией дельт.
- Если регрессия материала не может быть объяснена, оставьте анализатор производства без изменений.
Откат должен восстановить предыдущую протестированную конфигурацию, а не просто снизить порог оповещений.
11. Контрольный список QA
Воспроизводимость
- [ ] Одинаковый коммит SHA в обеих полосах
- [ ] Та же семья бегунов и архитектура
- [ ] Одинаковые файлы зависимостей с блокировкой
- [ ] Тот же режим сборки и команда
- [ ] Записанные версии с инструментами и пакетами запросов
Покрытие
- [ ] Ожидаемые задания, выполненные языковые работы
- [ ] Анализ диагностики базы данных
- [ ] Файлы или приборы Сентинела предоставили ожидаемые доказательства
- [ ] Игнорируйте пути и политику сгенерированного кода без изменений
- [ ] Кастомные пакеты прошли тесты
Обзор изменений
- [ ] Добавленные результаты проанализированы
- [ ] Удалённые результаты проанализированы
- [ ] Рассмотрены изменения степени и местоположения
- [ ] Несовпадающие отпечатки результатов исследованы
- [ ] Ложноположительные срабатывания и исключения задокументированы
Контроль выпуска
- [ ] Проверка pull request пройдена
- [ ] Плановое сравнение успешно выполнено на актуальном коммите
- [ ] Сравнение релиз-кандидата сохранено
- [ ] Владелец решения одобрил оставшийся риск
- [ ] Версия с откатом и записанные шаги
12. Что должна — и чего не должна — решать автоматизация
Автоматизация отлично подходит для создания сопоставимых баз данных, нормализации SARIF, расчёта дельт, прикрепления артефактов и обеспечения необходимости доказательств.
Автоматизация не должна решать, что каждое добавленное оповещение является дефектом продукта или что каждое удалённое оповещение безопасно. Эти решения требуют контекста: изменения запросов, доступность, возможность эксплуатации, предполагаемая конфигурация и принятый риск проекта.
Финальные ворота должны сочетать контракты, проверяемые машинами, с решением по сортировке, принадлежащему человеку.
Заключение
Обновление CodeQL — это изменение самой тестовой системы. Тестируйте её как любую другую производственную зависимость: управляйте входными данными, сравнивайте старое и новое поведение на том же коде, проверяйте покрытие, проверяйте пользовательские пакеты и требуйте объяснимые доказательства перед продвижением.
С помощью повторяемого процесса Базовая линия → Параллельное сравнение → Анализ изменений → Контроль выпуска команды могут внедрять улучшения анализаторов, не скрывая реальные дефекты и не создавая избыточный шум оповещений.
Источники
- GitHub Changelog — CodeQL 2.27.1 adds C and C++ query and Kotlin 2.4.20 support: https://github.blog/changelog/2026-09-25-codeql-2-27-1-adds-c-and-c-query-and-kotlin-2-4-20-support/
- CodeQL documentation — CodeQL tools and the CodeQL bundle: https://codeql.github.com/docs/codeql-overview/codeql-tools/
- CodeQL CLI documentation — Setting up the CodeQL CLI: https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli
- GitHub Docs — CodeQL code scanning for compiled languages: https://docs.github.com/en/code-security/concepts/code-scanning/codeql/codeql-for-compiled-languages
- GitHub — CodeQL Action README and supported versions: https://github.com/github/codeql-action/blob/main/README.md
- CodeQL CLI documentation — Creating and working with CodeQL packs: https://docs.github.com/en/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs
Оставить комментарий
Поделитесь своим мнением о статье. Регистрация не требуется.
Комментарии
Загрузка комментариев…