Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Une politique fondée sur la seule feuille que l’auteur a écrite

Cet exemple enseigne une règle maison et le fait qui la rend exprimable :

Un emplacement d’identifiants peut être rempli. Il ne peut pas l’être en écrivant le contenu secret dans les propres sources de l’espace de travail.

Deux releases, à une variable près : la même base de données managée, le même emplacement d’identifiants obligatoire, rempli par deux Features différentes — l’une que le développeur rattache dans l’Aggregate, l’autre que l’opérateur rattache dans la Release. Une politique écrite par l’opérateur refuse l’une et autorise l’autre. Ce qui rend la paire intéressante à exécuter, c’est que les deux rattachements manipulent du contenu secret — si bien que la règle ne peut pas être écrite à partir de la question « ce rattachement est-il sensible ? », et la politique témoin ci-dessous montre ce qui se passe quand vous essayez.

Tout, sauf deux fichiers de politique, provient du catalogue de la bibliothèque standard, y compris l’entité Plugin de gouvernance.

L’emplacement, et les deux Features qui peuvent le remplir

core/datastore/mariadb déclare un emplacement d’identifiants obligatoire :

featuresSchema:
root_password:
required: true
sensitive: true
inject: []
description: Root database password. Recipe controls delivery (Black-Box).

sensitive: true y est une affirmation sur le point de liaison plutôt que sur un remplissage particulier : quoi que ce soit qui lie cet emplacement manipule du contenu secret. inject: [] ferme la livraison — la Recipe décide où vont les identifiants, et le développeur ne l’impose pas.

Deux Features de la bibliothèque standard lient cet emplacement, et elles modélisent des cycles de vie d’identifiants opposés :

Featureà qui appartient le contenuce qu’un rattachement écrit
core/secret-valueun auteur le fournitdeux feuilles de values — voir ci-dessous
core/generated-secretle moteur cible le provisionne et en assure la rotationrien ; elle ne déclare pas de values

core/secret-value déclare ses deux feuilles de façon asymétrique, et cette asymétrie est tout le pivot de cet exemple :

values:
origin: { type: string, sensitive: true }
key: { type: string, required: true, default: "value" }

origin porte le contenu et est déclarée sensible. key est un nom de livraison et est délibérément laissée sans marque — une clé nomme où se trouve le contenu plutôt que d’être le contenu, et chaque Recipe qui implémente cette Feature la rend en clair.

core/generated-secret ne déclare pas de values du tout, si bien qu’un rattachement n’a rien à écrire. C’est l’homologue géré par le moteur plutôt qu’une version plus faible de la même chose : elle porte le même label de famille d’identifiants, elle lie le même emplacement, et ses Recipes ne rendent rien, car les identifiants appartiennent au moteur que gère la propre Recipe du composant.

Les deux releases

aggregate-authored.yaml lie l’emplacement de la façon fournie par l’auteur : le développeur rattache les identifiants dans l’Aggregate, et le rattachement écrit les deux feuilles :

features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: root-password-in-the-clear

La branche déléguée le lie de la façon gérée par le moteur, et cette liaison revient à l’opérateur : que le moteur possède les identifiants découle de la Recipe que choisit le Manifest, si bien que release-delegated.yaml rattache core/generated-secret sur son entrée pour db, et aggregate-delegated.yaml est l’Aggregate écrit sans son bloc features: :

components:
db:
features:
root_password:
type: core/generated-secret

Les deux releases partagent manifest.yaml, qui lie les trois types pour la cible Terraform, si bien que ce n’est pas dans le Manifest que les deux diffèrent :

components:
type:
core/datastore/mariadb:1.0.0: terraform/mariadb-rds:1.0.0
features:
type:
core/secret-value:1.0.0: terraform/variable-secret:1.0.0
core/generated-secret:1.0.0: terraform/generated-secret:1.0.0

La politique

policy.rego, rattachée sur le graphe de build :

