Una política basada en la única hoja que escribió el autor
Este ejemplo enseña una regla interna y el hecho que la hace expresable:
Una ranura de credenciales puede llenarse. No puede llenarse escribiendo el material en el propio código fuente del espacio de trabajo.
Dos releases, a una variable de distancia: la misma base de datos gestionada, la misma ranura de credenciales obligatoria, llenada por dos Features distintas — una que el desarrollador vincula en el Aggregate, la otra que el operador vincula en la Release. Una política escrita por el operador rechaza una y permite la otra. Lo que hace que valga la pena ejecutar el par es que ambas vinculaciones manejan material secreto — así que la regla no puede escribirse a partir de la pregunta «¿es sensible esta vinculación?», y la política de control de más abajo muestra lo que ocurre cuando lo intentas.
Todo salvo dos archivos de política procede del catálogo de la biblioteca estándar, incluida la entidad Plugin de gobernanza.
La ranura, y las dos Features que pueden llenarla
core/datastore/mariadb declara una ranura de credenciales obligatoria:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true es ahí una afirmación sobre el punto de enlace y no sobre un llenado concreto: lo que sea que enlace esta ranura maneja material secreto. inject: [] cierra la entrega — la Recipe decide adónde va la credencial, y el desarrollador no lo dicta.
Dos Features de la biblioteca estándar enlazan esa ranura, y modelan ciclos de vida de credenciales opuestos:
| Feature | a quién pertenece el material | qué escribe una vinculación |
|---|---|---|
core/secret-value | un autor lo proporciona | dos hojas de values — consulta más abajo |
core/generated-secret | el motor de destino lo aprovisiona y lo rota | nada; no declara values |
core/secret-value declara sus dos hojas de forma asimétrica, y la asimetría es todo el eje de este ejemplo:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin lleva el material y está declarada como sensible. key es un nombre de entrega y se deja deliberadamente sin marcar — una clave nombra dónde vive el material en lugar de ser el material, y cada Recipe que implementa esta Feature la renderiza en claro.
core/generated-secret no declara values en absoluto, así que no hay nada que una vinculación pueda escribir. Es el homólogo gestionado por el motor y no una versión más débil de lo mismo: lleva la misma etiqueta de familia de credenciales, enlaza la misma ranura, y sus Recipes no renderizan nada, porque la credencial pertenece al motor que gestiona la propia Recipe del componente.
Las dos releases
aggregate-authored.yaml enlaza la ranura de la forma proporcionada por el autor: el desarrollador vincula la credencial en el Aggregate, y la vinculación escribe ambas hojas:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearLa rama delegada la enlaza de la forma gestionada por el motor, y ese enlace corresponde al operador: que el motor sea dueño de la credencial se deriva de la Recipe que elige el Manifest, así que release-delegated.yaml vincula core/generated-secret en su entrada para db, y aggregate-delegated.yaml es el Aggregate escrito sin su bloque features::
components: db: features: root_password: type: core/generated-secretAmbas releases comparten manifest.yaml, que enlaza los tres tipos para el destino Terraform, así que no es en el Manifest donde difieren:
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.0La política
policy.rego, vinculada sobre el grafo de compilación:
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 enumera las hojas que lleva la carga útil de esta vinculación y cuya ruta la Feature vinculada declara sensible, cada una como una ruta con puntos prefijada por el pilar. La carga útil leída es la que la vinculación acaba llevando, así que una hoja que está en un valor que el esquema de la Feature declara como default se nombra igual que una en la que escribió un autor. Dos consecuencias, y el ejemplo gira en torno a ambas:
- Una hoja aparece solo donde una declaración la cubre — la declaración nombra esa hoja, o nombra un objeto que la contiene, con una coincidencia segmento a segmento sobre la ruta con puntos. No se lee nada del propio texto de la ruta y no se inspecciona ningún valor. Así que
key, escrita junto aoriginen la misma vinculación, nunca aparece: su Feature no declara nada sobre ella. - Una vinculación cuya carga útil no lleva nada en una hoja declarada no aporta nada a la lista. La vinculación de la release delegada lleva la respuesta de toda la vinculación y ninguna lista por hoja, porque la clave se omite en la transmisión cuando estaría vacía.
La vinculación está en .aggrega-config.yaml en el rol ir-verdict, que es el rol que recibe el grafo de compilación:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoUn rol de veredicto devuelve una aceptación o un rechazo y nada más. Puede detener esta compilación; no puede reescribir el Aggregate para que cumpla, porque el código que despacha un veredicto no tiene forma de aplicar uno como cambio. Una Release que quiere la forma delegada la obtiene vinculando la Feature delegada — nunca mediante una política que la sustituya discretamente.
Compilar ambas
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull rellena el archivo de bloqueo durante la compilación; aggrega pull --release release-<arm>.yaml ejecutado una vez de antemano hace lo mismo y permite que las compilaciones posteriores se ejecuten sin ningún flag. La salida renderizada y los archivos de bloqueo se generan, no se distribuyen: este ejemplo hace commit de sus entradas y regenera todo lo demás.
Lo que se obtiene
La release escrita por el autor se rechaza, y la compilación sale con 1. E0005 es el diagnóstico que lleva el rechazo de una política — consulta la referencia 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 violationLee la ruta de la hoja. La carga útil de la vinculación lleva dos valores; el rechazo nombra values.origin y no menciona values.key. Esa única frase es el marcado por hoja haciendo su trabajo — una vinculación, dos hojas de carga útil, una declaración, un rechazo.
El rechazo también llega antes de que se renderice nada. No se crea en absoluto ningún directorio dist/infra-authored/, así que no hay ningún árbol de artefactos parcial que limpiar ni nada en disco que un paso posterior pudiera confundir con salida.
La release delegada se compila, sale con 0 y escribe dos archivos. dist/infra-delegated/terraform/aggrega.modules.tf, la configuración raíz del límite:
# 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"}y dist/infra-delegated/terraform/modules/db/main.tf, que se abre con un bloque de comentarios # que identifica la compilación y luego lleva la restricción del proveedor de AWS, el recurso y la salida de dirección que publica la Recipe:
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 es la forma delegada que llega a la salida: el motor guarda la credencial, y la Release no nombra material en ninguna parte. La release permitida renderizó un artefacto real en lugar de pasar sin renderizar nada.
La política de control: plantear en su lugar la pregunta sobre toda la vinculación
Cambia la fuente vinculada en .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego es el mismo recorrido basado en attachment.sensitive — un único booleano para toda la vinculación — en lugar de en la lista por hoja:
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])}Vuelve a compilar ambas releases — y restaura policy.rego después, ya que el resto de esta página lo da por supuesto. Ahora se rechazan ambas, con la misma 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 violationNo es que la regla falle — es la regla a la que se le hace una pregunta más burda y que la responde correctamente. sensitive lee lo que declaran las entidades: aquí es verdadero porque la ranura declara que lo que sea que la enlace maneja material secreto, y la ranura lo dice sea quien sea quien la llene. La vinculación delegada no escribe nada y aun así es sensible, así que una regla basada en esa respuesta no puede distinguir en absoluto las dos releases. La release delegada es una compilación que la regla por hoja permite y que la regla de toda la vinculación no tiene forma de permitir.
El tercer hecho de sensibilidad, sensitive_inject, tampoco ayuda: nombra las claves de entrega cuya clave provides referenciada está declarada como sensible. Aquí la ranura está cerrada a la entrega y la Feature proporcionada por el autor no publica ningún pilar provides, así que en este espacio de trabajo no nombra nada. De los tres hechos, solo la lista por hoja responde a «dónde lleva datos la carga útil de esta vinculación», que es de lo que trata la regla interna.
Para los tres hechos uno al lado del otro, con las estructuras de la carga útil y los casos en que cada uno es la pregunta correcta, consulta los hechos de vinculación que lee una política de gobernanza. Para el socket en sí — los roles, las severidades del veredicto, el canal de entrada del operador — consulta el socket de políticas, y para el lugar que ocupa la política en el producto, Gobernanza y cumplimiento.
Lo que este destino hace visible sobre la forma escrita por el autor
La Recipe de la base de datos gestionada establece incondicionalmente la directiva de contraseña gestionada propia del motor y no lee ninguna credencial inyectada, así que en este destino detiene la compilación en la propia vinculación escrita por el autor, nombrando la ranura, en lugar de aceptar material que no tiene dónde ir. La política la rechaza antes, donde realmente está: en un archivo que el espacio de trabajo mantiene bajo control de versiones. Esa es la cuestión de gobernanza, y es un asunto distinto de lo que cualquier Recipe habría renderizado.
Por eso mismo las dos Features son homólogas y no alternativas de igual rango en cada destino. Enlaza la Feature proporcionada por el autor donde de verdad posees la credencial, y la gestionada por el motor donde el destino es su dueño. La release escrita por el autor de este ejemplo es el desajuste que una regla interna puede detectar mecánicamente.
De dónde procede el plugin
Cada entidad que consume este espacio de trabajo procede del catálogo publicado de la biblioteca estándar: el Component, las dos Features, la Recipe, las dos FeatureRecipes y la entidad Plugin de gobernanza — leídas desde el registro del hub que nombra .aggrega-config.yaml, o desde un checkout del catálogo (dónde obtener uno) nombrado con --catalog.
uri: governance/rego:0.9.0 nombra esa entidad Plugin. Es una identidad: una coordenada <pluginType>/<name> más una versión, y ambas mitades forman parte de la forma. La versión es aquella con la que se publica el plugin — el hub la publica como oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. La versión interviene en la resolución: una vinculación que nombra una versión que no lleva ningún directorio de catálogo, ningún registro ni el propio binario aggrega detiene la compilación. El binario lleva la entidad del motor solo en la versión de su propia release.
Compilado con --catalog nombrando un checkout del catálogo, el ejemplo no necesita nada más: con el binario aggrega de la versión que nombra la vinculación, que lleva la propia entidad Plugin, cada entidad se resuelve sin red, y el motor que se ejecuta es el compilado en el binario aggrega. Sin esa opción, las entidades se leen desde hub.aggrega.ai.
El motor Rego está compilado en el binario de la CLI, y su versión es la versión del compilador que lo distribuye. Un compilador de otra versión lee del hub la entidad Plugin que nombra la vinculación y ejecuta el motor compilado en él: la versión de la vinculación identifica la entidad y no elige el motor.
Archivos
aggregate-authored.yaml— la ranuraroot_passwordenlazada porcore/secret-valueen el Aggregate, que escribe la clave de entrega y el material.aggregate-delegated.yaml— la misma base de datos sin vinculación: el desarrollador no enlaza nada.manifest.yaml— enlaza el tipo de componente y ambos tipos de Feature con sus Recipes de Terraform. Compartido por ambas releases.release-negative-authored.yaml,release-delegated.yaml— uno por rama, cada uno con su propiodirectory:de límite. No hay ningún flag para la ubicación de la salida, así que, si dos releases compartieran un directorio, la segunda sobrescribiría la primera.release-delegated.yamltambién enlaza la ranura, en su entrada paradb, concore/generated-secret, sin escribir nada. Qué Feature llena la ranura, y en qué documento, es la única diferencia entre las dos ramas.policy.rego— la regla interna, basada en el marcado por hoja.policy-attachment-wide.rego— el control, basado en la respuesta de toda la vinculación. No vinculado de forma predeterminada..aggrega-config.yaml— el registro predeterminado y la vinculación de gobernanza.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example policy-payload-leaf-sensitivityDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd policy-payload-leaf-sensitivityCompilación
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsCon un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta Workspace aún no contiene una carpeta `policy-payload-leaf-sensitivity`, llama una vez a la herramienta `scaffold` con `example` establecido en `policy-payload-leaf-sensitivity` y sin `dir`: escribe el ejemplo en una nueva carpeta `policy-payload-leaf-sensitivity`. Luego llama a la herramienta `build` con `workspace_root` establecido en `policy-payload-leaf-sensitivity`, `release` establecido en `release-negative-authored.yaml`, `auto_pull` establecido en true y `write` establecido en true: debe ser rechazada, así que léeme el rechazo. Luego llama a la herramienta `build` de la misma manera con `release` establecido en `release-delegated.yaml`. Dime qué archivos escribió esa segunda compilación; están en `policy-payload-leaf-sensitivity/dist/`.