Una policy basata sull’unica foglia scritta dall’autore
Questo esempio insegna una regola interna e il fatto che la rende esprimibile:
Uno slot di credenziali può essere riempito. Non può essere riempito scrivendo il materiale nel sorgente proprio del workspace.
Due release, a una variabile di distanza: lo stesso database gestito, lo stesso slot di credenziali obbligatorio, riempito da due Features diverse — una che lo sviluppatore associa nell’Aggregate, l’altra che l’operatore associa nella Release. Una policy scritta dall’operatore rifiuta l’una e consente l’altra. Ciò che rende la coppia degna di essere eseguita è che entrambe le associazioni gestiscono materiale segreto — quindi la regola non può essere scritta a partire dalla domanda «questa associazione è sensibile?», e la policy di controllo più sotto mostra che cosa succede quando ci provi.
Tutto tranne due file di policy proviene dal catalogo della libreria standard, compresa l’entità Plugin di governance.
Lo slot, e le due Features che possono riempirlo
core/datastore/mariadb dichiara uno slot di credenziali obbligatorio:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true è lì un’affermazione sul punto di legame anziché su un particolare riempimento: qualunque cosa leghi questo slot gestisce materiale segreto. inject: [] chiude la consegna — la Recipe decide dove va la credenziale, e lo sviluppatore non lo impone.
Due Features della libreria standard legano quello slot, e modellano cicli di vita delle credenziali opposti:
| Feature | a chi appartiene il materiale | che cosa scrive un’associazione |
|---|---|---|
core/secret-value | un autore lo fornisce | due foglie di values — vedi sotto |
core/generated-secret | il motore di destinazione lo crea e ne esegue la rotazione | nulla; non dichiara values |
core/secret-value dichiara le sue due foglie in modo asimmetrico, e l’asimmetria è l’intero perno di questo esempio:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin porta il materiale ed è dichiarata sensibile. key è un nome di consegna ed è lasciata deliberatamente non marcata — una chiave indica dove si trova il materiale anziché essere il materiale, e ogni Recipe che implementa questa Feature la renderizza in chiaro.
core/generated-secret non dichiara affatto values, quindi un’associazione non ha nulla da scrivere. È l’omologo gestito dal motore e non una versione più debole della stessa cosa: porta la stessa etichetta di famiglia di credenziali, lega lo stesso slot, e le sue Recipes non renderizzano nulla, perché la credenziale appartiene al motore gestito dalla Recipe propria del componente.
Le due release
aggregate-authored.yaml lega lo slot nel modo fornito dall’autore: lo sviluppatore associa la credenziale nell’Aggregate, e l’associazione scrive entrambe le foglie:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearIl ramo delegato lo lega nel modo gestito dal motore, e quel legame spetta all’operatore: il fatto che il motore possieda la credenziale deriva dalla Recipe che il Manifest sceglie, quindi release-delegated.yaml associa core/generated-secret sulla sua voce per db, e aggregate-delegated.yaml è l’Aggregate scritto senza il suo blocco features::
components: db: features: root_password: type: core/generated-secretEntrambe le release condividono manifest.yaml, che lega tutti e tre i tipi per il target Terraform, quindi non è nel Manifest che le due differiscono:
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.0La policy
policy.rego, associata sul grafo di 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 elenca le foglie che il payload di questa associazione porta e il cui percorso la Feature associata dichiara sensibile, ciascuna come percorso puntato con il prefisso del pilastro. Il payload letto è quello che l’associazione finisce per portare, quindi una foglia che si trova su un valore che lo schema della Feature dichiara come default viene nominata al pari di una su cui ha scritto un autore. Due conseguenze, e l’esempio si regge su entrambe:
- Una foglia compare solo dove una dichiarazione la copre — la dichiarazione nomina quella foglia, o nomina un oggetto che la contiene, con una corrispondenza segmento per segmento sul percorso puntato. Nulla viene letto dal testo proprio del percorso e nessun valore viene ispezionato. Così
key, scritta accanto aoriginnella stessa associazione, non compare mai: la sua Feature non dichiara nulla al riguardo. - Un’associazione il cui payload non porta nulla su una foglia dichiarata non contribuisce nulla all’elenco. L’associazione della release delegata porta la risposta sull’intera associazione e nessun elenco per foglia, perché la chiave viene omessa dalla trasmissione quando sarebbe vuota.
L’associazione si trova in .aggrega-config.yaml al ruolo ir-verdict, che è il ruolo che riceve il grafo di build:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoUn ruolo di verdetto restituisce un’accettazione o un rifiuto e nient’altro. Può fermare questa build; non può riscrivere l’Aggregate per renderlo conforme, perché il codice che inoltra un verdetto non ha alcun modo di applicarne uno come modifica. Una Release che vuole la forma delegata la ottiene associando la Feature delegata — mai tramite una policy che ne sostituisca una di nascosto.
Eseguire la build di entrambe
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull riempie il lockfile durante la build; aggrega pull --release release-<arm>.yaml eseguito una volta in anticipo fa la stessa cosa e permette alle build successive di essere eseguite senza flag. L’output renderizzato e i lockfile sono generati, non distribuiti: questo esempio esegue il commit dei propri input e rigenera tutto il resto.
Che cosa ritorna
La release scritta dall’autore viene rifiutata, e la build esce con 1. E0005 è la diagnostica che porta il rifiuto di una policy — vedi il riferimento delle diagnostiche:
[… 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 violationLeggi il percorso della foglia. Il payload dell’associazione porta due valori; il rifiuto nomina values.origin e non menziona values.key. Quell’unica frase è la marcatura per foglia al lavoro — un’associazione, due foglie di payload, una dichiarazione, un rifiuto.
Il rifiuto arriva inoltre prima che qualcosa venga renderizzato. Nessuna directory dist/infra-authored/ viene creata, quindi non c’è alcun albero di artefatti parziale da ripulire e nulla su disco che un passo successivo possa scambiare per output.
La release delegata viene compilata, esce con 0 e scrive due file. dist/infra-delegated/terraform/aggrega.modules.tf, la configurazione radice del confine:
# 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"}e dist/infra-delegated/terraform/modules/db/main.tf, che si apre con un blocco di commenti # che identifica la build e poi porta il vincolo del provider AWS, la risorsa e l’output dell’indirizzo che la Recipe pubblica:
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 è la forma delegata che arriva nell’output: il motore detiene la credenziale, e la Release non nomina materiale da nessuna parte. La release consentita ha renderizzato un artefatto reale anziché passare non renderizzando nulla.
La policy di controllo: porre invece la domanda sull’intera associazione
Sostituisci la sorgente associata in .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego è la stessa visita basata su attachment.sensitive — un unico booleano per l’intera associazione — anziché sull’elenco per foglia:
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])}Esegui di nuovo la build di entrambe le release — e rimetti poi a posto policy.rego, dato che il resto di questa pagina lo presuppone. Ora vengono rifiutate entrambe, con la stessa frase:
[… 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 violationNon è la regola che scatta a sproposito — è la regola a cui viene posta una domanda più grossolana e che vi risponde correttamente. sensitive legge ciò che dichiarano le entità: qui è vero perché lo slot dichiara che qualunque cosa lo leghi gestisce materiale segreto, e lo slot lo dice chiunque lo riempia. L’associazione delegata non scrive nulla ed è comunque sensibile, quindi una regola basata su quella risposta non può affatto distinguere le due release. La release delegata è una build che la regola per foglia consente e che la regola sull’intera associazione non ha alcun modo di consentire.
Nemmeno il terzo fatto di sensibilità, sensitive_inject, aiuta: nomina le chiavi di consegna la cui chiave provides referenziata è dichiarata sensibile. Qui lo slot è chiuso alla consegna e la Feature fornita dall’autore non pubblica alcun pilastro provides, quindi in questo workspace non nomina nulla. Dei tre fatti, solo l’elenco per foglia risponde a «dove porta dati il payload di questa associazione», che è ciò di cui si occupa la regola interna.
Per tutti e tre i fatti affiancati, con le strutture del payload e i casi in cui ciascuno è la domanda giusta, vedi i fatti di associazione che una policy di governance legge. Per il socket stesso — i ruoli, le severità dei verdetti, il canale di input dell’operatore — vedi il socket delle policy, e per la collocazione delle policy nel prodotto, Governance e conformità.
Che cosa rende visibile questo target sulla forma scritta dall’autore
La Recipe del database gestito imposta incondizionatamente la direttiva della password gestita propria del motore e non legge alcuna credenziale iniettata, quindi su questo target arresta la build sull’associazione stessa scritta dall’autore, nominando lo slot, anziché accettare materiale che non ha dove finire. La policy la rifiuta prima, dove si trova davvero: in un file che il workspace tiene sotto controllo di versione. Questa è la questione di governance, ed è una questione separata da ciò che una Recipe qualsiasi avrebbe renderizzato.
Ed è anche per questo che le due Features sono omologhe anziché alternative di pari rango su ogni target. Lega la Feature fornita dall’autore dove detieni davvero la credenziale, e quella gestita dal motore dove la credenziale appartiene al target. La release scritta dall’autore di questo esempio è la discrepanza che una regola interna può cogliere meccanicamente.
Da dove proviene il plugin
Ogni entità che questo workspace consuma proviene dal catalogo pubblicato della libreria standard: il Component, le due Features, la Recipe, le due FeatureRecipes e l’entità Plugin di governance — lette dal registry dell’hub che .aggrega-config.yaml nomina, oppure da un checkout del catalogo (dove ottenerne uno) indicato con --catalog.
uri: governance/rego:0.9.0 nomina quell’entità Plugin. È un’identità: una coordinata <pluginType>/<name> più una versione, ed entrambe le metà fanno parte della forma. La versione è quella con cui il plugin è pubblicato — l’hub la pubblica come oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. La versione partecipa alla risoluzione: un’associazione che nomina una versione che nessuna directory di catalogo, nessun registry e nemmeno il binario aggrega stesso contiene arresta la build. Il binario contiene l’entità del motore solo alla versione della propria release.
Compilato con --catalog che indica un checkout del catalogo, l’esempio non ha bisogno di nient’altro: con il binario aggrega della release che l’associazione nomina, che contiene l’entità Plugin stessa, ogni entità si risolve senza rete, e il motore che viene eseguito è quello compilato nel binario aggrega. Senza di esso le entità vengono lette da hub.aggrega.ai.
Il motore Rego è compilato nel binario della CLI, e la sua versione è la release del compilatore che lo distribuisce. Un compilatore di un’altra release legge dall’hub l’entità Plugin che l’associazione nomina ed esegue il motore compilato al suo interno: la versione nell’associazione identifica l’entità, e non sceglie il motore.
File
aggregate-authored.yaml— lo slotroot_passwordlegato dacore/secret-valuenell’Aggregate, che scrive la chiave di consegna e il materiale.aggregate-delegated.yaml— lo stesso database senza alcuna associazione: lo sviluppatore non lega nulla.manifest.yaml— lega il tipo di componente ed entrambi i tipi di Feature alle loro Recipes Terraform. Condiviso da entrambe le release.release-negative-authored.yaml,release-delegated.yaml— uno per ramo, ciascuno con la propriadirectory:di confine. Non esiste un flag per la posizione dell’output, quindi con due release che condividono una directory la seconda sovrascriverebbe la prima.release-delegated.yamllega anche lo slot, sulla sua voce perdb, concore/generated-secret, senza scrivere nulla. Quale Feature riempie lo slot, e in quale documento, è l’unica differenza tra i due rami.policy.rego— la regola interna, basata sulla marcatura per foglia.policy-attachment-wide.rego— il controllo, basato sulla risposta sull’intera associazione. Non associato per impostazione predefinita..aggrega-config.yaml— il registry predefinito e l’associazione di governance.
Generare l’esempio
Puoi eseguire la build di questo esempio con i comandi qui sotto, oppure farla eseguire al tuo assistente IA.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example policy-payload-leaf-sensitivityPoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:
cd policy-payload-leaf-sensitivityBuild
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsCon un assistente AI
Un assistente IA configurato con gli strumenti di Aggrega può fare lo stesso: incolla questo prompt nell’assistente.
Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella Workspace non contiene ancora una cartella `policy-payload-leaf-sensitivity`, chiama una volta lo strumento `scaffold` con `example` impostato a `policy-payload-leaf-sensitivity` e senza `dir`: scrive l’esempio in una nuova cartella `policy-payload-leaf-sensitivity`. Poi chiama lo strumento `build` con `workspace_root` impostato a `policy-payload-leaf-sensitivity`, `release` impostato a `release-negative-authored.yaml`, `auto_pull` impostato a true e `write` impostato a true: deve essere rifiutata, quindi leggimi il rifiuto. Poi chiama lo strumento `build` allo stesso modo con `release` impostato a `release-delegated.yaml`. Dimmi quali file ha scritto questa seconda build; si trovano in `policy-payload-leaf-sensitivity/dist/`.