package house.governance
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
some leaf in attachment.sensitive_payload_leaves
msg := sprintf("%v: the %v credential carries declared-sensitive material in its payload at %v", [node_id, attachment_name, leaf])
}

sensitive_payload_leaves liste les feuilles que porte la charge utile de ce rattachement et dont la Feature rattachée déclare le chemin sensible, chacune sous forme de chemin pointé préfixé par le pilier. La charge utile lue est celle que le rattachement finit par porter, si bien qu’une feuille qui se trouve à une valeur que le schéma de la Feature déclare comme default est nommée au même titre qu’une feuille qu’un auteur y a écrite. Deux conséquences, et l’exemple repose sur les deux :

  • Une feuille n’apparaît que là où une déclaration la couvre — la déclaration nomme cette feuille, ou nomme un objet qui la contient, avec une correspondance segment par segment sur le chemin pointé. Rien n’est lu dans le texte propre du chemin et aucune valeur n’est inspectée. Ainsi, key, écrite à côté de origin dans le même rattachement, n’apparaît jamais : sa Feature ne déclare rien à son sujet.
  • Un rattachement dont la charge utile ne porte rien à une feuille déclarée n’apporte rien à la liste. Le rattachement de la release déléguée porte la réponse portant sur tout le rattachement et aucune liste par feuille, car la clé est omise de la transmission lorsqu’elle serait vide.

Le rattachement se trouve dans .aggrega-config.yaml au rôle ir-verdict, qui est le rôle qui reçoit le graphe de build :

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policy.rego

Un rôle de verdict renvoie une acceptation ou un refus, et rien d’autre. Il peut arrêter ce build ; il ne peut pas réécrire l’Aggregate pour le rendre conforme, car le code qui transmet un verdict n’a aucun moyen d’en appliquer un comme modification. Une Release qui veut la forme déléguée l’obtient en rattachant la Feature déléguée — jamais par une politique qui en substituerait une discrètement.

Construire les deux

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # expected to fail
aggrega build --release release-delegated.yaml --auto-pull

--auto-pull remplit le fichier de verrouillage pendant le build ; aggrega pull --release release-<arm>.yaml exécuté une fois au préalable fait la même chose et permet aux builds suivants de s’exécuter sans option. La sortie rendue et les fichiers de verrouillage sont générés, et non livrés : cet exemple commite ses entrées et régénère tout le reste.

Ce qui en ressort

La release écrite par l’auteur est refusée, et le build se termine avec 1. E0005 est le diagnostic que porte un refus de politique — voir la référence des diagnostics :

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential carries declared-sensitive material in its payload at values.origin
caused by: policy violation

Lisez le chemin de la feuille. La charge utile du rattachement porte deux valeurs ; le refus nomme values.origin et ne mentionne pas values.key. Cette seule phrase, c’est le marquage par feuille à l’œuvre — un rattachement, deux feuilles de charge utile, une déclaration, un refus.

Le refus arrive aussi avant que quoi que ce soit ne soit rendu. Aucun répertoire dist/infra-authored/ n’est créé, si bien qu’il n’y a aucune arborescence d’artefacts partielle à nettoyer et rien sur le disque qu’une étape ultérieure pourrait prendre pour une sortie.

La release déléguée se construit, se termine avec 0 et écrit deux fichiers. dist/infra-delegated/terraform/aggrega.modules.tf, la configuration racine de la frontière :

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "db" {
source = "./modules/db"
}

et dist/infra-delegated/terraform/modules/db/main.tf, qui s’ouvre sur un bloc de commentaires # identifiant le build, puis porte la contrainte du fournisseur AWS, la ressource et la sortie d’adresse que publie la Recipe :

terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.69"
}
}
}
resource "aws_db_instance" "db" {
identifier = "db"
engine = "mariadb"
engine_version = "11.4"
port = 3306
## ── Compute ──────────────────────────────────────────────
instance_class = "db.t3.small"
## ── Storage ──────────────────────────────────────────────
allocated_storage = 100
storage_type = "gp3"
## ── Database ─────────────────────────────────────────────
db_name = "appdb"
username = "admin"
## Black-Box: RDS manages the password via Secrets Manager.
manage_master_user_password = true
## ── HA ───────────────────────────────────────────────────
multi_az = false
## ── Backup ───────────────────────────────────────────────
backup_retention_period = 7
## ── Provider-specific overrides ──────────────────────────
}
output "address" {
value = aws_db_instance.db.address
}

manage_master_user_password = true est la forme déléguée qui arrive dans la sortie : le moteur détient les identifiants, et la Release ne nomme de contenu secret nulle part. La release autorisée a rendu un véritable artefact au lieu de passer en ne rendant rien.

La politique témoin : poser plutôt la question sur tout le rattachement

Remplacez la source rattachée dans .aggrega-config.yaml :

sources:
- policy-attachment-wide.rego

policy-attachment-wide.rego est le même parcours fondé sur attachment.sensitive — un seul booléen pour tout le rattachement — au lieu de la liste par feuille :

deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
attachment.sensitive
msg := sprintf("%v: the %v credential handles sensitive material", [node_id, attachment_name])
}

Reconstruisez les deux releases — et remettez policy.rego en place ensuite, puisque le reste de cette page le suppose. Les deux sont désormais refusées, avec la même phrase :

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential handles sensitive material
caused by: policy violation

Ce n’est pas la règle qui se déclenche à tort — c’est la règle à qui l’on pose une question plus grossière et qui y répond correctement. sensitive lit ce que les entités déclarent : il est vrai ici parce que l’emplacement déclare que quoi que ce soit qui le lie manipule du contenu secret, et l’emplacement le dit quel que soit celui qui le remplit. Le rattachement délégué n’écrit rien et est pourtant sensible, si bien qu’une règle fondée sur cette réponse ne peut pas du tout distinguer les deux releases. La release déléguée est un build que la règle par feuille autorise et que la règle portant sur tout le rattachement n’a aucun moyen d’autoriser.

Le troisième fait de sensibilité, sensitive_inject, n’aide pas non plus : il nomme les clés de livraison dont la clé provides référencée est déclarée sensible. Ici, l’emplacement est fermé à la livraison et la Feature fournie par l’auteur ne publie aucun pilier provides, si bien que dans cet espace de travail il ne nomme rien. Des trois faits, seule la liste par feuille répond à « où la charge utile de ce rattachement porte-t-elle des données », ce qui est précisément l’objet de la règle maison.

Pour les trois faits côte à côte, avec les structures de charge utile et les cas où chacun est la bonne question, voir les faits de rattachement que lit une politique de gouvernance. Pour le socket lui-même — les rôles, les niveaux de gravité des verdicts, le canal d’entrée de l’opérateur — voir le socket de politiques, et pour la place de la politique dans le produit, Gouvernance et conformité.

Ce que cette cible rend visible de la forme écrite par l’auteur

La Recipe de la base de données managée définit sans condition la directive de mot de passe managé propre au moteur et ne lit aucun identifiant injecté, si bien que sur cette cible elle arrête le build sur le rattachement écrit par l’auteur lui-même, en nommant l’emplacement, plutôt que d’accepter un contenu qui n’a nulle part où aboutir. La politique le refuse d’abord, là où il se trouve réellement : dans un fichier que l’espace de travail conserve sous gestion de versions. C’est cela, la préoccupation de gouvernance, et c’est une question distincte de ce qu’une Recipe quelconque aurait rendu.

C’est aussi pourquoi les deux Features sont des homologues plutôt que des alternatives de même rang sur chaque cible. Liez la Feature fournie par l’auteur là où vous détenez réellement les identifiants, et celle gérée par le moteur là où la cible les possède. La release écrite par l’auteur de cet exemple est l’inadéquation qu’une règle maison peut détecter mécaniquement.

D’où vient le plugin

