Uma política baseada na única folha que o autor escreveu
Este exemplo ensina uma regra interna e o fato que a torna expressável:
Um slot de credencial pode ser preenchido. Ele não pode ser preenchido escrevendo o material no próprio código-fonte do espaço de trabalho.
Duas releases, a uma variável de distância: o mesmo banco de dados gerenciado, o mesmo slot de credencial obrigatório, preenchido por duas Features diferentes — uma que o desenvolvedor vincula no Aggregate, a outra que o operador vincula na Release. Uma política escrita pelo operador recusa uma e permite a outra. O que faz o par valer a execução é que as duas vinculações lidam com material secreto — então a regra não pode ser escrita com base na pergunta “esta vinculação é sensível?”, e a política de controle mais abaixo mostra o que acontece quando você tenta.
Tudo, exceto dois arquivos de política, vem do catálogo da biblioteca padrão, incluindo a entidade Plugin de governança.
O slot, e as duas Features que podem preenchê-lo
core/datastore/mariadb declara um slot de credencial obrigatório:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true ali é uma afirmação sobre o ponto de associação, e não sobre um preenchimento específico: o que quer que associe este slot lida com material secreto. inject: [] fecha a entrega — a Recipe decide para onde vai a credencial, e o desenvolvedor não dita isso.
Duas Features da biblioteca padrão associam esse slot, e elas modelam ciclos de vida de credencial opostos:
| Feature | a quem pertence o material | o que uma vinculação escreve |
|---|---|---|
core/secret-value | um autor o fornece | duas folhas de values — veja abaixo |
core/generated-secret | o mecanismo de destino o provisiona e o rotaciona | nada; ela não declara values |
core/secret-value declara as suas duas folhas de forma assimétrica, e a assimetria é todo o eixo deste exemplo:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin carrega o material e é declarada sensível. key é um nome de entrega e é deliberadamente deixada sem marcação — uma chave nomeia onde o material fica, em vez de ser o material, e toda Recipe que implementa esta Feature a renderiza em texto claro.
core/generated-secret não declara values de forma alguma, então não há nada para uma vinculação escrever. Ela é o equivalente gerenciado pelo mecanismo, e não uma versão mais fraca da mesma coisa: carrega o mesmo rótulo de família de credencial, associa o mesmo slot, e as suas Recipes não renderizam nada, porque a credencial pertence ao mecanismo que a própria Recipe do componente gerencia.
As duas releases
aggregate-authored.yaml associa o slot da forma fornecida pelo autor: o desenvolvedor vincula a credencial no Aggregate, e a vinculação escreve as duas folhas:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearO ramo delegado o associa da forma gerenciada pelo mecanismo, e essa associação cabe ao operador: se o mecanismo é dono da credencial decorre da Recipe que o Manifest escolhe, então release-delegated.yaml vincula core/generated-secret na sua entrada para db, e aggregate-delegated.yaml é o Aggregate escrito sem o seu bloco features::
components: db: features: root_password: type: core/generated-secretAs duas releases compartilham manifest.yaml, que associa os três tipos para o destino Terraform, então não é no Manifest que as duas diferem:
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.0A política
policy.rego, vinculada sobre o grafo 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 lista as folhas que o payload desta vinculação carrega e cujo caminho a Feature vinculada declara sensível, cada uma como um caminho pontilhado prefixado pelo pilar. O payload lido é aquele que a vinculação acaba carregando, então uma folha que está em um valor que o schema da Feature declara como default é nomeada da mesma forma que uma em que um autor escreveu. Duas consequências, e o exemplo depende de ambas:
- Uma folha aparece apenas onde uma declaração a cobre — a declaração nomeia essa folha, ou nomeia um objeto que a contém, com correspondência segmento a segmento sobre o caminho pontilhado. Nada é lido do próprio texto do caminho e nenhum valor é inspecionado. Assim,
key, escrita ao lado deoriginna mesma vinculação, nunca aparece: a sua Feature não declara nada sobre ela. - Uma vinculação cujo payload não carrega nada em uma folha declarada não contribui com nada para a lista. A vinculação da release delegada carrega a resposta da vinculação inteira e nenhuma lista por folha, porque a chave é omitida da transmissão quando estaria vazia.
A vinculação fica em .aggrega-config.yaml no papel ir-verdict, que é o papel que recebe o grafo de build:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoUm papel de veredito retorna uma aceitação ou uma recusa e nada mais. Ele pode parar este build; não pode reescrever o Aggregate para torná-lo conforme, porque o caminho que despacha um veredito não tem como aplicar um como alteração. Uma Release que quer a forma delegada a obtém vinculando a Feature delegada — nunca por uma política que substitua uma silenciosamente.
Fazer o build das duas
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull preenche o arquivo de bloqueio durante o build; aggrega pull --release release-<arm>.yaml executado uma vez antes faz a mesma coisa e permite que builds posteriores rodem sem nenhuma flag. A saída renderizada e os arquivos de bloqueio são gerados, não distribuídos: este exemplo faz commit das suas entradas e regenera todo o resto.
O que volta
A release escrita pelo autor é recusada, e o build sai com 1. E0005 é o diagnóstico que uma recusa de política carrega — veja a referência de diagnósticos:
[… 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 violationLeia o caminho da folha. O payload da vinculação carrega dois valores; a recusa nomeia values.origin e não menciona values.key. Essa única frase é a marcação por folha em ação — uma vinculação, duas folhas de payload, uma declaração, uma recusa.
A recusa também chega antes que qualquer coisa seja renderizada. Nenhum diretório dist/infra-authored/ é criado, então não há nenhuma árvore de artefatos parcial para limpar nem nada no disco que uma etapa posterior possa confundir com saída.
A release delegada é compilada, sai com 0 e escreve dois arquivos. dist/infra-delegated/terraform/aggrega.modules.tf, a configuração raiz da fronteira:
# 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, que começa com um bloco de comentários # identificando o build e depois traz a restrição do provedor AWS, o recurso e a saída de endereço que a Recipe publica:
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 é a forma delegada chegando à saída: o mecanismo guarda a credencial, e a Release não nomeia material em lugar nenhum. A release permitida renderizou um artefato real em vez de passar sem renderizar nada.
A política de controle: fazer, em vez disso, a pergunta sobre a vinculação inteira
Troque a fonte vinculada em .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego é o mesmo percurso baseado em attachment.sensitive — um único booleano para a vinculação inteira — em vez de na lista por folha:
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])}Refaça o build das duas releases — e coloque policy.rego de volta depois, já que o resto desta página pressupõe isso. As duas agora são recusadas, com a mesma 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 violationNão é a regra disparando por engano — é a regra recebendo uma pergunta mais grosseira e respondendo-a corretamente. sensitive lê o que as entidades declaram: é verdadeiro aqui porque o slot declara que o que quer que o associe lida com material secreto, e o slot diz isso seja quem for que o preencha. A vinculação delegada não escreve nada e mesmo assim é sensível, então uma regra baseada nessa resposta não consegue distinguir de forma alguma as duas releases. A release delegada é um build que a regra por folha permite e que a regra da vinculação inteira não tem como permitir.
O terceiro fato de sensibilidade, sensitive_inject, também não ajuda: ele nomeia as chaves de entrega cuja chave provides referenciada é declarada sensível. Aqui o slot é fechado à entrega e a Feature fornecida pelo autor não publica nenhum pilar provides, então neste espaço de trabalho ele não nomeia nada. Dos três fatos, só a lista por folha responde a “onde o payload desta vinculação carrega dados”, que é do que trata a regra interna.
Para os três fatos lado a lado, com as estruturas do payload e os casos em que cada um é a pergunta certa, veja os fatos de vinculação que uma política de governança lê. Para o socket em si — os papéis, as severidades do veredito, o canal de entrada do operador — veja o socket de políticas, e para o lugar da política no produto, Governança e conformidade.
O que este destino torna visível sobre a forma escrita pelo autor
A Recipe do banco de dados gerenciado define incondicionalmente a diretiva de senha gerenciada do próprio mecanismo e não lê nenhuma credencial injetada, então, neste destino, ela interrompe o build já na própria vinculação escrita pelo autor, nomeando o slot, em vez de aceitar material que não tem onde ir parar. A política a recusa antes, onde ela realmente está: em um arquivo que o espaço de trabalho mantém sob controle de versão. Essa é a questão de governança, e ela é distinta do que qualquer Recipe teria renderizado.
É também por isso que as duas Features são equivalentes, e não alternativas de igual peso em todo destino. Associe a Feature fornecida pelo autor onde você realmente detém a credencial, e a gerenciada pelo mecanismo onde o destino é dono dela. A release escrita pelo autor deste exemplo é o descompasso que uma regra interna consegue detectar mecanicamente.
De onde vem o plugin
Toda entidade que este espaço de trabalho consome vem do catálogo publicado da biblioteca padrão: o Component, as duas Features, a Recipe, as duas FeatureRecipes e a entidade Plugin de governança — lidas do registry do hub que .aggrega-config.yaml nomeia, ou de um checkout do catálogo (onde obter um) nomeado com --catalog.
uri: governance/rego:0.9.0 nomeia essa entidade Plugin. É uma identidade: uma coordenada <pluginType>/<name> mais uma versão, e as duas metades fazem parte da forma. A versão é aquela com que o plugin é publicado — o hub a publica como oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. A versão participa da resolução: uma vinculação que nomeia uma versão que nenhum diretório de catálogo, nenhum registry e nem o próprio binário aggrega traz interrompe o build. O binário traz a entidade do mecanismo apenas na versão da sua própria release.
Com o build feito com --catalog nomeando um checkout do catálogo, o exemplo não precisa de mais nada: com o binário aggrega da versão que a vinculação nomeia, que traz a própria entidade Plugin, toda entidade é resolvida sem rede, e o mecanismo que roda é o compilado no binário aggrega. Sem essa opção, as entidades são lidas de hub.aggrega.ai.
O mecanismo Rego é compilado no binário da CLI, e sua versão é a versão do compilador que o distribui. Um compilador de outra versão lê do hub a entidade Plugin que a vinculação nomeia e executa o mecanismo compilado nele: a versão na vinculação identifica a entidade e não escolhe o mecanismo.
Arquivos
aggregate-authored.yaml— o slotroot_passwordassociado porcore/secret-valueno Aggregate, escrevendo a chave de entrega e o material.aggregate-delegated.yaml— o mesmo banco de dados sem vinculação: o desenvolvedor não associa nada.manifest.yaml— associa o tipo de componente e os dois tipos de Feature às suas Recipes Terraform. Compartilhado pelas duas releases.release-negative-authored.yaml,release-delegated.yaml— um por ramo, cada um com o seu própriodirectory:de fronteira. Não há flag para o local da saída, então duas releases compartilhando um diretório fariam a segunda sobrescrever a primeira.release-delegated.yamltambém associa o slot, na sua entrada paradb, comcore/generated-secret, sem escrever nada. Qual Feature preenche o slot, e em qual documento, é a única diferença entre os dois ramos.policy.rego— a regra interna, baseada na marcação por folha.policy-attachment-wide.rego— o controle, baseado na resposta da vinculação inteira. Não vinculado por padrão..aggrega-config.yaml— o registry padrão e a vinculação de governança.
Gerar o exemplo
Você pode fazer o build deste exemplo com os comandos abaixo, ou pedir ao seu assistente de IA que faça o build por você.
Escreva o exemplo em uma nova pasta com o nome dele:
aggrega scaffold --example policy-payload-leaf-sensitivityEm seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:
cd policy-payload-leaf-sensitivityBuild
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsCom um assistente de IA
Um assistente de IA configurado com as ferramentas do Aggrega pode fazer o mesmo: cole este prompt nele.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por conta própria. Se a pasta Workspace ainda não contiver uma pasta `policy-payload-leaf-sensitivity`, chame uma vez a ferramenta `scaffold` com `example` definido como `policy-payload-leaf-sensitivity` e sem `dir`: ela grava o exemplo em uma nova pasta `policy-payload-leaf-sensitivity`. Em seguida, chame a ferramenta `build` com `workspace_root` definido como `policy-payload-leaf-sensitivity`, `release` definido como `release-negative-authored.yaml`, `auto_pull` definido como true e `write` definido como true: ele deve ser recusado, então leia para mim a recusa. Depois, chame a ferramenta `build` da mesma forma com `release` definido como `release-delegated.yaml`. Diga-me quais arquivos esse segundo build gravou; eles ficam em `policy-payload-leaf-sensitivity/dist/`.