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

Aggrega Plugin 信任记录 schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json

机器生成的记录,为每个返回接受或拒绝裁决的挂载项记录其所信任的插件身份——即处于 ir-verdict 或 render-verdict 角色的 plugins.governance 挂载项,以及每个 plugins.linter 挂载项。该记录位于 lockfile 旁边的 plugins-trust.yaml,并与 lockfile 一同提交,因为保存在版本控制之外的记录无人能够审查,也无从比对。它由 aggrega pull 写入:该命令在首次解析上述某个挂载项时创建该文件,并在解析每个挂载项时为其添加一条记录。一个只包含部分已配置挂载项记录的文件是合法的中间状态,而不是损坏状态。读取它的有 aggrega build、aggrega lint --release 和 aggrega validate --release,以及通过 aggrega serve 和 aggrega mcp 执行的相同操作;它们都会在上述任何挂载项运行之前,用该记录约束工作区配置。有两种不一致会被拒绝,原因各不相同:解析出的制品摘要与记录中摘要不同的插件会被拒绝而不运行,因为将要运行的插件并不是该记录当初审查的那个插件;没有任何已配置裁决挂载项对应的记录条目会使运行中止,因为移除一个关卡不会改变任何渲染字节,所以在缺少一个已审查关卡的情况下产生的输出,与经该关卡批准的输出无法区分。构建、限定 Release 范围的 lint 和限定 Release 范围的验证——无论来自命令行、通过 aggrega serve 还是通过 aggrega mcp——在加载从内容缓存读取的上述插件时,还会用其记录所携带的 signature 约束每个插件,正如构建用每个 lockfile 条目所携带的签名约束该条目一样:参见下文的 signature。相反的方向——记录中尚未包含的已配置挂载项——就是上文所述的中间状态,两种比对都不会拒绝它;而不存在的记录不含任何条目,因此不固定任何内容,两种比对也不会因它而拒绝任何东西;签名要求是缺失条目无法规避的唯一约束,如下文 signature 所述。条目只会在显式升级时离开记录:指明某个插件的 aggrega pull --upgrade 会在不再有裁决挂载项指明该插件时删除其条目,而不带参数的 aggrega pull --upgrade 会删除所有此类条目。普通的 aggrega pull 既不会重新解析条目的身份,也不会删除条目,因此因无对应条目而导致的中止,需要通过明确声明来清除,而不是由下一次运行清除。最后一个条目被删除的记录会被清空而不是删除,清空的记录是合法的:它不含任何内容,因此不固定任何内容,两种比对也不会因它而拒绝任何东西,与不存在的记录完全相同。每条记录以插件自身的身份坐标寻址,并将所选版本和制品摘要作为字段携带,因此版本变化是对现有记录某个字段的修改,而不是新地址下的新记录——正是这一点使得重新换版本的插件在文件及其 diff 中能与首次记录的插件区分开来。除该身份之外,记录还携带关于其所指明制品的两项事实,每项都仅在经过验证后才会记录:发布者附加到该制品上的弃用信息(在发现该信息且其签名验证通过时),以及 aggrega pull 在验证插件自身签名时记录的已验证签名事实——与 lockfile 条目所携带的是同一事实、同一键。每一项都是关于所记录制品的事实,而不是第二个身份,因此普通的 pull 在记录它时不会扰动该记录所约束的身份。除此之外,该文件不记录任何内容:没有针对文件本身的签名,没有规则输入,没有解析来源——没有注册表主机,没有写入它的机器上的路径——也没有时钟读数,因此同样的解析无论何时何地运行都会产生相同的字节。plugins.governance 裁决挂载项的外部规则文件以摘要形式记录在 lockfile 的 verdict_inputs 中;plugins.linter 挂载项的规则输入则不记录在任何一个文件中。构建逐字节复现的一切都固定在 lockfile 中;裁决挂载项不影响任何渲染输出,这就是其身份记录在此处而非 lockfile 中的原因。Schema 演进准则:添加新的顶层部分属于 SemVer-MINOR(增量);在现有部分内添加新字段属于 SemVer-MINOR;删除键或收紧约束属于 SemVer-MAJOR。

顶层类型: object

属性

属性类型必需描述
pluginsobject[]否每个受信任用于返回裁决的挂载的插件对应一条记录,按插件的身份坐标寻址。同时挂载在两个裁决角色上的插件——同一个治理插件同时绑定到 ir-verdict 和 render-verdict——只贡献一条记录,因为所记录的对象是插件的身份而非挂载:两个挂载读取的是同一个制品。记录按坐标升序输出。默认值:[]
versionconst 1是信任记录 schema 版本:1。schema 的 SemVer-MAJOR 变更会使其递增。常量:1

不允许其他属性。

plugins-trust.plugins[]

