Die Ankündigung von GitHub, das plattformübergreifende CodeQL-Bundle einzustellen, ist eine wichtige Erinnerung: Ein Update des Security Scannings ist nicht nur eine Aktualisierung einer Abhängigkeit. CodeQL Action, CLI-Bundle, Query Packs, Runner-Plattform, Build-Modus und Upload-Berechtigungen bilden gemeinsam ein System. Wenn sich eine dieser Systemgrenzen ändert, kann selbst ein erfolgreicher Workflow fehlende Sprachen, veränderte Befunde oder unvollständige Nachweise verbergen.

Dieser Artikel beschreibt einen praxisnahen QA-Ansatz für erweiterte CodeQL-Konfigurationen. Das Default Setup auf GitHub-gehosteten Runnern wird weitgehend von GitHub verwaltet. Teams, die festgelegte Tool-Versionen, benutzerdefinierte Packs, selbst gehostete Runner oder erweiterte Workflows verwenden, benötigen besonders belastbare Nachweise für die Migration.

1. Die veränderlichen Komponenten getrennt betrachten

Unterscheiden Sie vor einer Änderung am Workflow folgende Komponenten:

  1. CodeQL-Action-Version: Sie steuert die Integration in den Workflow. GitHub führt derzeit v4 als neueste unterstützte Hauptversion und v3 als ebenfalls unterstützte Version auf. Erweiterte Konfigurationen sollten in der Regel einer unterstützten Hauptversion folgen oder bewusst gepflegte, festgelegte Revisionen verwenden.
  2. CodeQL-CLI- und Bundle-Version: Sie bezeichnet den Analyzer und die gebündelten Tools, die während eines Laufs verwendet werden. Sie ist nicht mit der Action-Version identisch.
  3. Query Packs: Sie enthalten Abfragen und Bibliotheken für bestimmte Sprachen. Benutzerdefinierte Konfigurationen können Abhängigkeiten einführen, die von der Standardsuite nicht verwendet werden.
  4. Runner-Plattform: Dazu gehören Betriebssystem, CPU-Architektur, installierte Build-Tools, Netzwerkzugriff und Cache-Zustand.
  5. Build-Modus: Er bestimmt, wie CodeQL die Datenbank erstellt. none, autobuild und manual unterstützen unterschiedliche Sprachen und bergen unterschiedliche Risiken; die richtige Wahl hängt vom Repository ab.
  6. SARIF-Upload: Er veröffentlicht Analyseergebnisse im Code Scanning. Eine erfolgreiche Analyse ohne den erwarteten Upload, die erwartete Kategorie oder die erforderlichen Berechtigungen ist kein vollständiges Produktionsergebnis.

Die Ankündigung zum plattformübergreifenden Bundle betrifft dessen Distribution. Sie belegt nicht, dass jedes Repository dieselbe Änderung am Workflow vornehmen muss. Dokumentieren Sie deshalb zuerst die tatsächlich verwendete Konfiguration.

2. Die aktuelle Konfiguration inventarisieren

