Оголошення GitHub про припинення підтримки універсального пакета CodeQL нагадує: оновлення засобу сканування безпеки — це не просто зміна версії залежності. CodeQL Action, пакет CLI, пакети запитів, платформа середовища виконання, режим побудови та дозволи на завантаження результатів утворюють єдину систему. Якщо змінюється одна з її меж, успішне виконання робочого процесу все одно може приховувати пропущені мови, змінені результати або неповні докази.

У цій статті описано практичний QA-підхід до розширених налаштувань CodeQL. Стандартним налаштуванням у середовищах виконання GitHub переважно керує сам GitHub. Найретельніше перевіряти міграцію мають команди, які використовують зафіксовані версії інструментів, власні пакети, власні середовища виконання або розширені робочі процеси.

1. Розмежуйте компоненти, що змінюються

Перш ніж змінювати робочий процес, розмежуйте такі компоненти:

  1. Версія CodeQL Action визначає інтеграцію з робочим процесом. Наразі GitHub указує v4 як останню підтримувану основну версію, а v3 — як іншу підтримувану версію. У розширених налаштуваннях зазвичай слід використовувати підтримувану основну версію або свідомо супроводжувати зафіксовані редакції.
  2. Версія CodeQL CLI та пакета визначає аналізатор і набір інструментів, що використовуються під час запуску. Вона не тотожна версії CodeQL Action.
  3. Пакети запитів містять запити й бібліотеки для певних мов. Власні конфігурації можуть додавати залежності, яких не використовує стандартний набір запитів.
  4. Платформа середовища виконання охоплює операційну систему, архітектуру процесора, установлені засоби побудови, доступ до мережі та стан кешу.
  5. Режим побудови визначає, як CodeQL створює базу даних. Режими none, autobuild і manual підтримують різні мови та мають різні ризики; правильний вибір залежить від репозиторію.
  6. Завантаження SARIF публікує результати аналізу в системі сканування коду. Успішний аналіз без очікуваного завантаження, категорії або дозволів не є повним результатом для робочого середовища.

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

2. Проведіть інвентаризацію поточного налаштування

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

  1. Зафіксуйте всі посилання github/codeql-action/* і зазначте, чи використовують вони тег основної версії, тег релізу або SHA коміту.
  2. Зафіксуйте параметр tools, якщо він заданий, а також інші явні налаштування версії CodeQL.
  3. Зафіксуйте мітки й архітектури середовищ виконання, зокрема власних.
  4. Зафіксуйте мови, що аналізуються, і режим побудови для кожної мови.
  5. Зафіксуйте власні конфігураційні файли, набори запитів, пакети моделей і завантажувані пакети.
  6. Зафіксуйте дозволи робочого процесу, категорії SARIF, терміни зберігання артефактів і залежності правил захисту гілок.
  7. Зафіксуйте мережеві обмеження, проксі-сервери, дзеркала та кеші, що беруть участь у завантаженні пакетів CodeQL або пакетів запитів.

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

3. Створіть базові показники для порівняння

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

  1. Підсумковий результат робочого процесу та результати його кроків.
  2. Версії CodeQL Action і CodeQL, зазначені в журналах.
  3. Мови та режими побудови, які було фактично ініціалізовано.
  4. Результати створення бази даних і завершення аналізу.
  5. Файли SARIF або категорії завантажених результатів.
  6. Ідентифікатори сповіщень і відповідні розташування в коді, згруповані за правилом і рівнем серйозності.
  7. Тривалість виконання, поведінку завантаження та доречні відомості про кеш.
  8. Журнали й хеші артефактів, необхідні для відтворення порівняння.

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

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-командою. Практичний шлюз має перевіряти таке:

  1. Для кожної обов’язкової мови успішно виконано ініціалізацію та створено базу даних.
  2. Очікувані набори запитів і власні пакети успішно знайдено та підключено.
  3. SARIF створено для кожного запланованого елемента матриці.
  4. Нові, відсутні або змінені результати проаналізовано та пояснено.
  5. Архітектура середовища виконання й вибраний для завантаження пакет відповідають цільовому середовищу.
  6. Тривалість виконання та використання ресурсів залишаються в межах задокументованого командою бюджету.
  7. Необхідні дозволи на завантаження та категорії працюють під час контрольованого інтеграційного запуску.
  8. Журнали й артефакти не містять секретів або зайвих фрагментів вихідного коду.
  9. Цільову версію для відкату визначено, і вона залишається доступною.
  10. Порівняння схвалив рецензент, а не лише зелений індикатор стану.

6. Безпечно перевірте негативні сценарії

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

  1. Виберіть непідтримувану або недоступну версію інструментів і переконайтеся, що налаштування завершується помилкою, не пропускає зміну далі та надає корисні діагностичні дані.
  2. Перевірте архітектуру середовища виконання, для якої неможливо отримати очікуваний файл пакета, використовуючи контрольовану мережеву заглушку замість зміни робочих URL.
  3. Підключіть несумісний власний пакет і переконайтеся, що повідомлення про помилку вказує на проблему з пошуком або підключенням пакета.
  4. Заблокуйте завантаження в ізольованому мережевому тесті й переконайтеся, що робочий процес не повідомляє про успіх і не використовує повторно неперевірений артефакт.
  5. Вилучіть security-events: write із тестового робочого процесу й переконайтеся, що спроба завантаження завершується невдало, а локальні докази SARIF залишаються доступними для перевірки.
  6. Пошкодьте або пропустіть очікуваний крок побудови й переконайтеся, що помилка створення бази даних або аналізу є очевидною.
  7. Запустіть два елементи матриці з різними категоріями й переконайтеся, що їхні результати не об’єднуються непомітно.

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

7. Де допомагає автоматизація

Автоматизація корисна для повторюваного збирання та порівняння даних:

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

8. П’ять запитань для рецензента

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

9. Рекомендації з усунення несправностей

10. Контрольний список релізу

  1. Інвентаризацію перевірено та збережено разом зі зміною.
  2. Для базової версії та кандидата використано той самий репрезентативний коміт.
  3. Перевірено всі обов’язкові мови, середовища виконання, режими й власні пакети.
  4. Відмінності в SARIF проаналізував кваліфікований рецензент.
  5. Негативні сценарії завершуються блокувально та зберігають діагностичні дані.
  6. Дозволи й категорії завантаження перевірено.
  7. Бюджети часу виконання та ресурсів погоджено.
  8. Секрети й чутливі дані вихідного коду не потрапляють до доказів.
  9. Цільову версію та відповідального за відкат задокументовано.
  10. Після просування зміни до робочого середовища виконано мінімальну перевірку основної працездатності.

Висновок

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

Джерела