治理策略读取的挂载事实
挂载在 ir-verdict 角色上的治理插件会接收整个构建图,构建中的每个 Feature 挂载都随之一起到达。每个挂载都携带一组关于自身的固定事实:它指定哪个 Feature,它填充哪个槽位,它写在哪个连接上(如果写在某个连接上的话),哪个 FeatureRecipe 实现它,目录作者对它声明了什么,作者向其中写入了什么,以及它是否处理了有人声明为敏感的内容。有一项内容不会按原样到达:作者声明为敏感的值会以隐藏状态到达——参见声明为敏感的值以隐藏状态到达。
本页列举这些事实,并说明每项事实声明了什么、不声明什么。
关于套接口本身——四种角色、裁决严重级别、
运维人员输入通道,以及随编译器一起提供的两种
策略引擎——参见 policy-socket.md。关于逐字段列出
类型和必填性的表格,参见生成的
图 schema 参考;本页讲解如何解读
这些事实,而那一页是契约。
附件在载荷中的位置
附件挂在构建图的 feature_values_mapping 下,先按节点 id、再按作者为每个附件指定的实例名作为键:
input.graph.spec.feature_values_mapping[<node id>][<attachment name>]附件名承载实际作用,而非装饰。它是作者填充槽位所用的键,因此也是编译器与宿主 Component 所声明的槽位进行配对的依据。
写在某个组件的连接上的附件——位于 Aggregate 或 Release 中某个 uses 条目的 features: 下——属于消费方组件的附件,因此它位于同一个桶中,处于消费方组件的节点上。它的键是编译器为其指定的名称,即连接的别名与槽位以点号连接:对于写在别名 gpt 下的连接的 credential 槽位,键为 gpt.credential。点号从不出现在作者编写的名称中,因此该键永远不会与节点自身某个附件的名称相同。不过,策略并不从键中读取连接:条目将其作为数据携带,即下文的 connection。
package security
import rego.v1
deny contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some name, attachment in attachments attachment.binding == "free" msg := sprintf("%v carries attachment %v, which fills no declared slot.", [node_id, name])}只有 ir-verdict 能看到这些事实。 render-verdict 策略接收渲染后的产物,不接收图;label-transform 策略接收节点标签和值的投影(其中声明为敏感的值与此处一样被隐藏),其中完全不携带附件;annotation-transform 策略接收它可以添加注解的组件。读取附件事实的规则应放在 ir-verdict,将其移到其他角色会得到一条永不触发的规则,而不是报错,因为不存在的路径只是未定义。
同一个桶,容纳所有挂载类别
一个节点上的每个挂载都位于同一个桶中,无论其 Feature 产出什么——运维类 Feature、凭据类 Feature 还是身份类 Feature。 没有哪个类别会得到比其他类别更窄的投影,因此遍历该桶的策略能看到所有挂载, 且在读取某项事实之前,无需先知道自己面对的是哪个类别。
标识:type 与 resolved_version
type 是该附件所指向的目录 Feature 的 URI。
resolved_version 是本次构建中版本解析最终确定的确切版本。
两者始终存在。
原样携带的目录元数据:labels 和 catalog_annotations
labels 是所附加 Feature 实体自身的 metadata.labels。
catalog_annotations 是该实体自身的 metadata.annotations。两者都
按目录实体声明它们的顺序携带,且都不会被过滤、
规范化或去除前缀——目录作者自己命名空间中的键
会按原样到达,编译器不读取其中任何一项。
正是这种原样携带,使策略可以以编译器 根本无从知晓其存在的标签为键。目录作者若用自己发明的标签 标记凭据类 Features,便可以直接针对该标签编写规则。
当 Feature 未声明任何标签或注解时,以及当其 type 解析不到任何目录实体时,两者都不会出现在该挂载中。
catalog_annotations 描述的是附加项所指名的实体。它与
下文的 annotation_key 和 annotation_source 回答的是不同的问题,后两者
描述的是附加项是如何产生的。写在
features: 块中的附加项携带目录注解,但不携带
另外两项。
附件填充哪个槽位:binding
binding 有三种取值,第三种并不是第二种的变体:
| 值 | 含义 |
|---|---|
| 一个槽位名 | 该附件填充具有该名称的已声明附件槽位。 |
free | 该附件不填充任何已声明的槽位。这是一个肯定的结论:槽位集合已被解析,且没有任何已声明的槽位具有此名称。 |
| 缺失 | 宿主 Component 声明的槽位集合无法解析,因此填充的是哪个槽位未知。 |
名称来自哪个已声明的槽位集合,取决于附件写在何处。节点自身块中的附件填充宿主 Component 在其自身 featuresSchema 中声明的槽位。写在连接上的附件——即带有下文 connection 的附件——填充该连接的 socket 所声明的槽位,该槽位位于宿主 Component 上该 socket 的 featuresSchema 中。因此,同一个值 credential 在一个附件上指的是 Component 的槽位,在另一个附件上指的是 socket 的槽位,而区分二者的正是 connection。
配对按名称进行——当 Feature 以槽位名称挂载在组件的块上或连接上时,附件即填充该槽位——因此该值是已声明槽位集合中的一个确切键。不会从附件的键中读取任何内容:一个连接的附件键为 gpt.credential,报告的是 credential。之所以携带槽位名称而不是一个简单的标志,是因为填充的是哪个槽位才是答案中更有用的那一半。
写在连接上的附件永远不会报告 free。socket 的槽位是经由它的连接唯一可以携带的名称,携带任何其他名称的连接会在构建加载时被拒绝,因此在到达策略的图中,每个这样的附件都填充一个已声明的槽位。
将缺失的 binding 视为 free 的策略会把未知情况报告为结论。请显式检测 free。
附件写在哪个连接上:connection
写在节点某个连接上的每个附件都带有 connection,节点自身块中的每个附件则没有。它包含两个字段,即该连接在节点上的坐标:
| 字段 | 含义 |
|---|---|
socket | 连接所经由的 socket。 |
alias | 连接所使用的别名。 |
这一对字段指明图中的一条边:其 source 是携带该附件的节点,且其 socket 和 alias 即为这两个值。该边的 target 就是附件所呈现给的组件。因此,策略可以把附件与它所到达的对象关联起来——这是仅凭附件自身的任何事实都无法说明的,因为附件位于消费方节点上:
package security
import rego.v1
deny contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some name, attachment in attachments attachment.labels["feature.aggrega.ai/kind"] == "secret" some edge in input.graph.spec.edges edge.source == node_id edge.socket == attachment.connection.socket edge.alias == attachment.connection.alias input.graph.spec.nodes[edge.target].labels["example.com/trust-zone"] == "external" msg := sprintf("%v presents the credential %v to %v, outside the trust zone.", [node_id, name, edge.target])}connection 声明了什么,又没有声明什么:
- 它记录作者在何处编写了该附件。 它根据附件所写的连接填充,从不从附件的键中解析,因此它既包含别名,也包含 socket——而键中并不包含 socket。
- 它不包含槽位。 附件填充 socket 的哪个槽位由
binding给出,读取方式与任何附件相同;槽位只在那里报告一次。 - 它不描述目标。 目标、目标的标签,以及由谁连接了这条边——开发者、Release 还是某个 Feature——都是边和目标节点的事实,在关联之后到那里读取。
- Feature 绘制的连接不携带附件,因此没有任何附件会带有指向此类边的
connection。Feature 自身连接所需的凭据是一个填充该 Feature 所声明槽位的附件,它不带有connection。 - 缺失表示节点自身的块。 没有
connection的附件写在组件自身的features:中(或者从更广的作用域、或通过注解驱动的展开到达该处)。这并不表示该附件未呈现给任何其他组件:组件自身的凭据到达何处,取决于其交付的连接方式,而该字段并不描述这一点。
除了决定 binding 以及 sensitive 的槽位部分从哪个已声明槽位集合中读取之外,connection 不会改变附件的任何方面:它的 FeatureRecipe、它的 provides 契约、它的其余事实以及它在桶中的位置,都与节点所携带的任何附件相同。
哪个 FeatureRecipe 实现该挂载:realization
realization 以 <name>:<version> 的形式,指明该 Release 的 Manifest 绑定到该挂载的 FeatureRecipe。若 Manifest 的 name 层映射了该挂载自身的名称,Manifest 就按该名称绑定——对于写在连接上的挂载,即其限定名称,如上文的 gpt.credential——否则按挂载所指定的 Feature 类型绑定。所指明的 FeatureRecipe,就是对同一组文档进行构建时用来渲染该挂载的那一个:图在任何渲染之前就记录了绑定,而渲染也以同样的方式绑定该挂载。
package security
import rego.v1
approved_realizations := {"approved-credential:1.0.0"}
deny contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some name, attachment in attachments attachment.labels["feature.aggrega.ai/kind"] == "secret" realization := attachment.realization not realization in approved_realizations msg := sprintf("%v realizes the credential %v with %v, which is not an approved FeatureRecipe.", [node_id, name, realization])}realization 声明了什么,又没有声明什么:
- 它在出现的每一处都是同一对值。
aggrega inspect将其打印为该挂载的 realization;而在目标会在其渲染结果上标记来源的情况下,该 FeatureRecipe 渲染出的文档会将其作为aggrega.ai/recipe-uri的值携带,因此策略无需在不同形式之间转换,即可将挂载与其渲染结果关联起来。 - 它按名称和版本指明 FeatureRecipe,而不是按能力。 两个能力可能各自以相同的名称和版本发布一个 FeatureRecipe。 绑定其中哪一个由 Manifest 的映射决定,凡是仅凭名称会产生歧义之处,该映射都会指明能力;本字段不会重复说明这一点。
- Release 边界自身的挂载同样携带它,位于
boundary_features之下,读取方式相同。边界级挂载还会到达该边界所包含的每个组件,并在那里携带相同的 realization。 - 缺失表示未绑定到任何对象。 若 Manifest 未将某个挂载绑定到目录中的任何
FeatureRecipe,该挂载就不携带
realization。对这样的组合进行构建,会在渲染前中止,并指明未映射的挂载——但处于此角色的策略在该中止之前就会被调用,因此它可能遇到不携带该字段的挂载。上面的规则会跳过这样的挂载,因为其规则体首先绑定realization;想要报告这种情况的规则需要显式检测该键是否缺失。
附加项的产生方式:origin 及其两个伴随字段
origin 区分开发者手写的附加项与由注解驱动的展开所生成的附加项:
| 值 | 含义 |
|---|---|
explicit | 在 features: 块中编写。 |
annotation | 由注解驱动的展开生成。 |
mixed | 该附加项的 value 或 infra 叶子混合了两者;逐叶子的详细信息见 provenance 映射。 |
annotation_key 指明触发合成附加项的注解,annotation_source 以 <release-file-path>:<dotted-yaml-key-path> 的形式定位其声明。当 origin 为 explicit 时,两者均不存在。
编写的载荷:values、infra 和 inject
values 是该附件的运行配置,属于开发者的领域。infra 是其按实例划分的物理规格,属于运维人员的领域。inject
是与内容无关的注入路由,将交付键映射到它们所取值的 provides 键,首先按交付机制分组。
凭据附件的 values 承载什么由作者决定,编译器按所写内容原样承载,不解析其中任何一种:按引用的凭据承载指向密钥存储的指针,按值的凭据承载凭据材料本身。无论哪种,所附加的 Feature 声明为敏感的叶子在到达策略时都会被隐去,如下一节所述;未声明的叶子(例如公开的定位符)则按原样到达。
声明为敏感的值以隐去形式到达
图中标记为已声明敏感的每个叶子,到达此套接字时都是一个隐去标记,而不是作者所写的值。该标记是一个单键对象,携带该值缺失的原因:
{ "aggrega_withheld": "declared" }declared 表示有一项声明覆盖了该叶子。完全无法读取的载荷会被整体隐去,原因为 unreadable,因为其中没有任何叶子可以被判定。
隐去遵循图自身的标记,因此它恰好作用于这些标记所指定的叶子,无论它们位于何处:
- 每个附件的
values和infra,无论由哪个作用域写入——组件自身的块、子系统、边界或 Release、由注解驱动的展开——也无论写在节点自身的块上还是写在其某个连接上,按其sensitive_payload_leaves所指定的叶子隐去; - 边界级附件的
infra,位于boundary_features下,按其 自身的标记隐去; - 节点自身的
values和infra,位于values_mapping和infra_mapping下,按节点自身的sensitive_payload_leaves隐去; - 连接自身的
values和infra,位于边上以及消费方节点的uses条目中,按边的sensitive_payload_leaves隐去,该字段列出消费方组件的套接字声明为敏感的叶子。
策略据以推理的内容保持完整。类型、解析后的版本、标签、目录注解、binding、connection、realization、origin 及其来源映射、全部三项敏感性事实,以及没有任何声明标记的每个叶子,都按原样到达。被隐去叶子的键也会保留,因此策略仍能看到载荷携带哪些叶子,以及其中哪些携带已声明的内容——只是值缺失。因此,关于已声明敏感内容流向何处、经由哪条路径的规则可以完整表达;而关于内容本身的规则则无法表达,这是有意的设计。
节点编写的 uses 块与其边一同携带在节点上,它只为写在连接上的每个附件保留其 type 和 description。附件的值只携带一次,即携带在附件本身上,隐去作用于此处。
想要区分被隐去的叶子与编写的叶子的策略,可以检测该标记的键:
package security
import rego.v1
audit contains msg if { some node_id, attachments in input.graph.spec.feature_values_mapping some name, attachment in attachments some key, value in attachment.values is_object(value) value.aggrega_withheld msg := sprintf("%v/%v writes a declared-sensitive value at values.%v.", [node_id, name, key])}这与命令打印图时 --ir-graph 所应用的隐去、以及守护进程的 aggrega/irGraph 应答客户端时所应用的隐去相同,因此策略和阅读图的人看到的是同样被隐去的叶子。这些界面会在有人使用 --unredacted 请求时向其返回这些值;策略收到的载荷没有这样的请求,节点自身已声明的值也会按照与附件相同的条件对其隐去。它只作用于策略收到的载荷,不作用于其他任何内容:构建据以渲染的图不受影响,因此隐去不会改变任何渲染出的字节。render-verdict 策略收到的内容不会隐去任何东西,因为该角色所评判的正是渲染出的产物。
每个叶子的来源:values_provenance 和 infra_provenance
二者都以叶子在其所属支柱内的点分路径为键,每个条目记录该叶子的 origin——同样是 explicit / annotation 的区分,只是逐个叶子应用。由注解贡献的叶子还额外携带声明它的编写表面、贡献它的注解键,以及该声明的源位置。当显式叶子覆盖了由注解贡献的叶子时,条目还会携带被它替换的、遭到抑制的贡献,这样策略不仅能看到最终胜出的值,还能看到被覆盖的内容。
三个敏感性单位
载荷携带三个敏感性事实,它们位于三个不同的单位:整个附件、单个投递键、单个载荷叶子。
每个事实都由其自身的输入计算得出。没有一个是从另一个派生的,尤其是针对整个附件的答案从不会向下扩散到更窄的单位。将其中任意两个混为一谈,会产生一个以静默方式出错的策略,因此在针对其中任何一个编写规则之前,值得分别理解这三者。
它们全部派生自作者声明的内容——Feature 的 schema 叶子上的 sensitive: true,或 Component 为其自身附件或其某个插槽声明的附件槽位上的 sensitive: true。不会检查任何值的内容,也不会从字段名称中读取任何含义。
sensitive——针对整个附件的一个答案
当所附加的 Feature 在其 values、infra 或 provides 中声明了敏感叶子,或者附件所填充的槽位声明了绑定到它的任何内容都会处理机密材料时,该值为 true。这里的槽位是指宿主 Component 的同名附件槽位,或者对于携带 connection 的附件,是该连接的插槽所声明的同名槽位。两种声明都不存在时,该值不设置。
它回答的是该实体是什么,因此有意不随某位作者具体写了什么而变化。它读取的是 Feature 的声明,而不是该附件恰好填充的那部分敏感叶子,因为一个在某个 Release 中敏感、在另一个 Release 中不敏感的字段,对于针对目录实体进行推理的策略来说将无法使用。
这两部分相互独立,各自单独成立。一个完全没有声明敏感叶子的 Feature,绑定到敏感槽位时仍然是敏感附件,因为槽位如此声明。一个声明了敏感叶子的填充是敏感附件,即使槽位没有作出这样的声明,甚至即使它是一个不绑定任何槽位的自由附件。
sensitive_inject——每个投递键一个答案
inject 中其所引用的 provides 键被所附加的 Feature 声明为敏感的那个子集,以 inject 自身的形状携带:先是机制,然后是投递键,值为所引用的 provides 键。
从 Feature 标记为敏感的 provides 键填充的投递键会出现在这里;从未标记的键填充的投递键则不会,即使在同一个附件、同一种机制上也是如此。当附件未声明任何投递机制,或未引用任何敏感的 provides 键时,该字段不存在。
sensitive_payload_leaves——每个载荷叶子一个答案
该附件的载荷所携带的、其路径被所附加的 Feature 声明为敏感的叶子,每个都以该数据所在的、带支柱前缀的点分路径表示:values.<path> 或 infra.<path>。
这里读取的载荷是附件最终携带的载荷,而不是作者编写的块。一个处于 Feature 的 schema 声明为 default 的值上的叶子,与作者写在该处的叶子一同列出:被填充的默认值是载荷携带的数据,而仅从编写的块中读取的标记会使其无法被列出。
当 Feature 的 schema 声明为敏感的某个路径覆盖某个叶子时,该叶子就会出现——即该声明指名了这个叶子,或指名了包含它的对象。匹配按点分路径的段逐段进行,因此 db 上的声明覆盖 db.password,而不会涉及名为 dbPassword 的兄弟叶子。不会从路径本身的文本中读取任何内容,也不会检查任何值——作者在被标记的叶子上写的是材料本身还是指向它的指针,在这里无从得知,也不是该标记所声称的内容。
比较针对展平为叶子的载荷进行,而不是针对支柱的顶层键,因此嵌套映射中更深层的叶子与其他叶子一样参与比较。
叶子按载荷保存它们的顺序到达,values 支柱的叶子在 infra 支柱的叶子之前——与载荷本身携带的顺序相同,正是这一点使得相同输入的多次运行在传输上保持字节一致。
这个单位回答的是该附件把数据放在了哪里,这必然随 Release 而变化。这就是为什么它与作者编写的内容取交集,而 sensitive 不这样做:两者回答的是不同的问题,把任一规则应用到另一个字段上都会使其失效。
综合理解这三者
一位作者附加了一个凭据 Feature,该 Feature 将其 literalPassword values 叶子和 password provides 键声明为敏感,填充一个已声明的 credentials 槽位,并内联编写了一个字面密码:
{ "type": "example/db-credential", "resolved_version": "1.0.0", "binding": "credentials", "values": { "secretName": "db-creds", "literalPassword": { "aggrega_withheld": "declared" } }, "inject": { "env": { "DATABASE_PASSWORD": "password" } }, "sensitive": true, "sensitive_inject": { "env": { "DATABASE_PASSWORD": "password" } }, "sensitive_payload_leaves": ["values.literalPassword"]}三个不同的问题,三个不同的答案。该附件确实处理已声明为敏感的材料(sensitive)。DATABASE_PASSWORD 环境键是携带该材料的键(sensitive_inject)。而该附件的载荷具体在 values.literalPassword 处携带了一个值(sensitive_payload_leaves)——而 values.secretName 作为 Feature 有意不加标记的定位符,即使载荷同样携带它,也不在该列表中。作者写的密码以被扣留的形式到达,而旁边的定位符按原样到达:标记告诉策略那里有一个值,而值本身从不会到达策略。
拒绝渲染产物中出现字面机密的规则需要第三个。要求每个处理凭据的附件都携带所有权标签的规则需要第一个。用一个替代另一个,会改变哪些构建被中止。
缺失不等于许可
只有在某个声明覆盖某个叶子时,该叶子才会被列出。因此缺失的 sensitive_payload_leaves 表示该附件没有列出其 Feature 声明为敏感的任何叶子——绝不表示载荷不敏感。 它也不区分没有此类叶子可列出的附件与根本不报告这一维度的生产者:这两者仍无法区分,读取缺失键的一方只能得知这一点,别无其他。
如果一个 guest 将缺失的叶子列表理解为可以明文显示或输出某个值的许可,那它就把标记的含义读反了。
当该键为空时,它会从传输中完全省略,因此一个其 Feature 和槽位都没有任何声明的附件,携带的字节与该标记不存在时完全相同。正是这种省略让误读变得容易,也正因如此,值得明确说明其方向。
最清楚的情况是一个敏感但完全没有列出任何叶子的附件。以上面的附件为例,改变两点——作者只编写定位符,不填充已声明为敏感的叶子,并且改用 Feature 未标记的 name provides 键而不是 password 来填充环境键:
{ "type": "example/db-credential", "resolved_version": "1.0.0", "binding": "credentials", "values": { "secretName": "db-creds" }, "inject": { "env": { "DATABASE_PASSWORD": "name" } }, "sensitive": true}sensitive 仍然为 true——Feature 的声明没有改变——而两个更窄的单位都消失了。该附件仍然处理机密材料;只是它不通过该附件携带的叶子或投递键来处理。基于汇总值的策略会拒绝此次构建,而基于逐叶子标记的策略会放行它。两者都是站得住脚的规则,策略需要哪一个,由策略作者有意作出决定。
对于 sensitive_inject,同样的不对称也反向成立:一个附件可以编写敏感叶子而不通过投递键传递任何敏感内容,也可以传递敏感的 provides 键而完全不编写任何值。
敏感性声明不做什么
标记只起注释作用,它不是一种控制。将一个叶子或一个槽位声明为敏感,不会加密任何内容,不会校验或拒绝某个值,也不会强制使用某种交付机制。构建结果不会因为存在某个声明而改变。
在大多数目标上,它也不会改变任何渲染出的字节:作者内联提供的已声明为敏感的值,与未声明的值渲染结果完全相同。Terraform 是标准库目标中的例外,因为它自带一个原生的逐值敏感性原语,可供声明落在其上——参见
providers/terraform.md “Declared-sensitive module
inputs”。没有自身敏感性概念的目标,就没有可供声明改变的东西。
这些声明在所有地方所做的,是让这一事实变得可读——对编译器自身的调试输出可读,也对此插槽上决定如何处理它的策略可读。将标记转化为构建结果是策略的职责,这正是此插槽存在的意义。而且策略会得知已声明为敏感的材料,却不会拿到它:标记会到达,值则以隐去的形式到达。
交叉引用
policy-socket.md— 治理插槽:四种角色、裁决严重级别、操作员输入通道、随编译器提供的策略引擎,以及将插件挂接到工作区。plugin-contract.md— 该插槽在流水线中的位置及其类型化的传输结构。- 图 schema 参考 — 构建图的逐字段契约,包括附件上的每个字段。
entities/component.md“Attachment Slots” — 声明槽位、将槽位声明为敏感;以及插槽为经由它连接的连接所声明的featuresSchema。entities/aggregate.md“A connection’s own attachments” — 在连接上编写附件,以及附件所取的名称。vocabulary/compact-form-authoring.md“Declaring a leaf sensitive” —sensitive:关键字,以及声明它所能达到效果的上限。vocabulary/labels-and-annotations.md— 策略读取的标签与注解。