Der Standard für die „ allow “-Regel

Standardmäßig muss Ihre Rego-Versicherungspolice eine „ allow “-Klausel enthalten. Im Zusammenhang mit dieser Pipeline ist dies nicht nur ein Vorschlag – es ist eine zwingende Vorgabe.

Die Pipeline-Engine fragt speziell den booleschen Wert „ allow “ ab, um die endgültige Entscheidung über die Durchführung oder den Abbruch der Bereitstellung zu treffen. Wenn Sie eine benutzerdefinierte Rego-Richtlinie bereitstellen, müssen Sie diese Regel ausdrücklich definieren. Fehlt die Regel „ allow “ oder ergibt ihre Auswertung den Wert „ false “, wird die Pipeline sofort angehalten, die Bereitstellung blockiert und es werden die von Ihnen definierten Ablehnungsmeldungen ausgegeben.

Um maximale Sicherheit zu gewährleisten, arbeitet OPA nach einem strengen „Fail-Closed“-Prinzip. Ihre Richtlinie sollte standardmäßig immer auf „ false “ gesetzt sein und nur dann den Wert „ true “ annehmen, wenn alle erforderlichen Compliance-Bedingungen erfüllt sind.

package one_pipeline.config
# Default deny
default allow := false
# Allow only if your custom checks pass
allow {
    check_sast_scans_passed
    check_secrets_scans_passed
}

Richtliniendateien und Datenvalidierungsdateien

Die Konfigurationsdatei (.rego) – Die Logik

Hier geben Sie Ihre eigentlichen Regeln und Bedingungen ein. Ihre Richtlinie könnte beispielsweise lauten: „Lassen Sie diese Bereitstellung nur zu, wenn ein Schwachstellen-Scan durchgeführt wurde und die Ergebnisse zeigen, dass keine kritischen Probleme vorliegen.“ Sie können Ihre benutzerdefinierte Richtliniendatei über die Pipeline-Umgebungseigenschaft „ policy-path “ bereitstellen. Wird keine Richtliniendatei angegeben, verwendet die Pipeline die Standard-Richtliniendatei.

Die Datenvalidierungsdatei (.json) – Die Fakten

Diese Datei dient als Ihre statische Referenzliste. Anstatt Daten direkt in Ihre Rego-Regeln fest zu codieren, verwenden Sie diese Datei, um Listen mit zugelassenen Variablen zu verwalten – wie beispielsweise Ihre zulässigen Image-Registries (us.icr.io oder eu.icr.io) oder bestimmte Repositorys, die von bestimmten Prüfungen ausgenommen sind. Sie können Ihre Datenvalidierungsdatei über die Pipeline-Umgebungseigenschaft „ evidence-checks-config-path “ bereitstellen. Wird keine Datenvalidierungsdatei bereitgestellt, verwendet die Pipeline die Standard-Datenvalidierungsdatei.

Beispiel für eine Datenvalidierungsdatei:

        package one_pipeline.config
        pre_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }
        post_deployment := {
            "com.ibm.prod_change_request": {
                "asset_type": [
                "*",
                "image"
                ],
                "source": [
                "prod",
                "stage"
                ],
                "target": [
                "prod",
                "stage"
                ],
                "recommended": [
                "*"
                ]
            }
        }

Jeder Block in der Konfiguration legt genau fest, welche Nachweise erwartet werden, woher sie stammen und wie streng sie durchgesetzt werden sollen.

• Die Beweistyp-ID (com.ibm.prod_change_request): Der Schlüssel der obersten Ebene gibt die spezifische Kategorie des zu bewertenden Beweismittels vor. Zu den gängigen Beispielen gehören com.ibm.static-scan, com.ibm.unit-tests oder com.ibm.image_signing.
• asset_type: Legt fest, auf welche Art von Artefakt diese Regel zutrifft. Beispielsweise könnte dies nur für image oder repo gelten. Mit der Option „ ["*"] “ wird die Regel auf alle Asset-Typen angewendet.
• source (Quellumgebungen): Gibt an, woher die Beweismittel stammen. Dabei kann es sich um einen bestimmten Zweig oder eine Pipeline-Umgebung handeln (z. B. ci-pipeline, stage, prod).
• target (Zielumgebungen): Definiert die Zielumgebung, in der diese Evidenz im Hinblick auf die Bereitstellung validiert wird (z. B. stage, prod). Weitere Informationen zu Quelle und Ziel finden Sie hier.
• gating mode: In den letzten Feldern geben Sie an, welchen Gating-Modus Sie für den Belegtyp anwenden möchten. Weitere Informationen zu den unterstützten Gating-Modi finden Sie hier.

