Як оновити рушій статичного аналізу, не плутаючи зміни аналізатора з регрессіями застосунків.


1. Реальний ризик оновлення CodeQL

Реліз CodeQL може додавати запити, покращувати моделі потоків даних, підтримувати нові мовні версії або зменшувати хибнопозитивні результати. Наприклад, CodeQL 2.27.1 додав запити C/C++ та C#, підтримку Kotlin 2.4.20 та кілька покращень точності. [1]

Це означає, що набір сповіщень може змінюватися навіть тоді, коли додаток не фіксує. Додане сповіщення може виявити реальну проблему, яку пропустив старий аналізатор, але також може бути хибнопозитивним результатом, спричиненим зміненою моделлю. Видалене сповіщення може означати виправлений хибний позитив або виявити втрату покриття.

Отже, безпечне питання — не «Чи змінилася кількість сповіщень?» Це таке:

> Чи можемо ми пояснити кожну суттєву дельту між старим і новим аналізом, зберігаючи під контролем ревізію вихідного коду, вхідні дані для побудови, обсяг запитів і правила огляду?

У цій статті використовується практична схема:

Базове → паралельне порівняння → тріажі Delta → Release Gate


2. Визначити договір про оновлення

Перед тим, як запускати щось, запишіть контрольовані дані та докази, які очікуються від порівняння.

Пункт контрактуЩо потрібно записати
ДжерелоРепозиторій і точний коміт SHA
Навколишнє середовищеОбраз Runner, архітектура, відповідні версії компілятора або виконання
Режим будівництваЖодного, автозбірки чи ручного збірки
ІнструментиCodeQL bundle або версія Action
Обсяг запитуПакети за замовчуванням, з розширенням безпеки, безпеки та якості або іменовані кастомні пакети
КонфігураціяКонфігураційний файл CodeQL та виключення
ВихідSARIF-файли, журнали робочих процесів, діагностика бази даних та дельта-звіти
Власник рішенняОсоба або команда, яка приймає, відкладає або блокує кожен матеріальний дельта

GitHub рекомендує пакет CodeQL, оскільки він містить сумісний CLI плюс стандартні пакети запитів і бібліотеки. [2] [3] Розглядайте цей пакет, конфігурацію робочого процесу та будь-які кастомні пакети як один версійний тестовий актив.


3. Побудуйте відтворювану базову лінію

Виберіть відомий комміт і збережіть його SHA. Запустіть поточну виробничу конфігурацію на цій точній версії і збережіть:

Для скомпільованих мов важливий метод створення бази даних. GitHub підтримує різні режими збірки, і відповідний режим залежить від мови та проєкту. [4] Якщо поточна виробнича система використовує ручну збірку, використовуйте ту ж команду збірки та залежності для порівняння. Інакше різниця збірки може виглядати як різниця аналізатора.

Базовий рівень — це не просто «підрахунок сповіщень минулого тижня». Це відстежуваний пакет, який може відтворити інший інженер.


4. Порівняйте старий і новий аналіз на одному й тому ж коді

Створіть тимчасову гілку оновлення або ізольований робочий процес порівняння. Обидві лінії повинні аналізувати однаковий комміт:

                         ┌─ Current CodeQL configuration ─→ old.sarif
same commit + same inputs
                         └─ Candidate CodeQL configuration → new.sarif

Зберігайте ці вхідні дані ідентичними, якщо вони не є явним предметом тесту:

Спочатку змініть лише кандидатний компонент — наприклад, версію bundle CodeQL. Якщо версія 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 містять більше, ніж просто номер повідомлення та рядка. Корисний ключ порівняння повинен віддавати перевагу стабільним ідентифікаторам, таким як:

Компактний звіт може виглядати так:

DeltaПравлінняРозташуванняСтаре → новеРезультат огляду
Доданоcpp/example-rulesrc/net.cppжодних → високихПідтверджені проблеми
Видаленоjava/example-rulesrc/db.javaВисокий → відсутністьВиправлення запиту підтверджено
Зміненоactions/example-rule.github/workflows/ci.ymlсередній → високийОчікуване оновлення моделі
НеперевершенийПравило звичаюПереміщена функціяВідбиток пальця зміненоПотрібна ручна кореляція

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


6. Тріаж кожної суттєвої категорії

Додані знахідки

Для кожного нового результату запитуйте:

  1. Чи додав у релізі відповідний запит або модель потоку даних?
  2. Чи дійсно шлях коду доступний?
  3. Чи може невеликий світильник або тест відтворити заявлений потік?
  4. Чи з'являється результат лише тому, що покриття екстракції покращилося?
  5. Чи є пригнічення виправданим, задокументованим і вузьким масштабом?

Видалені знахідки

