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

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:

Featurea quem pertence o materialo que um anexo escreve
core/secret-valueum autor fornece-oduas folhas de values — ver abaixo
core/generated-secreto motor de destino aprovisiona-o e faz a sua rotaçãonada; 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-clear

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

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

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

Um 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

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

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

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

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

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

Depois, imprime os próximos comandos a executar. O primeiro entra na nova pasta:

Terminal window
cd policy-payload-leaf-sensitivity

Compilação

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