属性类型必需描述
deprecationobject否经过验证的追溯性弃用标记,在 digest 所指的制品上发现经过签名且受信任的标记时记录。标记是其所弃用制品的一个经过签名的 OCI referrer,在发布之后附加,无需重新发布该制品,因此已记录在此的插件可以在事后被弃用——在 retracted 严重级别(即撤回级别)下,这意味着该制品被排除在选择之外,而不仅仅是不推荐使用。它是关于本记录已寻址的制品的一个事实,而非第二个身份,正因如此 aggrega pull 可以添加它,同时不改动 resolved_version 和 digest:记录它不会采纳任何东西。仅当解析得到的摘要等于已记录的摘要时才会记录它——报告不同字节的解析是身份的变更,受本记录自身的规则约束,除非运行明确要求,否则会被拒绝。没有任何操作会清除已记录的标记;它只会随承载它的记录一起离开,即在替换或删除该记录的显式升级时。aggrega build、aggrega lint --release 和 aggrega validate --release,以及通过 aggrega serve 和 aggrega mcp 到达的相同操作,都会指出携带标记的插件,因为否则被弃用的门禁会在无任何提示的情况下被获取、缓存并运行;工作区的 build.halt_on_deprecated_severity 设置决定构建是因此中止还是仅给出提示。
pluginstring是插件的身份坐标:其插槽段与裸名称以斜杠连接,例如 governance/aggrega-security-baseline。裸名称仅在其插槽内唯一,因此插槽段用于区分位于不同插槽中的两个同名插件。坐标有意不包含版本——正因如此,版本变更会表现为对下方 resolved_version 的编辑,而不是一条无关的记录。
resolved_versionstring是写入记录时为该插件选定的具体版本(例如 1.2.3)。以单个路径段记录,因此不包含 /、\ 和 ..。模式:^([^/\\.]|\.[^/\\.])*\.?$。
digeststring是所解析插件制品的内容摘要,格式为 sha256: 后跟 64 个小写十六进制字符——即内容地址在所有进行比较之处的书写形式。模式:^sha256:[a-f0-9]{64}$。
signatureVerifiedSignature否经过验证的签名事实,在 aggrega pull 依据所解析注册表的信任策略、针对 digest 所指制品验证该插件自身的签名时记录。拉取在每次运行时都会验证它为这些挂载解析的每个插件的签名,并将结果记录在此——替换记录原有的内容,若拉取未验证到任何签名则将其移除——且不改动记录所约束的身份。在构建、release 范围的 lint 或 release 范围的验证运行插件之前,会对该事实所指的已缓存签名包重新计算哈希,若该 blob 缺失或不一致则中止运行;对于从内容缓存读取的插件,运行会从该签名包中读取签名所针对的制品,若签名针对的制品不同于所读取的插件则中止——因此从另一个插件条目复制而来的 signature 会被拒绝,无论签名要求如何规定。此处不验证任何签名,因此手动写入缓存、针对该插件自身制品生成的签名包,与拉取验证过的签名包无法区分。此外,若工作区的信任配置要求从内容缓存读取的插件具有签名——即 aggrega pull 在验证插件时应用的要求,因此允许拉取不记录签名的跳过设置和 advisory 注册表同样允许运行继续——那么记录中没有该插件的 signature,或根本没有该插件的条目,都会中止运行,并指出该插件以及要求签名的设置。从目录 catalog 或编译器二进制文件内副本读取的插件永远不受该要求约束。

不允许其他属性。

plugins-trust.plugins[].deprecation

经过验证的追溯性弃用标记,在 digest 所指的制品上发现经过签名且受信任的标记时记录。标记是其所弃用制品的一个经过签名的 OCI referrer,在发布之后附加,无需重新发布该制品,因此已记录在此的插件可以在事后被弃用——在 retracted 严重级别(即撤回级别)下,这意味着该制品被排除在选择之外,而不仅仅是不推荐使用。它是关于本记录已寻址的制品的一个事实,而非第二个身份,正因如此 aggrega pull 可以添加它,同时不改动 resolved_version 和 digest:记录它不会采纳任何东西。仅当解析得到的摘要等于已记录的摘要时才会记录它——报告不同字节的解析是身份的变更,受本记录自身的规则约束,除非运行明确要求,否则会被拒绝。没有任何操作会清除已记录的标记;它只会随承载它的记录一起离开,即在替换或删除该记录的显式升级时。aggrega build、aggrega lint --release 和 aggrega validate --release,以及通过 aggrega serve 和 aggrega mcp 到达的相同操作,都会指出携带标记的插件,因为否则被弃用的门禁会在无任何提示的情况下被获取、缓存并运行;工作区的 build.halt_on_deprecated_severity 设置决定构建是因此中止还是仅给出提示。

属性类型必需描述
messagestring是标记所携带的人类可读弃用消息——通常是迁移指引。若标记未携带单独的消息,则在此记录其原因,因此报告的语句永远不会为空。
severitystring(枚举)是标记严重级别,顺序为 warning < error < retracted。当该严重级别达到或超过所配置的中止阈值时,构建中止,否则仅给出提示——与其他所有弃用报告读取的规则和设置相同。retracted 是撤回级别:该严重级别的制品被排除在选择之外,而两个提示性严重级别仍允许选择它。允许的值:"warning"、"error"、"retracted"

不允许其他属性。

定义

VerifiedSignature

pull 在依据解析所用 registry 的信任策略验证某个制品的签名时记录的已验证签名事实。两种记录都使用这同一种结构——锁文件用于它的每个条目,本记录用于每个插件——因此已验证的签名在两个文件中的读法相同。它记录验证模式、匹配到的无密钥身份/签发者(无密钥时)或固定密钥的指纹(有密钥时),以及 pull 所缓存的签名包的内容寻址摘要。

属性类型必需描述
bundle_digeststring是缓存的签名包 blob 的 SHA-256 摘要,格式为 sha256: 后跟 64 个小写十六进制字符。它为缓存 blob 命名,因此会用于构建路径,不含 /、\ 和 ..(sha256: 格式本身已排除这些字符);构建、限定于 release 的 lint 以及限定于 release 的验证都会对该 blob 重新计算哈希,并与它比对。模式:^sha256:[a-f0-9]{64}$。
identitystring否签名的已验证签名者:无密钥签名时为签名证书的主体;有密钥签名时为 keyed:sha256: 后跟固定公钥 PEM 文本的 SHA-256。
issuerstring否无密钥签名的已验证 OIDC 签发者。有密钥签名时为空。
modestring(枚举)是接纳该签名的验证模式。允许的值:"keyless"、"keyed"

不允许其他属性。