Uma política baseada na única folha que o autor escreveu
Este exemplo ensina uma regra interna e o facto que a torna exprimível:
Uma ranhura de credencial pode ser preenchida. Não pode ser preenchida escrevendo o material no próprio código-fonte do espaço de trabalho.
Duas releases, a uma variável de distância: a mesma base de dados gerida, a mesma ranhura de credencial obrigatória, preenchida por duas Features diferentes — uma que o programador anexa no Aggregate, a outra que o operador anexa na Release. Uma política escrita pelo operador recusa uma e permite a outra. O que faz com que valha a pena executar o par é que ambos os anexos lidam com material secreto — pelo que a regra não pode ser escrita a partir da pergunta «este anexo é sensível?», e a política de controlo mais abaixo mostra o que acontece quando se tenta.
Tudo, exceto dois ficheiros de política, vem do catálogo da biblioteca standard, incluindo a entidade Plugin de governação.
A ranhura, e as duas Features que a podem preencher
core/datastore/mariadb declara uma ranhura de credencial obrigatória:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true é aí uma afirmação sobre o ponto de associação e não sobre um preenchimento em particular: o que quer que associe esta ranhura lida com material secreto. inject: [] fecha a entrega — a Recipe decide para onde vai a credencial, e o programador não o dita.
Duas Features da biblioteca standard associam essa ranhura, e modelam ciclos de vida de credencial opostos:
| Feature | a quem pertence o material | o que um anexo escreve |
|---|---|---|
core/secret-value | um autor fornece-o | duas folhas de values — ver abaixo |
core/generated-secret | o motor de destino aprovisiona-o e faz a sua rotação | nada; 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 contém o material e está declarada como sensível. key é um nome de entrega e é deliberadamente deixada sem marcação — uma chave nomeia onde o material está, em vez de ser o material, e cada Recipe que implementa esta Feature renderiza-a em claro.
core/generated-secret não declara values de todo, pelo que não há nada para um anexo escrever. É o equivalente gerido pelo motor e não uma versão mais fraca da mesma coisa: tem a mesma etiqueta de família de credenciais, associa a mesma ranhura, e as suas Recipes não renderizam nada, porque a credencial pertence ao motor que a própria Recipe do componente gere.
As duas releases
aggregate-authored.yaml associa a ranhura da forma fornecida pelo autor: o programador anexa a credencial no Aggregate, e o anexo escreve ambas as folhas:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearO ramo delegado associa-a da forma gerida pelo motor, e essa associação cabe ao operador: o facto de o motor ser dono da credencial decorre da Recipe que o Manifest escolhe, pelo que release-delegated.yaml anexa 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-secretAmbas as releases partilham manifest.yaml, que associa os três tipos para o destino Terraform, pelo que 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, anexada sobre o grafo de compilação:
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 deste anexo contém e cujo caminho a Feature anexada declara sensível, cada uma como um caminho com pontos prefixado pelo pilar. O payload lido é aquele que o anexo acaba por conter, pelo que uma folha que está num valor que o esquema da Feature declara como default é nomeada tal como uma em que um autor escreveu. Duas consequências, e o exemplo assenta em ambas:
- Uma folha só aparece 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 com pontos. Nada é lido do próprio texto do caminho e nenhum valor é inspecionado. Assim,
key, escrita ao lado deoriginno mesmo anexo, nunca aparece: a sua Feature não declara nada sobre ela. - Um anexo cujo payload não contém nada numa folha declarada não contribui com nada para a lista. O anexo da release delegada contém a resposta do anexo inteiro e nenhuma lista por folha, porque a chave é omitida da transmissão quando estaria vazia.
O anexo está em .aggrega-config.yaml no papel ir-verdict, que é o papel que recebe o grafo de compilação:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoUm papel de veredicto devolve uma aceitação ou uma recusa e nada mais. Pode parar esta compilação; não pode reescrever o Aggregate para o tornar conforme, porque o caminho que despacha um veredicto não tem forma de aplicar um como alteração. Uma Release que quer a forma delegada obtém-na anexando a Feature delegada — nunca através de uma política que substitua uma discretamente.
Compilar ambas
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull preenche o ficheiro de bloqueio durante a compilação; aggrega pull --release release-<arm>.yaml executado uma vez antes faz o mesmo e permite que as compilações posteriores sejam executadas sem nenhuma flag. A saída renderizada e os ficheiros de bloqueio são gerados, não distribuídos: este exemplo faz commit das suas entradas e regenera todo o resto.
O que é devolvido
A release escrita pelo autor é recusada, e a compilação termina com 1. E0005 é o diagnóstico que uma recusa de política transporta — consulte-se 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-se o caminho da folha. O payload do anexo contém dois valores; a recusa nomeia values.origin e não menciona values.key. Essa única frase é a marcação por folha em ação — um anexo, duas folhas de payload, uma declaração, uma recusa.
A recusa também chega antes de qualquer coisa ser renderizada. Nenhum diretório dist/infra-authored/ é criado, pelo que não há nenhuma árvore de artefactos parcial para limpar nem nada no disco que uma etapa posterior possa confundir com saída.
A release delegada é compilada, termina com 0 e escreve dois ficheiros. 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 abre com um bloco de comentários # que identifica a compilação e depois contém a restrição do fornecedor 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 a chegar à saída: o motor detém a credencial, e a Release não nomeia material em lado nenhum. A release permitida renderizou um artefacto real em vez de passar sem renderizar nada.
A política de controlo: fazer antes a pergunta sobre o anexo inteiro
Troque-se a fonte anexada em .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego é o mesmo percurso baseado em attachment.sensitive — um único booleano para o anexo inteiro — 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])}Recompilem-se as duas releases — e reponha-se policy.rego depois, uma vez que o resto desta página o pressupõe. Ambas são agora 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 se trata de a regra disparar por engano — trata-se de a regra receber uma pergunta mais grosseira e responder-lhe corretamente. sensitive lê o que as entidades declaram: é verdadeiro aqui porque a ranhura declara que o que quer que a associe lida com material secreto, e a ranhura di-lo seja quem for que a preencha. O anexo delegado não escreve nada e mesmo assim é sensível, pelo que uma regra baseada nessa resposta não consegue de todo distinguir as duas releases. A release delegada é uma compilação que a regra por folha permite e que a regra do anexo inteiro não tem forma de permitir.
O terceiro facto de sensibilidade, sensitive_inject, também não ajuda: nomeia as chaves de entrega cuja chave provides referenciada está declarada como sensível. Aqui a ranhura está fechada à entrega e a Feature fornecida pelo autor não publica nenhum pilar provides, pelo que neste espaço de trabalho não nomeia nada. Dos três factos, só a lista por folha responde a «onde é que o payload deste anexo contém dados», que é aquilo de que trata a regra interna.
Para os três factos lado a lado, com as estruturas do payload e os casos em que cada um é a pergunta certa, ver os factos de anexo que uma política de governação lê. Para o socket em si — os papéis, as severidades do veredicto, o canal de entrada do operador — ver o socket de políticas, e para o lugar da política no produto, Governação e conformidade.
O que este destino torna visível sobre a forma escrita pelo autor
A Recipe da base de dados gerida define incondicionalmente a diretiva de palavra-passe gerida do próprio motor e não lê nenhuma credencial injetada, pelo que, neste destino, interrompe a compilação no próprio anexo escrito pelo autor, nomeando a ranhura, em vez de aceitar material que não tem onde ficar. A política recusa-o primeiro, onde ele realmente está: num ficheiro que o espaço de trabalho mantém sob controlo de versões. Essa é a questão de governação, e é um assunto distinto daquilo que qualquer Recipe teria renderizado.
É também por isso que as duas Features são equivalentes, e não alternativas de igual valor em todos os destinos. Associe-se a Feature fornecida pelo autor onde realmente se detém a credencial, e a gerida pelo motor onde o destino é dono dela. A release escrita pelo autor deste exemplo é o desajuste que uma regra interna consegue detetar mecanicamente.
De onde vem o plugin
Cada entidade que este espaço de trabalho consome vem do catálogo publicado da biblioteca standard: o Component, as duas Features, a Recipe, as duas FeatureRecipes e a entidade Plugin de governação — lidas do registo 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 ambas as metades fazem parte da forma. A versão é aquela com que o plugin é publicado — o hub publica-a como oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. A versão participa na resolução: um anexo que nomeia uma versão que nenhum diretório de catálogo, nenhum registo nem o próprio binário aggrega contém interrompe a compilação. O binário contém a entidade do motor apenas na versão da sua própria release.
Compilado com --catalog a nomear um checkout do catálogo, o exemplo não precisa de mais nada: com o binário aggrega da versão que o anexo nomeia, que contém a própria entidade Plugin, cada entidade é resolvida sem rede, e o motor que é executado é o que está compilado no binário aggrega. Sem essa opção, as entidades são lidas de hub.aggrega.ai.
O motor Rego está compilado no binário da CLI, e a sua versão é a versão do compilador que o distribui. Um compilador de outra versão lê a partir do hub a entidade Plugin que o anexo nomeia e executa o motor nele compilado: a versão no anexo identifica a entidade e não escolhe o motor.
Ficheiros
aggregate-authored.yaml— a ranhuraroot_passwordassociada porcore/secret-valueno Aggregate, escrevendo a chave de entrega e o material.aggregate-delegated.yaml— a mesma base de dados sem anexo: o programador não associa nada.manifest.yaml— associa o tipo de componente e ambos os tipos de Feature às suas Recipes Terraform. Partilhado pelas duas releases.release-negative-authored.yaml,release-delegated.yaml— um por ramo, cada um com o seu própriodirectory:de fronteira. Não existe nenhuma flag para a localização da saída, pelo que duas releases que partilhassem um diretório fariam a segunda sobrescrever a primeira.release-delegated.yamltambém associa a ranhura, na sua entrada paradb, comcore/generated-secret, sem escrever nada. Qual Feature preenche a ranhura, e em que 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 controlo, baseado na resposta do anexo inteiro. Não anexado por predefinição..aggrega-config.yaml— o registo predefinido e o anexo de governação.
Gerar o exemplo
É possível compilar este exemplo com os comandos abaixo, ou pedir ao assistente de IA que o compile.
Escreva o exemplo numa nova pasta com o nome dele:
aggrega scaffold --example policy-payload-leaf-sensitivityDepois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:
cd policy-payload-leaf-sensitivityCompilação
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-lhe este prompt.
Use apenas as ferramentas do Aggrega e não crie nenhuma pasta por iniciativa 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`: esta escreve o exemplo numa 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: deve ser recusada, por isso leia-me a recusa. Depois, chame a ferramenta `build` da mesma forma com `release` definido como `release-delegated.yaml`. Indique-me que ficheiros essa segunda compilação escreveu; encontram-se em `policy-payload-leaf-sensitivity/dist/`.