Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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:

Featurea quem pertence o materialo que uma vinculação escreve
core/secret-valueum autor o forneceduas folhas de values — veja abaixo
core/generated-secreto mecanismo de destino o provisiona e o rotacionanada; 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-clear

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

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

A 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 de origin na 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.rego

Um 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

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

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

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

Nã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 slot root_password associado por core/secret-value no 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óprio directory: 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.yaml também associa o slot, na sua entrada para db, com core/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:

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

Em seguida ele imprime os próximos comandos a executar. O primeiro entra na pasta nova:

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

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