La norme « allow »

En règle générale, votre dossier de police Rego doit comporter une clause d' allow. Dans le cadre de ce processus, il ne s'agit pas simplement d'une suggestion, mais d'une exigence stricte.

Le moteur de pipeline interroge spécifiquement la variable booléenne « allow » pour prendre la décision finale de déploiement (Go/No-Go). Si vous définissez une règle Rego personnalisée, vous devez définir explicitement cette règle. Si la règle « allow » est absente, ou si son évaluation donne « false », le pipeline s'arrête immédiatement, bloque le déploiement et affiche les messages de refus que vous avez définis.

Afin de garantir une sécurité maximale, l'OPA fonctionne selon un modèle strict de « fermeture en cas de défaillance ». Votre politique doit toujours être définie par défaut sur « false » et ne doit prendre la valeur « true » que si toutes les conditions de conformité requises sont remplies.

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
}

Fichiers de stratégie et fichiers de validation des données

Le fichier de stratégie (.rego)- La logique

C'est ici que vous rédigez vos règles et conditions proprement dites. Par exemple, votre politique pourrait stipuler : « Ne pas autoriser ce déploiement tant qu'un scan de vulnérabilité n'a pas été effectué et que les résultats n'indiquent aucune faille critique. » Vous pouvez fournir votre fichier de stratégie personnalisé à l'aide de la propriété d'environnement du pipeline « policy-path ». Si aucun fichier de stratégie n'est fourni, le pipeline utilise le fichier de stratégie par défaut.

Le fichier de validation des données (.json)- Les faits

Ce fichier sert de liste de référence statique. Au lieu d'intégrer directement des données dans vos règles Rego, vous utilisez ce fichier pour gérer des listes de variables approuvées, telles que vos registres d'images autorisés (us.icr.io ou eu.icr.io) ou des référentiels spécifiques exemptés de certaines vérifications. Vous pouvez fournir votre fichier de validation des données à l'aide de la propriété d'environnement du pipeline « evidence-checks-config-path ». Si aucun fichier de validation des données n'est fourni, le pipeline utilise le fichier de validation des données par défaut.

Exemple de fichier de validation des données :

        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": [
                "*"
                ]
            }
        }

Chaque bloc de la configuration définit précisément quelles preuves sont attendues, d'où elles proviennent et avec quel degré de rigueur elles doivent être exigées.

• L'identifiant du type de preuve (com.ibm.prod_change_request): cette clé de premier niveau définit la catégorie spécifique de la preuve faisant l'objet de l'évaluation. Parmi les exemples courants, on peut citer com.ibm.static-scan, com.ibm.unit-tests ou com.ibm.image_signing.
• asset_type: Définit le type d'artefact auquel s'applique cette règle. Par exemple, cela pourrait ne s'appliquer qu'à une adresse du type image ou repo. L'utilisation de l'option « ["*"] » applique la règle à tous les types d'actifs.
• source (Environnements sources): Définit d'où proviennent les éléments de preuve. Il peut s'agir d'une branche spécifique ou d'un environnement de pipeline (par exemple, ci-pipeline, stage, prod).
• target (Environnements cibles): définit l'environnement de destination dans lequel cet élément de preuve est en cours de validation en vue de son déploiement (par exemple, stage, prod). Pour plus d'informations sur l'environnement source et l'environnement cible, cliquez ici.
• gating mode: Les derniers champs indiquent le mode de filtrage que vous souhaitez appliquer à ce type de preuve. Vous trouverez ici plus d'informations sur les modes de déclenchement pris en charge.

Remarque : toutes les vérifications préalables au déploiement doivent être définies dans le tableau pre_deployment :{} , et toutes les vérifications postérieures au déploiement doivent être définies dans le tableau post_deployment :{} . De plus, si vous utilisez le chemin d'accès par défaut à la stratégie, vous devez impérativement inclure l'importation du package « one_pipeline.config » dans votre fichier de registre de validation des données.

Le script de conversion de JSON vers Rego

Bien que le pipeline prenne en charge nativement les fichiers de validation de données JSON hérités, vous pourriez à terme souhaiter moderniser vos configurations en Rego natif afin d’adopter pleinement la norme « policy-as-code ».

Pour vous faciliter la tâche, nous mettons à votre disposition un script utilitaire autonome qui convertit automatiquement vos fichiers de validation de données JSON existants au nouveau format Rego.

Emplacement du script : /opt/one-pipeline/polyglot/polyglot/translate-pipeline-config.sh

Comment utiliser le script de conversion

Vous pouvez exécuter ce script localement ou dans le cadre d'un pipeline. Lorsque vous exécutez le script en local, vous devez indiquer explicitement les environnements source et cible.

# 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

Configuration flexible : plusieurs fichiers de validation

Les environnements complexes nécessitent souvent des ensembles de règles modulaires. À cet effet, le pipeline de validation des promotions vous permet d'évaluer vos données par rapport à plusieurs configurations simultanément.