Erstellen Sie für jeden CodeQL-Workflow einen kompakten Migrationsnachweis:

  1. Erfassen Sie jede Referenz auf github/codeql-action/* und dokumentieren Sie, ob sie ein Major-Tag, ein Release-Tag oder einen Commit-SHA verwendet.
  2. Erfassen Sie jede tools-Eingabe und jede andere explizite Auswahl einer CodeQL-Version.
  3. Erfassen Sie die Runner-Labels und -Architekturen einschließlich der selbst gehosteten Runner.
  4. Erfassen Sie die analysierten Sprachen und den Build-Modus jeder Sprache.
  5. Erfassen Sie benutzerdefinierte Konfigurationsdateien, Query Suites, Model Packs und heruntergeladene Packs.
  6. Erfassen Sie Workflow-Berechtigungen, SARIF-Kategorien, die Aufbewahrung von Artefakten und Abhängigkeiten vom Branch-Schutz.
  7. Erfassen Sie Netzwerkeinschränkungen, Proxys, Mirrors und Caches, die an Downloads von Bundles oder Packs beteiligt sind.

Diese Bestandsaufnahme verhindert einen häufigen Fehler: Ein vereinfachtes Beispiel wird getestet, obwohl die Produktionsumgebung von einem benutzerdefinierten Query Pack oder einem eingeschränkten Runner abhängt.

3. Eine vergleichbare Baseline erstellen

Führen Sie die vorhandene Konfiguration für einen festgelegten Commit aus und bewahren Sie genügend Nachweise auf, um spätere Unterschiede erklären zu können. Erfassen Sie:

  1. das Gesamtergebnis des Workflows und die Ergebnisse der einzelnen Schritte;
  2. die in den Logs angegebenen Versionen der Action und von CodeQL;
  3. die tatsächlich initialisierten Sprachen und Build-Modi;
  4. den Abschluss der Datenbankerstellung und der Analyse;
  5. SARIF-Dateien oder hochgeladene Kategorien;
  6. die Identitäten der Alerts und die betroffenen Fundstellen, gruppiert nach Regel und Schweregrad;
  7. Laufzeit, Downloadverhalten und relevante Cache-Informationen;
  8. Logs und Hashes von Artefakten, die zur Reproduktion des Vergleichs erforderlich sind.

Verwenden Sie identische Alert-Zahlen nicht als einziges Akzeptanzkriterium. Ein neuerer Analyzer oder ein neueres Query Pack kann Befunde berechtigterweise hinzufügen, entfernen oder anders klassifizieren. Entscheidend ist, ob jeder Unterschied verstanden wurde und akzeptabel ist.

4. Einen kontrollierten Kandidaten ausführen

Verwenden Sie für den Kandidaten nach Möglichkeit denselben Commit, dieselbe Konfiguration, dieselben Testdaten und dieselbe Runner-Klasse. Ändern Sie jeweils nur eine Migrationsvariable. Beginnen Sie mit einem nicht blockierenden Branch oder einem zeitgesteuerten Canary-Lauf und vergleichen Sie die Nachweise, bevor Sie den verpflichtenden Produktionscheck ändern.

Ein kompakter Canary für eine erweiterte Konfiguration kann SARIF aufbewahren, ohne die Ergebnisse zu veröffentlichen:

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

Dieses Beispiel ist bewusst unvollständig: Kompilierte Sprachen können autobuild oder explizite Build-Befehle erfordern, und ein Produktionsworkflow benötigt möglicherweise security-events: write. Der Canary sollte das reale Repository abbilden, statt ein generisches Beispiel unverändert zu übernehmen.

5. Akzeptanzkriterien vor der Bereitstellung definieren

Eine Migration ist erst dann bereit, wenn ihre Nachweise die von Security, Entwicklung und QA vereinbarten Kriterien erfüllen. Ein praxistaugliches Gate umfasst:

  1. Jede erforderliche Sprache wird initialisiert und erzeugt eine Datenbank.
  2. Die erwarteten Query Suites und benutzerdefinierten Packs werden erfolgreich aufgelöst.
  3. Für jeden vorgesehenen Matrixeintrag wird SARIF erzeugt.
  4. Neue, fehlende oder veränderte Befunde werden geprüft und erklärt.
  5. Runner-Architektur und ausgewählter Download entsprechen der vorgesehenen Umgebung.
  6. Laufzeit und Ressourcenverbrauch bleiben innerhalb des dokumentierten Budgets des Teams.
  7. Die erforderlichen Upload-Berechtigungen und Kategorien funktionieren in einem kontrollierten Integrationslauf.
  8. Logs und Artefakte enthalten weder Secrets noch unnötige Quellcodedaten.
  9. Das Rollback-Ziel ist bekannt und weiterhin verfügbar.
  10. Ein Reviewer genehmigt den Vergleich und nicht lediglich ein grünes Statussymbol.

6. Negative Pfade sicher testen

Führen Sie Negativtests in einem kurzlebigen Repository, auf einem isolierten Runner oder mit einer Dry-Run-Konfiguration aus. Unterbrechen Sie den produktiven Security-Workflow nicht absichtlich.

  1. Wählen Sie eine nicht unterstützte oder nicht verfügbare Tool-Version und prüfen Sie, ob das Setup mit aussagekräftigen Diagnoseinformationen sicher fehlschlägt.
  2. Testen Sie eine Runner-Architektur, für die das erwartete Artefakt nicht abgerufen werden kann. Verwenden Sie dafür einen kontrollierten Netzwerk-Stub, statt Produktions-URLs zu verändern.
  3. Referenzieren Sie ein inkompatibles benutzerdefiniertes Pack und prüfen Sie, ob der Fehler auf die Pack-Auflösung verweist.
  4. Blockieren Sie den Download in einem isolierten Netzwerktest und stellen Sie sicher, dass der Workflow weder Erfolg meldet noch ein ungeprüftes Artefakt wiederverwendet.
  5. Entfernen Sie security-events: write aus einem Testworkflow und prüfen Sie, ob ein versuchter Upload fehlschlägt, während der lokale SARIF-Nachweis weiterhin geprüft werden kann.
  6. Beschädigen oder entfernen Sie einen erwarteten Build-Schritt und prüfen Sie, ob die Datenbankerstellung oder Analyse sichtbar fehlschlägt.
  7. Führen Sie zwei Matrixeinträge mit unterschiedlichen Kategorien aus und prüfen Sie, ob ihre Ergebnisse nicht unbemerkt zusammengeführt werden.

Der genaue Wortlaut von Fehlermeldungen ist kein stabiler Vertrag. Prüfen Sie stattdessen die Fehlerkategorie, den fehlgeschlagenen Schritt, die aufbewahrten Diagnoseinformationen und das Ausbleiben eines falschen Erfolgssignals.

7. Wo Automatisierung hilft

Automatisierung eignet sich besonders für die wiederholbare Erfassung und den Vergleich:

Eine menschliche Prüfung bleibt erforderlich. Ein neuer Alert kann eine wertvolle Verbesserung der Erkennung darstellen; ein fehlender Alert kann eine gefährliche Regression sein. Keine dieser Schlussfolgerungen lässt sich allein aus einer Anzahl ableiten.

8. Fünf Fragen für Reviewer

  1. Welche CodeQL-Komponente wurde geändert: Action, CLI-Bundle, Query Pack, Runner, Build-Modus oder Berechtigungen?
  2. Wurde die Baseline anhand desselben Commits und einer repräsentativen Runner-Umgebung erzeugt?
  3. Lässt sich jeder veränderte Befund auf eine Regel, eine Fundstelle und ein Artefakt des Kandidaten zurückführen?
  4. Wurden benutzerdefinierte Packs, selbst gehostete Runner und eingeschränkte Netzwerkpfade berücksichtigt?
  5. Ist ein Rollback möglich, ohne eine bereits nicht mehr unterstützte Konfiguration wiederherzustellen?

9. Leitfaden zur Fehlerbehebung

10. Release-Checkliste

  1. Die Bestandsaufnahme wurde geprüft und zusammen mit der Änderung gespeichert.
  2. Baseline und Kandidat verwenden denselben repräsentativen Commit.
  3. Erforderliche Sprachen, Runner, Modi und benutzerdefinierte Packs wurden getestet.
  4. SARIF-Unterschiede wurden von einem qualifizierten Reviewer geprüft.
  5. Negative Pfade schlagen sicher fehl und bewahren Diagnoseinformationen auf.
  6. Berechtigungen und Upload-Kategorien wurden verifiziert.
  7. Laufzeit- und Ressourcenbudgets wurden akzeptiert.
  8. Secrets und sensible Quellcodedaten wurden aus den Nachweisen ausgeschlossen.
  9. Rollback-Ziel und verantwortliche Person wurden dokumentiert.
  10. Nach der Bereitstellung in der Produktionsumgebung wurde ein minimaler Smoke-Test ausgeführt.

Fazit

Die sicherste CodeQL-Migration basiert auf Nachweisen. Behandeln Sie die Bundle-Änderung wie eine Änderung an einer Sicherheitskontrolle: Identifizieren Sie Systemgrenzen, vergleichen Sie eine festgelegte Baseline mit einem kontrollierten Kandidaten, testen Sie Fehlerpfade und bewahren Sie Artefakte auf, die ein anderer Reviewer prüfen kann. Die Automatisierung erfasst die Nachweise; Menschen entscheiden, ob ein verändertes Sicherheitsverhalten akzeptabel ist.

Quellen