Hinweis: Alle Prüfungen vor der Bereitstellung müssen im Array „ pre_deployment :{} “ definiert werden, und alle Prüfungen nach der Bereitstellung müssen im Array „ post_deployment :{} “ definiert werden. Wenn Sie den Standardpfad für die Richtlinie verwenden, müssen Sie außerdem den Import des Pakets „ one_pipeline.config “ in Ihre Registrierungsdatei für die Datenvalidierung einfügen.

Das Skript zum Konvertieren von JSON in Rego

Die Pipeline unterstützt zwar von Haus aus ältere JSON-Dateien zur Datenvalidierung, doch möglicherweise möchten Sie Ihre Konfigurationen irgendwann auf natives Rego umstellen, um den „Policy-as-Code“-Standard vollständig zu übernehmen.

Um Ihnen dabei zu helfen, stellen wir ein eigenständiges Dienstprogramm-Skript zur Verfügung, das Ihre bestehenden JSON-Datenvalidierungsdateien automatisch in das neue Rego-Format konvertiert.

Scriptspeicherposition: /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

So verwenden Sie das Konvertierungsskript

Sie können dieses Skript lokal oder im Rahmen eines Pipeline-Laufs ausführen. Wenn Sie das Skript lokal ausführen, müssen Sie die Ziel- und Quellumgebung explizit angeben.

# Convert a JSON config to Rego using named parameters
/opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh \
  --input ./legacy-evidence-config.json \
  --output ./new-evidence-config.rego \
  --target-env prod \
  --source-env master

Flexible Konfiguration: Mehrere Validierungsdateien

Komplexe Umgebungen erfordern oft modulare Regelsätze. Um dies zu unterstützen, können Sie mithilfe der Pipeline zur Validierung von Promotions Ihre Nachweise gleichzeitig anhand mehrerer Konfigurationen bewerten.

Sie können mehrere Datenvalidierungsdateien angeben, indem Sie deren Pfade als durch Kommas getrennte Liste an den Parameter „ evidence-checks-config-path “ übergeben. In diesem Fall vergleicht die Pipeline die Evidenz-Nutzdaten mit jeder Konfigurationsdatei und erstellt für jede Datei eine eigene Auswertungs-Tabelle. Und im PR-Kommentarbereich werden die Bewertungstabellen für jede Datei als separate Kommentare angezeigt.

Automatisiertes PR-Feedback

Um maximale Transparenz zu gewährleisten, gleicht die Pipeline die aktuelle Evidenz-Nutzlast mit jeder von Ihnen bereitgestellten Konfigurationsdatei ab. Nach Abschluss der Auswertung erstellt die Pipeline automatisch detaillierte Zusammenfassungs- und Auswertungs-Tabellen und fügt diese direkt an den PR an.

Wenn Sie mehrere Datenvalidierungsdateien konfigurieren, veröffentlicht die Pipeline die Ergebnisse für jede Datei als separaten PR-Kommentar. Dadurch erhalten die Prüfer einen klaren, umfassenden Überblick über den Konformitätsstatus in verschiedenen Kontexten, ohne dass die Ergebnisse miteinander vermischt werden.

In jedem PR-Kommentar findest du:

• Drei Auswertungs-Tabellen: Eine vollständige Aufschlüsselung der Validierungsergebnisse. Weitere Informationen zum Verständnis dieser Tabellen finden Sie unter „ Die Evidenz-Check-Tabelle verstehen “.
• Konfigurationslinks: Direkte Links zu der spezifischen Datenvalidierungsdatei und der Richtliniendatei, die für genau diese Auswertung verwendet wurden, wodurch sich Ihre Regeln leicht überprüfen und Fehler beheben lassen.

