Як оновити рушій статичного аналізу, не плутаючи зміни аналізатора з регрессіями застосунків.
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. Запустіть поточну виробничу конфігурацію на цій точній версії і збережіть:
- URL робочого процесу;
- версію CodeQL Action або пакет;
- вибрані мови та набори запитів;
- режим збірки та команда збірки, коли використовується ручна збірка;
- згенерований результат SARIF;
- діагностика бази даних та відповідні журнали вилучення;
- Останній сигнал тривоги згрупований за правилами, тяжкістю та мовою.
Для скомпільованих мов важливий метод створення бази даних. GitHub підтримує різні режими збірки, і відповідний режим залежить від мови та проєкту. [4] Якщо поточна виробнича система використовує ручну збірку, використовуйте ту ж команду збірки та залежності для порівняння. Інакше різниця збірки може виглядати як різниця аналізатора.
Базовий рівень — це не просто «підрахунок сповіщень минулого тижня». Це відстежуваний пакет, який може відтворити інший інженер.
4. Порівняйте старий і новий аналіз на одному й тому ж коді
Створіть тимчасову гілку оновлення або ізольований робочий процес порівняння. Обидві лінії повинні аналізувати однаковий комміт:
┌─ Current CodeQL configuration ─→ old.sarif
same commit + same inputs
└─ Candidate CodeQL configuration → new.sarifЗберігайте ці вхідні дані ідентичними, якщо вони не є явним предметом тесту:
- здійснити SHA;
- перевірити глибину та підмодулі;
- операційну систему та архітектуру;
- файли блокування залежностей;
- створення змінних команд і середовища;
- політика згенерованого коду;
- шляхи, ігноровані конфігурацією CodeQL;
- Пакети запитів і кастомні пакети.
Спочатку змініть лише кандидатний компонент — наприклад, версію 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 містять більше, ніж просто номер повідомлення та рядка. Корисний ключ порівняння повинен віддавати перевагу стабільним ідентифікаторам, таким як:
- ідентифікатор правил;
- результат — відбитки пальців або часткові відбитки пальців, коли вони доступні;
- нормалізований артефактний URI;
- логічне розташування;
- регіон як запасний варіант, а не єдина ідентичність;
- Серйозність безпеки та рівень результату.
Компактний звіт може виглядати так:
| Delta | Правління | Розташування | Старе → нове | Результат огляду |
|---|---|---|---|---|
| Додано | cpp/example-rule | src/net.cpp | жодних → високих | Підтверджені проблеми |
| Видалено | java/example-rule | src/db.java | Високий → відсутність | Виправлення запиту підтверджено |
| Змінено | actions/example-rule | .github/workflows/ci.yml | середній → високий | Очікуване оновлення моделі |
| Неперевершений | Правило звичаю | Переміщена функція | Відбиток пальця змінено | Потрібна ручна кореляція |
Не покладайтеся лише на загальну кількість попереджень. П'ять видалених сповіщень і п'ять доданих сповіщень дають чисту зміну нуль, при цьому представляючи десять рішень про перегляд.
6. Тріаж кожної суттєвої категорії
Додані знахідки
Для кожного нового результату запитуйте:
- Чи додав у релізі відповідний запит або модель потоку даних?
- Чи дійсно шлях коду доступний?
- Чи може невеликий світильник або тест відтворити заявлений потік?
- Чи з'являється результат лише тому, що покриття екстракції покращилося?
- Чи є пригнічення виправданим, задокументованим і вузьким масштабом?
Видалені знахідки
Видалений результат потребує не меншої уваги:
- Чи був старий результат відомим хибнопозитивним?
- Чи описувалося в нотатках до релізу фіксацію точності для цього правила?
- Чи зберігається відповідний файл у базі даних кандидатів?
- Чи старий запит все ще повідомляє про проблему при роботі з порівнянними даними?
- Чи був результат прихований через зміну конфігурації або набору запитів?
Змінені знахідки
Перегляньте зміни у ступені серйозності, шляху, регіоні, повідомленні або класифікації. Деякі з них — це покращення презентації; інші можуть впливати на політики або маршрутизацію власності.
Невідповідні знахідки
Відбитки пальців можуть змінюватися під час переміщення коду або еволюції моделей аналізу. Зберігайте категорію «невідповідної», а не примушуйте додавати або видаляти кожен результат. Рецензент може корелюювати за правилами, функціями та шляхом потоку даних.
7. Перевірте покриття вилучення та налаштувань
Чиста дельта не має сенсу, якщо кандидат аналізував менше коду.
Перевірте принаймні:
- Усі очікувані мовні роботи виконали;
- створення бази даних завершено без збоїв екстрактора;
- Ручні кроки будівництва збирали заплановані цілі;
- Корені джерела та ігноровані шляхи не змінювалися випадково;
- згенерований код і тестовий код відповідають задокументованій політиці;
- кастомні пакети запитів були успішно вирішені;
- завершено завантаження результатів або створення артефакту;
- Були переглянуті попередження в діагностиці баз даних.
Для великого репозиторію обирайте кілька відомих «сентинельних» файлів або навмисно вразливих тестових фітюрів. Їхні очікувані результати швидко дають ознаку, що кандидат все ще аналізує критичні шляхи.
Не публікуйте реальні вразливості у публічних фінітурах. Використовуйте синтетичні приклади у контрольованому тестовому репозиторії.
8. Захистіть кастомні запити
Кастомні пакети є частиною регресійної поверхні. Тестуйте їх незалежно перед прийняттям оновлення:
- розв'язати точні версії паків;
- запускати
codeql pack installз каталогу паків; - компілювати або тестувати власні запити;
- виконувати їхні тести запитів, де це можливо;
- проаналізувати принаймні одну репрезентативну базу даних;
- Порівняйте очікуваний набір результатів із базовим рівнем.
Пакети CodeQL використовують семантичні діапазони версій для залежностей, а файл блокування фіксує розв'язані залежності. [6] Переглядайте зміни блокованих файлів, як і будь-яке інше оновлення залежностей. Несподівано розширений діапазон залежностей може зробити майбутні запуски менш відтворюваними.
9. Проектування випускових гейтів за ризиком
Гейт запит на злиття
Використовуйте кандидатську лінію у спеціальному pull request-і на покращення.
Блокуйте злиття, коли:
- створення або аналіз бази даних не зазнає успіху;
- відсутня очікувана мова або критичний шлях;
- кастомний пак більше не розв'язується або його тести не проходять успіху;
- новий результат високої тяжкості не має власного або не має рішення про сортування;
- раніше підтверджений результат високої тяжкості зникає без пояснення.
Заплановане порівняння
Запускайте завдання поруч за графіком під час оцінки оновлення. Це фіксує зміни в репозиторії, які виявляють прогалини, відсутні у першому порівнянні. Зберігайте той самий контракт порівняння і маркуйте отримані звіти за комітом SHA.
Гейт перед релізом
Перед тим, як просувати конфігурацію кандидата:
- повторіть порівняння кандидата на реліз;
- закрити або явно прийняти будь-яку дельту матеріалу;
- підтвердити необхідні перевірки статусу та дозволи;
- архівуйте посилання на звіти та робочі процеси;
- запишіть версію відкату та кроки відкату;
- отримайте необхідний дозвіл безпеки або QA.
Пороги, такі як «не більше ніж на 2% менше витягнутих файлів», можуть бути корисними попереджувальними сигналами, але вони залежать від конкретного проєкту. Не подавайте ілюстративного порогу як галузевий стандарт.
10. Обробка збоїв та відкат
Робочий процес порівняння має бути безпечним.
- Якщо одна смуга не проходить, позначте порівняння неостаточним, не пропущеним.
- Якщо парсер SARIF не спрацює, зберігайте обидва сирі артефакти і зупиняйте гейт.
- Якщо кандидат не може розв'язати пакет запитів, не повертайтеся мовчки до іншої версії.
- Якщо будівництво недетерміноване, повторіть обидві смуги перед класифікацією.
- Якщо регрес матеріалу неможливо пояснити, залиште аналізатор виробництва без змін.
Відкат має відновити попередню перевірену конфігурацію, а не просто зменшити поріг тривоги.
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
Залишити коментар
Поділіться думкою про статтю. Реєстрація не потрібна.
Коментарі
Завантаження коментарів…