Видалений результат потребує не меншої уваги:

  1. Чи був старий результат відомим хибнопозитивним?
  2. Чи описувалося в нотатках до релізу фіксацію точності для цього правила?
  3. Чи зберігається відповідний файл у базі даних кандидатів?
  4. Чи старий запит все ще повідомляє про проблему при роботі з порівнянними даними?
  5. Чи був результат прихований через зміну конфігурації або набору запитів?

Змінені знахідки

Перегляньте зміни у ступені серйозності, шляху, регіоні, повідомленні або класифікації. Деякі з них — це покращення презентації; інші можуть впливати на політики або маршрутизацію власності.

Невідповідні знахідки

Відбитки пальців можуть змінюватися під час переміщення коду або еволюції моделей аналізу. Зберігайте категорію «невідповідної», а не примушуйте додавати або видаляти кожен результат. Рецензент може корелюювати за правилами, функціями та шляхом потоку даних.


7. Перевірте покриття вилучення та налаштувань

Чиста дельта не має сенсу, якщо кандидат аналізував менше коду.

Перевірте принаймні:

Для великого репозиторію обирайте кілька відомих «сентинельних» файлів або навмисно вразливих тестових фітюрів. Їхні очікувані результати швидко дають ознаку, що кандидат все ще аналізує критичні шляхи.

Не публікуйте реальні вразливості у публічних фінітурах. Використовуйте синтетичні приклади у контрольованому тестовому репозиторії.


8. Захистіть кастомні запити

Кастомні пакети є частиною регресійної поверхні. Тестуйте їх незалежно перед прийняттям оновлення:

  1. розв'язати точні версії паків;
  2. запускати codeql pack install з каталогу паків;
  3. компілювати або тестувати власні запити;
  4. виконувати їхні тести запитів, де це можливо;
  5. проаналізувати принаймні одну репрезентативну базу даних;
  6. Порівняйте очікуваний набір результатів із базовим рівнем.

Пакети CodeQL використовують семантичні діапазони версій для залежностей, а файл блокування фіксує розв'язані залежності. [6] Переглядайте зміни блокованих файлів, як і будь-яке інше оновлення залежностей. Несподівано розширений діапазон залежностей може зробити майбутні запуски менш відтворюваними.


9. Проектування випускових гейтів за ризиком

Гейт запит на злиття

Використовуйте кандидатську лінію у спеціальному pull request-і на покращення.

Блокуйте злиття, коли:

Заплановане порівняння

Запускайте завдання поруч за графіком під час оцінки оновлення. Це фіксує зміни в репозиторії, які виявляють прогалини, відсутні у першому порівнянні. Зберігайте той самий контракт порівняння і маркуйте отримані звіти за комітом SHA.

Гейт перед релізом

Перед тим, як просувати конфігурацію кандидата:

Пороги, такі як «не більше ніж на 2% менше витягнутих файлів», можуть бути корисними попереджувальними сигналами, але вони залежать від конкретного проєкту. Не подавайте ілюстративного порогу як галузевий стандарт.


10. Обробка збоїв та відкат

Робочий процес порівняння має бути безпечним.

Відкат має відновити попередню перевірену конфігурацію, а не просто зменшити поріг тривоги.


11. Контрольний список QA

Відтворюваність

Покриття

Огляд дельти

Контроль випуску


12. Яка автоматизація повинна — а яка — не повинна — вирішувати

Автоматизація чудово створює порівнянні бази даних, нормалізує SARIF, обчислює дельти, додає артефакти та забезпечує наявність необхідних доказів.

Автоматизація не повинна вирішувати, що кожне додане сповіщення є дефектом продукту або що кожне видалене сповіщення є безпечним. Ці рішення потребують контексту: зміни запитів, досяжності, можливості експлуатації, запланованої конфігурації та прийнятого ризику проєкту.

Останні ворота мають поєднувати контракти, що перевіряються машинами, з рішенням про сортування, що належить людині.


Висновок

Оновлення CodeQL — це зміна самої тестової системи. Тестуйте її як будь-яку іншу виробничу залежність: контролюйте вхідні дані, порівнюйте стару та нову поведінку на тому ж коді, досліджуйте покриття, перевіряйте кастомні пакети та вимагайте обґрунтованих доказів перед просуванням.

Завдяки повторюваному процесу Базова лінія → Паралельне порівняння → Тріаж дельти → Випусковий шлюз команди можуть впроваджувати покращення аналізаторів, не приховуючи реальні дефекти та не створюючи зайвий шум сповіщень.


Джерела

  1. 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/
  2. CodeQL documentation — CodeQL tools and the CodeQL bundle: https://codeql.github.com/docs/codeql-overview/codeql-tools/
  3. 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
  4. GitHub Docs — CodeQL code scanning for compiled languages: https://docs.github.com/en/code-security/concepts/code-scanning/codeql/codeql-for-compiled-languages
  5. GitHub — CodeQL Action README and supported versions: https://github.com/github/codeql-action/blob/main/README.md
  6. 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