In der Phase der Aktionsvalidierung dient diese OPA-Konformitätsprüfung der Transparenz und dem Feedback. Wenn Verstöße gegen Ihre Regeln festgestellt werden, wird die Pipeline weder angehalten noch bricht sie ab. Stattdessen läuft die Pipeline bis zum Ende durch und veröffentlicht die detaillierten Ergebnisse im PR. Dadurch wird sichergestellt, dass Entwickler einen vollständigen Bericht über alle Compliance-Lücken erhalten und diese beheben können, ohne dass der Build während des Prozesses abstürzt.

Das „ table_results “-Objekt (für PR-Feedback)

Um die detaillierten Tabellen „ Markdown “ in Ihren PR-Kommentaren zu generieren, sucht die Pipeline nach einer bestimmten Datenstruktur namens „ table_results “.

Wenn Ihre Policy innerhalb von „ table_results “ ein „ res “-Objekt ausgibt, das genau diese acht Felder enthält, übernimmt die Pipeline. Es wertet Ihre Ausgabe sicher aus und wandelt sie automatisch in die übersichtliche, detaillierte Tabelle „ Markdown “ um, die Sie im PR sehen:

table_results contains res if {
    # ... your custom evaluation logic goes here ...
    
    # Map your findings to the contract structure
    res := {
        "RuleType":       "Required",       
        "AssetType":      "image",          
        "AssetId":        "12345678",      
        "EvidenceTypeId": "com.ibm.scan",   
        "Tool":           "zap",         
        "Status":         "failure",        
        "Source":         "ci-pipeline",    
        "Target":         "prod",           
    }
}

Die „ allow “-Regel (für die Pipeline-Ausführung)

Wie bereits erwähnt, ist der zweite obligatorische Bestandteil dieses Vertrags die „ allow “-Regel.

Warum ist dies erforderlich?

Während „ table_results “ die Berichterstellung zu Ihren Compliance-Prüfungen übernimmt, ist die Regel „ allow “ der eigentliche Kill-Switch für die Pipeline. Die Pipeline-Engine ist fest so programmiert, dass sie den booleschen Wert „ allow “ abfragt, um die endgültige Go/No-Go-Entscheidung zu treffen.

Wenn Sie eine benutzerdefinierte Richtliniendatei bereitstellen, aber vergessen, die Regel „ allow “ einzufügen, weiß die Pipeline nicht, wie sie fortfahren soll. Da hier ein striktes „Fail-Closed“-Sicherheitsmodell zum Einsatz kommt, wird der Pipeline-Lauf standardmäßig abgebrochen und die Bereitstellung blockiert.

OPA aktivieren

Um OPA-basiertes Compliance-Gating in Ihren CD- und CC-Pipelines zu aktivieren, müssen Sie das Flag „ opt-in-rego-translation “ explizit aktivieren (setzen Sie es auf „ true “ oder „ 1 “).

Konfigurationsbeschränkungen

Genau wie bei der Promotion-Pipeline können Sie sowohl eine Policy-Datei (Ihre Logik) als auch eine Datenvalidierungsdatei (Ihre Fakten) bereitstellen. Es gibt jedoch einen wesentlichen Unterschied: Die CD- und CC-Pipelines akzeptieren derzeit jeweils nur eine Datenvalidierungsdatei und keine durch Kommas getrennte Liste.

Anhänge zu Änderungsanträgen (CR) und Schritte zum Abschluss der Pipeline

Wenn Sie die CD-Pipeline ausführen, verarbeitet die Engine Ihre Datenvalidierungsdatei und fügt sie zu Prüfungszwecken Ihrem Änderungsantrag bei. Das Verhalten beim Anhängen von Dateien hängt vollständig vom von Ihnen angegebenen Format ab:

• Wenn Sie eine JSON-Datei zur Datenvalidierung im alten Format bereitstellen: Die Pipeline konvertiert diese automatisch im Hintergrund. Sowohl die ursprüngliche JSON-Datei als auch die generierte Rego-Konfigurationsdatei sind dem Schritt „Änderungsanforderung“ beigefügt.
• Wenn Sie eine native Rego-Datei zur Datenvalidierung bereitstellen: Die Pipeline bindet direkt nur die von Ihnen bereitgestellte Rego-Datei ein.

Genau dieses Bindungsverhalten gilt auch für den Prozess der Konfigurationswiederherstellung, der während des Schritts „CD Finish“ ganz am Ende der Pipeline stattfindet.