Vous pouvez fournir plusieurs fichiers de validation des données en transmettant leurs chemins d'accès sous forme de liste séparée par des virgules au paramètre « evidence-checks-config-path ». Dans ce cas, le pipeline analysera la charge utile « evidence » par rapport à chaque fichier de configuration et générera un tableau d'évaluation distinct pour chaque fichier. Et dans la section des commentaires de PR, vous verrez les tableaux d'évaluation de chaque fichier sous forme de commentaires distincts.

Retour d'information automatisé sur les relations publiques

Pour une visibilité optimale, le pipeline compare les données de preuve actuelles à chacun des fichiers de configuration que vous fournissez. Une fois l'évaluation terminée, le pipeline génère automatiquement des tableaux récapitulatifs et d'évaluation détaillés, qu'il ajoute directement à la pull request.

Si vous configurez plusieurs fichiers de validation des données, le pipeline publie les résultats de chaque fichier sous forme de commentaire distinct dans la demande de pull. Cela permet aux évaluateurs d'avoir une vue d'ensemble claire et exhaustive de l'état de conformité dans différents contextes, sans mélanger les résultats.

Dans chaque commentaire de relations publiques, vous trouverez :

• Trois tableaux d'évaluation: une analyse détaillée des résultats de validation. Pour plus d'informations sur la manière d'interpréter ces tableaux, consultez la section « Comprendre le tableau de vérification des données ».
• Liens de configuration: liens directs vers le fichier de validation des données et le fichier de stratégie spécifiques qui ont été utilisés pour effectuer cette évaluation précise, ce qui facilite l'audit et le dépannage de vos règles.

Au cours de la phase de validation de la promotion, ce contrôle de conformité OPA vise à assurer la transparence et à recueillir des retours d'expérience. Si des problèmes de conformité par rapport à vos règles sont détectés, le pipeline ne s'arrête pas et ne rencontre pas d'échec. Au lieu de cela, le pipeline termine son exécution et publie les résultats détaillés dans la pull request. Cela permet aux développeurs de disposer d'un rapport complet sur toutes les non-conformités et de les corriger sans que la compilation ne s'interrompe en cours de processus.

L'objet « table_results » (pour les commentaires sur les relations publiques)

Pour générer les tableaux détaillés d' Markdown s dans les commentaires de votre PR, le pipeline recherche une structure de données spécifique nommée « table_results ».

Si votre politique génère un objet res au sein de table_results contenant exactement ces huit champs, le pipeline prend le relais. Il analyse en toute sécurité vos données de sortie et les transforme automatiquement en un tableau « Markdown » clair et détaillé, tel que vous pouvez le voir dans la pull request :

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",           
    }
}

La règle « allow » (pour l'exécution en pipeline)

Comme indiqué précédemment, le deuxième élément obligatoire de ce contrat est la règle relative à l’ allow.

Pourquoi est-ce nécessaire?

Alors que la méthode table_results gère la création des rapports relatifs à vos contrôles de conformité, la règle allow constitue le véritable « kill switch » du pipeline. Le moteur de pipeline est programmé de manière fixe pour interroger la variable booléenne « allow » afin de déterminer la décision finale « Go » ou « No-Go ».

Si vous fournissez un fichier de stratégie personnalisé mais que vous oubliez d'y inclure la règle « allow », le pipeline ne sait pas comment procéder. Fonctionnant selon un modèle de sécurité « fail-closed » strict, le système interrompt par défaut l'exécution du pipeline et bloque le déploiement.

Activation de l'OPA

Pour activer le contrôle de conformité basé sur OPA dans vos pipelines CD et CC, vous devez activer explicitement le drapeau « opt-in-rego-translation » (en le définissant sur « true » ou « 1 »).

Contraintes de configuration

Tout comme pour le pipeline de promotion, vous pouvez fournir à la fois un fichier de règles (votre logique) et un fichier de validation des données (vos données). Il existe toutefois une différence majeure : les pipelines CD et CC n'acceptent actuellement qu'un seul fichier de validation des données à la fois, et non une liste de fichiers séparés par des virgules.

Pièces jointes aux demandes de modification (CR) et étapes de finalisation du pipeline

Lorsque vous lancez le pipeline CD, le moteur traite votre fichier de validation des données et l'associe à votre demande de modification à des fins d'audit. Le comportement des pièces jointes dépend entièrement du format que vous fournissez :

• Si vous fournissez un fichier de validation de données JSON hérité: le pipeline le convertit automatiquement en arrière-plan. Le fichier JSON d'origine et le fichier de configuration Rego généré sont tous deux joints à l'étape « Demande de modification ».
• Si vous fournissez un fichier de validation de données Rego natif: le pipeline intègre directement et uniquement le fichier Rego que vous avez fourni.

Ce même comportement d'association s'applique également au processus de reconstruction de la configuration qui a lieu lors de l'étape « CD Finish », à la toute fin du pipeline.