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:
- CodeQL-Action-Version: Sie steuert die Integration in den Workflow. GitHub führt derzeit
v4als neueste unterstützte Hauptversion undv3als ebenfalls unterstützte Version auf. Erweiterte Konfigurationen sollten in der Regel einer unterstützten Hauptversion folgen oder bewusst gepflegte, festgelegte Revisionen verwenden. - 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.
- 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.
- Runner-Plattform: Dazu gehören Betriebssystem, CPU-Architektur, installierte Build-Tools, Netzwerkzugriff und Cache-Zustand.
- Build-Modus: Er bestimmt, wie CodeQL die Datenbank erstellt.
none,autobuildundmanualunterstützen unterschiedliche Sprachen und bergen unterschiedliche Risiken; die richtige Wahl hängt vom Repository ab. - 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:
- Erfassen Sie jede Referenz auf
github/codeql-action/*und dokumentieren Sie, ob sie ein Major-Tag, ein Release-Tag oder einen Commit-SHA verwendet. - Erfassen Sie jede
tools-Eingabe und jede andere explizite Auswahl einer CodeQL-Version. - Erfassen Sie die Runner-Labels und -Architekturen einschließlich der selbst gehosteten Runner.
- Erfassen Sie die analysierten Sprachen und den Build-Modus jeder Sprache.
- Erfassen Sie benutzerdefinierte Konfigurationsdateien, Query Suites, Model Packs und heruntergeladene Packs.
- Erfassen Sie Workflow-Berechtigungen, SARIF-Kategorien, die Aufbewahrung von Artefakten und Abhängigkeiten vom Branch-Schutz.
- 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:
- das Gesamtergebnis des Workflows und die Ergebnisse der einzelnen Schritte;
- die in den Logs angegebenen Versionen der Action und von CodeQL;
- die tatsächlich initialisierten Sprachen und Build-Modi;
- den Abschluss der Datenbankerstellung und der Analyse;
- SARIF-Dateien oder hochgeladene Kategorien;
- die Identitäten der Alerts und die betroffenen Fundstellen, gruppiert nach Regel und Schweregrad;
- Laufzeit, Downloadverhalten und relevante Cache-Informationen;
- 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-resultsDieses 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:
- Jede erforderliche Sprache wird initialisiert und erzeugt eine Datenbank.
- Die erwarteten Query Suites und benutzerdefinierten Packs werden erfolgreich aufgelöst.
- Für jeden vorgesehenen Matrixeintrag wird SARIF erzeugt.
- Neue, fehlende oder veränderte Befunde werden geprüft und erklärt.
- Runner-Architektur und ausgewählter Download entsprechen der vorgesehenen Umgebung.
- Laufzeit und Ressourcenverbrauch bleiben innerhalb des dokumentierten Budgets des Teams.
- Die erforderlichen Upload-Berechtigungen und Kategorien funktionieren in einem kontrollierten Integrationslauf.
- Logs und Artefakte enthalten weder Secrets noch unnötige Quellcodedaten.
- Das Rollback-Ziel ist bekannt und weiterhin verfügbar.
- 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.
- 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.
- 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.
- Referenzieren Sie ein inkompatibles benutzerdefiniertes Pack und prüfen Sie, ob der Fehler auf die Pack-Auflösung verweist.
- Blockieren Sie den Download in einem isolierten Netzwerktest und stellen Sie sicher, dass der Workflow weder Erfolg meldet noch ein ungeprüftes Artefakt wiederverwendet.
- Entfernen Sie
security-events: writeaus einem Testworkflow und prüfen Sie, ob ein versuchter Upload fehlschlägt, während der lokale SARIF-Nachweis weiterhin geprüft werden kann. - Beschädigen oder entfernen Sie einen erwarteten Build-Schritt und prüfen Sie, ob die Datenbankerstellung oder Analyse sichtbar fehlschlägt.
- 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:
- Workflow-Metadaten und Analyzer-Versionen in ein maschinenlesbares Manifest übertragen.
- SARIF normalisieren und Regeln, Fingerprints, Fundstellen sowie Schweregrade vergleichen.
- Prüfen, ob jede erwartete Sprache und Kategorie ein Artefakt erzeugt hat.
- Die Aufbewahrung von Nachweisen und Secret Scanning für hochgeladene Logs durchsetzen.
- Unerwartete Zunahmen der Laufzeit oder des Downloadvolumens erkennen.
- Bei veränderten Befunden einen Review-Vorgang erstellen.
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
- Welche CodeQL-Komponente wurde geändert: Action, CLI-Bundle, Query Pack, Runner, Build-Modus oder Berechtigungen?
- Wurde die Baseline anhand desselben Commits und einer repräsentativen Runner-Umgebung erzeugt?
- Lässt sich jeder veränderte Befund auf eine Regel, eine Fundstelle und ein Artefakt des Kandidaten zurückführen?
- Wurden benutzerdefinierte Packs, selbst gehostete Runner und eingeschränkte Netzwerkpfade berücksichtigt?
- Ist ein Rollback möglich, ohne eine bereits nicht mehr unterstützte Konfiguration wiederherzustellen?
9. Leitfaden zur Fehlerbehebung
- Der Bundle-Download schlägt fehl: Prüfen Sie die Runner-Plattform, die Netzwerkrichtlinie, den Proxy, die ausgewählte
tools-Eingabe und die aktuellen Release-Artefakte. - Eine Sprache fehlt: Prüfen Sie die Sprachkennung, die Erweiterung der Matrix, die Unterstützung des Build-Modus und die Logs der Datenbankinitialisierung.
- Benutzerdefinierte Abfragen schlagen fehl: Prüfen Sie die Pack-Abhängigkeiten und testen Sie exakt die in der Produktionsumgebung verwendete Konfigurationsdatei.
- SARIF ist vorhanden, aber es werden keine Alerts angezeigt: Prüfen Sie die
upload-Einstellungen, Berechtigungen, Kategoriewerte, die Verfügbarkeit von Code Scanning für das Repository und die Upload-Logs. - Die Anzahl der Alerts ändert sich: Vergleichen Sie die SARIF-Einträge nach Regel und Fundstelle. Verbergen Sie den Unterschied nicht durch eine Änderung der Baseline.
- Der Canary ist langsamer: Trennen Sie Download-, Build-, Datenbank-, Abfrage- und Upload-Zeit, bevor Sie die Ursache zuordnen.
10. Release-Checkliste
- Die Bestandsaufnahme wurde geprüft und zusammen mit der Änderung gespeichert.
- Baseline und Kandidat verwenden denselben repräsentativen Commit.
- Erforderliche Sprachen, Runner, Modi und benutzerdefinierte Packs wurden getestet.
- SARIF-Unterschiede wurden von einem qualifizierten Reviewer geprüft.
- Negative Pfade schlagen sicher fehl und bewahren Diagnoseinformationen auf.
- Berechtigungen und Upload-Kategorien wurden verifiziert.
- Laufzeit- und Ressourcenbudgets wurden akzeptiert.
- Secrets und sensible Quellcodedaten wurden aus den Nachweisen ausgeschlossen.
- Rollback-Ziel und verantwortliche Person wurden dokumentiert.
- 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.
Kommentar hinterlassen
Teilen Sie Ihre Gedanken zum Artikel. Kein Konto erforderlich.
Kommentare
Kommentare werden geladen…