Chaque entité que consomme cet espace de travail provient du catalogue publié de la bibliothèque standard : le Component, les deux Features, la Recipe, les deux FeatureRecipes et l’entité Plugin de gouvernance — lues depuis le registre du hub que nomme .aggrega-config.yaml, ou depuis un checkout du catalogue (où en obtenir un) nommé avec --catalog.

uri: governance/rego:0.9.0 nomme cette entité Plugin. C’est une identité : une coordonnée <pluginType>/<name> plus une version, et les deux moitiés font partie de la forme. La version est celle sous laquelle le plugin est publié — le hub la publie sous la forme oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. La version intervient dans la résolution : un rattachement qui nomme une version que ne porte aucun répertoire de catalogue, aucun registre ni le binaire aggrega lui-même arrête le build. Le binaire ne porte l’entité du moteur qu’à la version de sa propre release.

Construit avec --catalog nommant un checkout du catalogue, l’exemple n’a besoin de rien d’autre : avec le binaire aggrega de la version que nomme le rattachement, qui porte lui-même l’entité Plugin, chaque entité est résolue sans réseau, et le moteur qui s’exécute est celui compilé dans le binaire aggrega. Sans cette option, les entités sont lues depuis hub.aggrega.ai.

Le moteur Rego est compilé dans le binaire de la CLI, et sa version est la version du compilateur qui le livre. Un compilateur d’une autre version lit depuis le hub l’entité Plugin que nomme le rattachement et exécute le moteur compilé en lui : la version indiquée dans le rattachement identifie l’entité et ne choisit pas le moteur.

Fichiers

  • aggregate-authored.yaml — l’emplacement root_password lié par core/secret-value dans l’Aggregate, qui écrit la clé de livraison et le contenu secret.
  • aggregate-delegated.yaml — la même base de données sans rattachement : le développeur ne lie rien.
  • manifest.yaml — lie le type de composant et les deux types de Feature à leurs Recipes Terraform. Partagé par les deux releases.
  • release-negative-authored.yaml, release-delegated.yaml — un par branche, chacun avec son propre directory: de frontière. Il n’existe aucune option pour l’emplacement de sortie, si bien que deux releases partageant un répertoire verraient la seconde écraser la première. release-delegated.yaml lie aussi l’emplacement, sur son entrée pour db, avec core/generated-secret, sans rien écrire. Quelle Feature remplit l’emplacement, et dans quel document, est la seule différence entre les deux branches.
  • policy.rego — la règle maison, fondée sur le marquage par feuille.
  • policy-attachment-wide.rego — le témoin, fondé sur la réponse portant sur tout le rattachement. Non rattaché par défaut.
  • .aggrega-config.yaml — le registre par défaut et le rattachement de gouvernance.

Générer l’exemple

Vous pouvez construire cet exemple avec les commandes ci-dessous, ou le faire construire pour vous par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

Terminal window
aggrega scaffold --example policy-payload-leaf-sensitivity

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier :

Terminal window
cd policy-payload-leaf-sensitivity

Build

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1
aggrega build --release release-delegated.yaml --auto-pull # builds

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-lui ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier Workspace ne contient pas encore de dossier `policy-payload-leaf-sensitivity`, appelez une fois l’outil `scaffold` avec `example` défini sur `policy-payload-leaf-sensitivity` et sans `dir` : il écrit l’exemple dans un nouveau dossier `policy-payload-leaf-sensitivity`. Appelez ensuite l’outil `build` avec `workspace_root` défini sur `policy-payload-leaf-sensitivity`, `release` défini sur `release-negative-authored.yaml`, `auto_pull` défini sur true et `write` défini sur true : ce build doit être refusé, lisez-moi donc le refus. Appelez ensuite l’outil `build` de la même façon avec `release` défini sur `release-delegated.yaml`. Indiquez-moi quels fichiers ce deuxième build a écrits ; ils se trouvent sous `policy-payload-leaf-sensitivity/dist/`.