跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

以作者所写的那一个叶子为键的策略

本示例讲解一条内部规则,以及使其得以表达的事实:

凭据槽位可以被填充。但不得通过把凭据材料写入工作区自身的源文件来填充。

两个 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 来获得——绝不是由策略悄悄替换。

构建两者

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

policy-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 助手替你构建。

将示例写入一个以其命名的新文件夹:

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

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd policy-payload-leaf-sensitivity

构建

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1
aggrega 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/` 下。