Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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:

Featurea chi appartiene il materialeche cosa scrive un’associazione
core/secret-valueun autore lo forniscedue foglie di values — vedi sotto
core/generated-secretil motore di destinazione lo crea e ne esegue la rotazionenulla; 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-clear

Il 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-secret

Entrambe 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.0

La 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 a origin nella 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.rego

Un 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

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # expected to fail
aggrega 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 violation

Leggi 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.rego

policy-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 violation

Non è 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 slot root_password legato da core/secret-value nell’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 propria directory: 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.yaml lega anche lo slot, sulla sua voce per db, con core/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:

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

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella:

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

Con 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/`.