以作者所写的那一个叶子为键的策略
本示例讲解一条内部规则,以及使其得以表达的事实:
凭据槽位可以被填充。但不得通过把凭据材料写入工作区自身的源文件来填充。
两个 release,只差一个变量:同一个托管数据库,同一个必需的 凭据槽位,由两个不同的 Features 填充——一个由开发者在 Aggregate 中附加, 另一个由运维人员在 Release 中附加。一条 由运维人员编写的策略拒绝其一、允许其二。这一对示例值得运行的原因在于:两个附加都处理机密材料——因此该规则 无法针对“这个附加是否敏感?”这一问题来编写, 下文的对照策略展示了这样尝试时会发生什么。
除两个策略文件外,其余一切都来自标准库目录, 包括治理用的 Plugin 实体。
槽位,以及可以填充它的两个 Features
core/datastore/mariadb 声明了一个必需的凭据槽位:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).这里的 sensitive: true 是关于绑定点的声明,而不是关于某一次具体填充的声明:无论什么绑定这个槽位,都会处理机密材料。inject: [] 关闭了交付——凭据去往何处由 Recipe 决定,开发者不加指定。
有两个标准库 Features 绑定该槽位,它们建模的是相反的凭据生命周期:
| Feature | 谁拥有材料 | 一次附加编写了什么 |
|---|---|---|
core/secret-value | 由作者提供 | 两个 values 叶子——见下文 |
core/generated-secret | 由目标引擎预配并轮换 | 什么也没有;它不声明任何 values |
core/secret-value 以不对称的方式声明它的两个叶子,而这种不对称正是本示例的关键所在:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin 承载材料,并被声明为敏感。key 是一个交付名称,有意不加标记——key 指明的是材料存放在何处,而不是材料本身,每个实现此 Feature 的 Recipe 都以明文渲染它。
core/generated-secret 完全不声明 values,因此一次附加没有任何可编写的内容。它是由引擎管理的对等项,而不是同一事物的弱化版本:它带有相同的凭据族标签,绑定相同的槽位,而它的 Recipes 不渲染任何内容,因为凭据属于该组件自身的 Recipe 所管理的引擎。
两个 release
aggregate-authored.yaml 以作者提供的方式绑定该槽位:开发者在 Aggregate 中附加凭据,该附加编写了两个叶子:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clear委托分支以引擎管理的方式绑定该槽位,而这一绑定属于运维人员:引擎是否拥有凭据取决于 Manifest 选取的 Recipe,因此 release-delegated.yaml 在其 db 条目上附加 core/generated-secret,而 aggregate-delegated.yaml 是去掉了 features: 块的已编写 Aggregate:
components: db: features: root_password: type: core/generated-secret两个 release 共用 manifest.yaml,它为 Terraform 目标绑定了全部三种类型,因此两者的差异并不在 Manifest 中:
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策略
policy.rego,挂接在构建图之上:
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 列出该挂接的载荷所携带的、且其路径被所挂接的 Feature 声明为敏感的叶子,每个都以带支柱前缀的点分路径表示。读取的载荷是该挂接最终携带的载荷,因此位于 Feature 的 schema 声明为 default 的值处的叶子,与作者在该处写入的叶子会一并列出。这带来两个结果,而本示例正是围绕这两点展开的:
- 只有当某个声明覆盖某个叶子时,该叶子才会出现——即该声明指名了这个叶子,或指名了包含它的对象,按点分路径逐段匹配。不会从路径自身的文本中读取任何内容,也不会检查任何值。因此,在同一挂接中写在
origin旁边的key永远不会出现:它的 Feature 对它没有任何声明。 - 如果某个挂接的载荷在已声明的叶子处没有携带任何内容,它就不会向列表贡献任何内容。委托版本的挂接携带的是整个挂接的答案,完全没有逐叶子列表,因为该键在为空时会从传输数据中省略。
该挂接位于 .aggrega-config.yaml 中的 ir-verdict 角色处,这一角色负责接收构建图:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.rego裁决角色只返回接受或拒绝,别无其他。它可以终止本次构建;但不能把 Aggregate 改写为合规的形式,因为分派裁决的路径无法将裁决作为变更来应用。想要委托形式的 Release,应通过挂接委托的 Feature 来获得——绝不是由策略悄悄替换。
构建两者
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull 在构建期间填充锁文件;事先运行一次 aggrega pull --release release-<arm>.yaml 效果相同,并且之后的构建无需任何标志即可运行。渲染输出和锁文件是生成的,而不是随附提供的:
本示例只提交其输入,其余一切都会重新生成。
返回结果
作者编写的 release 被拒绝,构建以 1 退出。E0005 是策略拒绝所携带的诊断——参见
诊断参考:
[… 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阅读叶子路径。该挂载的载荷携带两个值;拒绝信息指明了 values.origin,而没有提及 values.key。这一句话正是按叶子标记在发挥作用——一个挂载,两个载荷叶子,一条声明,一次拒绝。
拒绝也发生在任何内容被渲染之前。根本不会创建 dist/infra-authored/
目录,因此没有需要清理的部分产物树,磁盘上也没有任何后续步骤可能误认为输出的内容。
委托的 release 构建成功,以 0 退出,并写出两个文件。
dist/infra-delegated/terraform/aggrega.modules.tf,即该边界的根配置:
# 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"}以及 dist/infra-delegated/terraform/modules/db/main.tf,它以一个标识本次构建的
# 注释块开头,随后包含 AWS provider 约束、资源以及该 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 是委托形式在输出中的体现:由引擎持有凭据,Release 在任何地方都不指明任何机密材料。被允许的 release 渲染出了真实的产物,而不是因为什么都没渲染才得以通过。
对照:改为询问整个挂接层面的问题
在 .aggrega-config.yaml 中替换所挂接的源文件:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego 执行相同的遍历,但以 attachment.sensitive
(整个挂接只有一个布尔值)为依据,而不是以逐叶列表为依据:
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])}重新构建两个 release,之后再把 policy.rego 放回原处,因为本页其余部分以它为前提。现在两者都被拒绝,且给出同一句话:
[… 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这并不是规则误判,而是规则被问了一个更粗粒度的问题,并正确地作出了回答。sensitive 读取的是实体的声明:它在这里为 true,是因为该槽位声明了任何绑定它的对象都会处理机密材料,而无论由谁来填充,槽位都这样声明。委托式挂接没有编写任何内容,却仍然是敏感的,因此以这个答案为依据的规则根本无法区分这两个 release。委托式 release 是一次逐叶规则允许、而整体挂接规则无从允许的构建。
第三个敏感性事实 sensitive_inject 同样无济于事:它列出的是其所引用的 provides 键被声明为敏感的交付键。这里的槽位对交付是封闭的,而由作者提供的 Feature 不发布
provides 支柱,因此在这个工作区中它什么也不列出。三个事实中,只有逐叶列表能回答“这个挂接的载荷在哪里携带数据”,而这正是内部规则所关心的。
若要并列查看这三个事实,以及各自的载荷形态和各自适用的情形,请参阅 治理策略读取的挂接事实。 关于套接口本身(角色、裁决严重级别、操作员输入通道),请参阅策略套接口;关于策略在产品中的位置,请参阅 治理与合规。
该目标让编写形式中的哪些问题变得可见
托管数据库 Recipe 无条件地设置引擎自身的托管密码指令,且不读取任何注入的凭据,因此在该目标上,它会针对编写的附件本身中止构建并指明该插槽,而不是接受无处落脚的材料。策略会先在它实际所在的位置拒绝它:位于工作区纳入版本控制的某个文件中。这才是治理关注的问题,它与任何 Recipe 本会渲染出什么是两回事。
这也是为什么这两个 Features 是并列关系,而不是在每个目标上地位相等的替代方案。在你确实持有凭据的地方绑定由作者提供的 Feature,在由目标掌管凭据的地方绑定由引擎托管的那个。本示例中编写的 release 正是内部规则可以机械地捕获的那种不匹配。
插件从哪里来
此工作区使用的每个实体都来自已发布的标准库目录:Component、两个 Features、Recipe、两个 FeatureRecipes 以及治理 Plugin 实体——它们从 .aggrega-config.yaml 指定的 hub 仓库读取,或从用 --catalog 指定的目录检出(获取方式)读取。
uri: governance/rego:0.9.0 指明该 Plugin 实体。它是一个标识:一个 <pluginType>/<name> 坐标加一个版本,两部分都属于该形式。版本即插件发布时的版本——hub 将其发布为 oci://hub.aggrega.ai/plugin/governance/rego:0.9.0。版本参与解析:若挂载指定的版本在任何目录、任何仓库中都不存在,aggrega 二进制文件本身也不带有,构建就会停止。二进制文件只带有其自身发布版本的引擎实体。
使用 --catalog 指定目录检出进行构建时,该示例不需要其他任何东西:借助挂接所指定版本的 aggrega 二进制文件(它本身带有该 Plugin 实体),每个实体都无需网络即可解析,运行的引擎就是编译在 aggrega 二进制文件中的那个。没有它时,这些实体从 hub.aggrega.ai 读取。
Rego 引擎编译在 CLI 二进制文件中,其版本就是发布它的编译器版本。其他版本的编译器会从 hub 读取挂接所指定的 Plugin 实体,并运行编译在其自身中的引擎:挂接中的版本用于标识该实体,而不是选择引擎。
文件
aggregate-authored.yaml— 在 Aggregate 中由core/secret-value绑定的root_password插槽, 由作者编写交付键和密钥材料。aggregate-delegated.yaml— 同一个数据库,但没有附加项: 开发者不绑定任何内容。manifest.yaml— 将组件类型和两种 Feature 类型绑定到各自的 Terraform Recipes。两个 release 共用。release-negative-authored.yaml、release-delegated.yaml— 每个分支一个,各自 拥有自己的边界directory:。没有用于指定输出位置的标志, 因此两个 release 若共用一个目录,第二个会覆盖第一个。release-delegated.yaml还在其db条目上用core/generated-secret绑定该插槽,不编写任何内容。由哪个 Feature 填充该插槽、 在哪个文档中填充,是两个分支之间唯一的区别。policy.rego— 内部规则,以逐叶标记为键。policy-attachment-wide.rego— 对照组,以整个附加项的 答案为键。默认不附加。.aggrega-config.yaml— 默认注册表和治理附加项。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example policy-payload-leaf-sensitivity然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd policy-payload-leaf-sensitivity构建
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # builds借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `policy-payload-leaf-sensitivity` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `policy-payload-leaf-sensitivity`,不设 `dir`:它会把示例写入新的 `policy-payload-leaf-sensitivity` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `policy-payload-leaf-sensitivity`,`release` 设为 `release-negative-authored.yaml`,`auto_pull` 设为 true,`write` 设为 true:这次构建预期会被拒绝,所以请把拒绝信息读给我听。然后以同样方式调用 `build` 工具,将 `release` 设为 `release-delegated.yaml`。告诉我第二次构建写入了哪些文件;它们位于 `policy-payload-leaf-sensitivity/dist/` 下。