Rekor 可插拔类型（Pluggable Types）机制深度解析：透明日志条目 Schema 插件体系与 BuildKit 中的落地实践-北京尧图网络

Rekor 可插拔类型Pluggable Types机制深度解析透明日志条目 Schema 插件体系与 BuildKit 中的落地实践【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkitRekor 是 Sigstore 软件供应链安全体系中的透明日志transparency log组件而可插拔类型Pluggable Types是它用来支撑多种日志条目格式的核心架构。本文以本仓库 vendor 中 pkg/types/README.md 为骨架结合其 types.go、entries.go、versionmap.go 等源码实现系统讲解 Rekor 如何通过 Schema 版本化的方式让同一条日志承载签名记录、DSSE 信封、in-toto 证言等多种数据类型并说明 BuildKit 为什么只需要 vendor 其中三种类型。读完本文你将掌握 Rekor 类型插件的注册、解析、版本路由与落库全流程并理解它与 BuildKit attestation 产物之间的对应关系。一、什么是 Rekor 的可插拔类型Rekor 是一个面向软件供应链的透明日志服务它把某个签名、某个证书、某个软件工件的加密学证据固化到不可篡改的日志中供事后审计与验证。然而不同类型的证据结构差异巨大——一条简单的 GPG 签名记录与一份完整的 in-toto 证言attestation在字段组织上完全不同。如果日志只接受一种固定格式就无法覆盖多样化的供应链安全场景。为此Rekor 引入了可插拔类型Pluggable Types日志中的每一条条目entry都归属于一个具体的类型kind而每种类型又对应一套 JSON Schema并可以拥有多个版本version。正如 pkg/types/README.md 所描述的Rekor supports pluggable types (aka different schemas) for entries stored in the transparency log——可插拔类型的本质就是为存储进透明日志的条目提供不同的 Schema。这种设计带来的直接收益是格式解耦类型与核心日志逻辑解耦新增一种证据格式无需改动日志写入、索引、验证的通用链路向后兼容同一类型可以并行保留多个版本老版本条目在日志中仍然可读可扩展性社区可以按既定约定为 Rekor 增加新的类型支持README 末尾也给出了官方扩展指引。二、当前支持的类型全景README 开列了 Rekor 当前支持的全部类型与对应 Schema、版本号。这里完整继承并整理如下类型Kind用途版本Alpine PackagesAlpine 软件包签名记录0.0.1COSE EnvelopesCOSE 签名信封0.0.1DSSE EnvelopesDSSEDead Simple Signing Envelope签名信封0.0.1HashedRekord仅存储工件哈希的签名记录0.0.1Helm Provenance FilesHelm Chart 来源证明文件0.0.1In-Toto Attestationsin-toto 证言attestation0.0.1、0.0.2Java Archives (JAR Files)Java JAR 包签名记录0.0.1Rekord默认类型通用签名记录含工件内容0.0.1RFC3161 TimestampsRFC3161 时间戳令牌0.0.1RPM PackagesRPM 软件包签名记录0.0.1TUF MetadataTUF 元数据签名记录0.0.1其中Rekord被标记为默认类型default type即未显式指定类型时使用的兜底条目格式。需要特别指出的是本文所在仓库BuildKit是 Rekor 的消费方vendor 目录中只保留了与构建产物证言attestation最相关的三个类型的完整实现与 Schema即dsse、hashedrekord、intoto见 vendor/github.com/sigstore/rekor/pkg/types 目录结构。表中其余类型属于完整 Rekor 服务端支持范围本仓库未携带其源码文件下文源码分析将以这三个 vendored 类型为主。三、插件架构源码级剖析可插拔类型的实现由三部分构成类型注册表TypeMap、类型基类与接口RekorType / TypeImpl、版本工厂映射VersionMap。三者共同完成按 kind 找到类型、按 version 找到实现的两级路由。3.1 类型注册表 TypeMap在 types.go 中Rekor 用一个sync.Map保存类型字符串 → 类型构造器的映射// TypeMap stores mapping between type strings and entry constructors // entries are written once at process initialization and read for each transaction, so we use // sync.Map which is optimized for this case var TypeMap sync.Map从注释可以读出设计意图映射在进程初始化阶段一次性写入各类型通过各自的init()完成注册随后每次日志事务都会读取。写少读多、且并发读频繁因此选用专为这种场景优化的sync.Map。每种具体类型在自己的包中完成注册。以 dsse.go 为例func init() { types.TypeMap.Store(KIND, New) } func New() types.TypeImpl { bit : BaseDSSEType{} bit.Kind KIND bit.VersionMap VersionMap return bit }hashedrekordhashedrekord.go与intotointoto.go采用完全相同的注册模式包内定义KIND常量init()阶段把New构造器存入TypeMap。这意味着新增一种类型只需新增一个包并实现接口无需改动任何既有代码——这正是可插拔的落点。TypeMap 还提供了两个查询入口types.goListSupportedKinds()返回所有已加载的条目 kindListImplementedTypes()返回所有kind:version组合的列表形如intoto:0.0.2供 API 对外暴露能力清单。3.2 类型基类 RekorType 与接口 TypeImpl每种类型的基类都嵌入统一的RekorType结构types.gotype RekorType struct { Kind string // this is the unique string that identifies the type VersionMap VersionEntryFactoryMap // this maps the supported versions to implementation }它携带两个字段类型标识Kind以及负责版本 → 实现工厂分发的VersionMap。所有类型都必须实现TypeImpl接口types.gotype TypeImpl interface { CreateProposedEntry(context.Context, string, ArtifactProperties) (models.ProposedEntry, error) DefaultVersion() string SupportedVersions() []string IsSupportedVersion(string) bool UnmarshalEntry(pe models.ProposedEntry) (EntryImpl, error) }接口中一个关键方法是VersionedUnmarshal定义于 types.go它演示了版本路由的完整过程先从VersionMap中按版本取出工厂函数ef调用ef()生成该版本的条目实例若传入的 proposed entry 非空则调用其Unmarshal方法填充数据func (rt *RekorType) VersionedUnmarshal(pe models.ProposedEntry, version string) (EntryImpl, error) { ef, err : rt.VersionMap.GetEntryFactory(version) if err ! nil { return nil, fmt.Errorf(%s implementation for version %v not found: %w, rt.Kind, version, err) } entry : ef() ... return entry, entry.Unmarshal(pe) }DefaultVersion()、SupportedVersions()、IsSupportedVersion()则分别回答默认用哪个版本、支持哪些版本、某个版本能否写入日志。3.3 版本工厂映射 VersionEntryFactoryMap 与语义化版本路由versionmap.go 定义了版本映射接口type VersionEntryFactoryMap interface { GetEntryFactory(string) (EntryFactory, error) // return the entry factory for the specified version SetEntryFactory(string, EntryFactory) error // set the entry factory for the specified version Count() int // return the count of entry factories currently in the map SupportedVersions() []string // return a list of versions currently stored in the map }其默认实现SemVerEntryFactoryMap是这篇文章最值得展开的细节它并不做字符串等值匹配而是用 blang/semver 库做语义化版本区间匹配versionmap.goSetEntryFactory(constraint, ef)把形如0.0.1、0.0.1的版本约束作为 key 存入factoryMap写入前先用semver.ParseRange校验约束合法性GetEntryFactory(version)先把请求版本解析为semver.Version再遍历 map用每个约束的 range 去匹配返回第一个匹配的工厂函数内部用sync.RWMutex保护并发读写。这一设计让支持版本的表达能力远超普通 map未来可以轻松表达0.0.2, 1.0.0都归到某个实现这类区间路由。每个类型在包的init()中向自己的VersionMap注册版本实现例如 DSSE v0.0.1 在 dsse/v0.0.1/entry.go 中func init() { if err : dsseType.VersionMap.SetEntryFactory(APIVERSION, NewEntry); err ! nil { log.Logger.Panic(err) } }3.4 版本化条目的行为契约 EntryImpl版本路由最终得到的对象是EntryImpl——它是某个具体版本条目的行为契约entries.gotype EntryImpl interface { APIVersion() string // the supported versions for this implementation IndexKeys() ([]string, error) // the keys that should be added to the external index for this entry Canonicalize(ctx context.Context) ([]byte, error) // marshal the canonical entry to be put into the tlog Unmarshal(e models.ProposedEntry) error // unmarshal the abstract entry into the specific struct for this versioned type CreateFromArtifactProperties(context.Context, ArtifactProperties) (models.ProposedEntry, error) Verifiers() ([]pkitypes.PublicKey, error) // list of keys or certificates that can verify an entrys signature ArtifactHash() (string, error) // hex-encoded artifact hash prefixed with hash name, e.g. sha256:abcdef Insertable() (bool, error) // denotes whether the entry that was unmarshalled has the writeOnly fields required to validate and insert into the log }各方法分工清晰Unmarshal把抽象 proposed entry 落到具体结构体Canonicalize产出写入透明日志的规范化字节IndexKeys决定该条目在外部索引供检索中暴露的键Verifiers返回能验证条目签名的公钥/证书ArtifactHash返回形如sha256:abcdef的工件摘要Insertable报告反序列化后的条目是否携带写入所需的 writeOnly 字段。对于还承载证言attestation的类型另有扩展接口EntryWithAttestationImplentries.go追加AttestationKey与AttestationKeyValue两个方法用于证言的存取。四、三种 vendored 类型与 Schema 详解本仓库实际携带了dsse、hashedrekord、intoto三套完整实现。下面结合各自的 JSON Schema 与实现逐一拆解。4.1 HashedRekord v0.0.1只存哈希的签名记录HashedRekord 与默认类型 Rekord 的最大区别是它不存工件原始内容只存工件的哈希从而避免把大型工件写入日志。其 Schema 位于 hashedrekord/v0.0.1/hashedrekord_v0_0_1_schema.json顶层结构为{ signature: { content: { type: string, format: byte }, publicKey: { content: { type: string, format: byte } } }, data: { hash: { algorithm: { enum: [sha256, sha384, sha512] }, value: { type: string } } }, required: [signature, data] }要点signature.content内联的签名内容base64 编码的字节串signature.publicKey.content可验证该签名的公钥也允许直接放 X.509 代码签名证书Schema 描述明确写明 this can also be an X509 code signing certificate证书中即含公钥信息data.hash.algorithm枚举限定为sha256/sha384/sha512三种哈希算法data.hash.value工件哈希值必须是小写十六进制字符串Schema 描述as represented by a lower case hexadecimal string。该类型的实现入口见 hashedrekord.goUnmarshalEntry先做类型断言pe.(*models.Hashedrekord)再校验APIVersion非空最后交给VersionedUnmarshal按版本路由到 v0.0.1 实现DefaultVersion()返回0.0.1。4.2 DSSE v0.0.1签名信封DSSEDead Simple Signing Envelope是 Sigstore 推荐的签名封装格式被 in-toto 证言广泛采用。其 Schema 位于 dsse/dsse_schema.json通过oneOf引用 dsse/v0.0.1/dsse_v0_0_1_schema.json。后者字段分为三组读写权限刻意区分proposedContentwriteOnly提交时使用内含envelope整个 DSSE 信封的字符串化 JSON与verifiers验证材料base64 编码的公钥/证书数组至少 1 项二者均为必填signaturesreadOnly读取时返回服务端从信封中提取出的签名集合按 base64 签名串的字典序排序每项含signature带 base64 正则校验与verifierenvelopeHash/payloadHash均readOnly前者是整个信封含签名的摘要后者是信封内payload的摘要算法均枚举为sha256。vendor/github.com/sigstore/rekor/pkg/types/dsse/README.md 对存储语义做了关键澄清值得原文继承如何识别条目的Body字段中包含dsseObj字段即为 DSSE 对象可识别的内容类型in-toto statement 会被识别并解析其中 subject 的哈希会被加入索引以便检索Rekor 实际存储什么只存 payload 的哈希、整个 DSSE 信封含签名的哈希、签名以及对应的验证材料公钥/证书即使配置了 attestation 存储也不会存储完整的 DSSE 信封。这种只存哈希、不存全文的取舍既保证了证据可校验又控制了日志体积。4.3 In-Toto v0.0.1 / v0.0.2软件供应链证言in-toto 类型承载的是证言attestation——关于软件工件的一种可认证、机器可读的元数据。本仓库中 intoto/intoto_schema.json 通过oneOf同时引用 v0.0.1 与 v0.0.2 两个版本的 Schema这与 README 中Versions: 0.0.1, 0.0.2一致也是 11 个类型中唯一支持双版本的类型。vendor/github.com/sigstore/rekor/pkg/types/intoto/README.md 给出了语义约定Attestation关于一个或多个软件工件的可认证、机器可读的元数据采用 SLSA 定义其值应为Base64 编码的 JSON 对象AttestationType标识证言类型如 provenance 构建来源证言、漏洞扫描证言即使其值带有http前缀也不一定是一个可访问的 URL如何识别条目的Body字段中包含IntotoObj字段即为 in-toto 对象。v0.0.2 的 Schemaintoto/v0.0.2/intoto_v0_0_2_schema.json结构为{ content: { envelope: { payload: { type: string, format: byte, writeOnly: true }, payloadType: { type: string }, signatures: { type: array, minItems: 1, items: { keyid: { type: string }, sig: { type: string, format: byte }, publicKey: { type: string, format: byte } }, required: [sig, publicKey] } }, hash: { algorithm: { enum: [sha256] }, value: { type: string } }, payloadHash: { algorithm: { enum: [sha256] }, value: { type: string } } }, required: [content] }可见 v0.0.2 直接在条目内嵌DSSE 信封content.envelopepayload为 writeOnly 的字节串signatures中每项含可选的keyid、必填的sig与publicKeyhash覆盖整个信封payloadHash覆盖 payload二者均为sha256且 readOnly。实现层面intoto.go 有两点值得注意DefaultVersion()返回0.0.2而SupportedVersions()返回[0.0.2, 0.0.1]按偏好顺序与 README 的版本列表对应CreateProposedEntry在未指定版本时会构建一个ProposedIntotoEntryIterator链表把支持的所有版本都生成一遍intoto.go由上层逐项尝试提交——这样即使某个版本在当前服务端被禁用其他版本仍可兜底。v0.0.2 实现 intoto/v0.0.2/entry.go 还展示了证言类型的索引逻辑IndexKeys对每个签名计算其规范化公钥的sha256:hex摘要并追加 key 的Subjects()随后追加payloadHash的algorithm:value键当payloadType为 in-toto 时还会解析 statement 的 subject。此外该文件定义了maxAttestationSize 100 * 1024100 KiB的证言大小上限并提供SetMaxAttestationSize供外部调整防止超大证言拖垮日志服务。五、条目的完整生命周期从提交到落库理解插件机制后再看一条日志条目的生命周期源码路径为 entries.go。5.1 统一参数载体 ArtifactPropertiesCLI 传入的工件、签名、公钥等杂项信息统一收敛到ArtifactProperties结构entries.gotype ArtifactProperties struct { AdditionalAuthenticatedData []byte ArtifactPath *url.URL ArtifactHash string ArtifactBytes []byte SignaturePath *url.URL SignatureBytes []byte PublicKeyPaths []*url.URL PublicKeyBytes [][]byte PKIFormat string }它的注释点明了职责provide a consistent struct for passing values from CLI flags to the typeversion specific CreateProposeEntry() methods——即把 CLI 层与类型实现层解耦各类型只需按需取用。5.2 创建 Proposed EntryNewProposedEntry(ctx, kind, version, props)entries.go从TypeMap中取出 kind 对应的构造器实例化TypeImpl后调用CreateProposedEntry(ctx, version, props)。类型实现内部会先补默认版本如if version { version it.DefaultVersion() }见 dsse.go再通过VersionedUnmarshal(nil, version)拿到版本实现最终调用其CreateFromArtifactProperties生成具体的 proposed entry。5.3 校验并落库CreateVersionedEntryCreateVersionedEntry(pe)entries.go是插入路径insertion flow的入口它依次执行三道检查kind 白名单isKindAllowedForSubmission检查该 kind 是否在服务端启用。值得注意的是这个白名单通过SetAllowedKindsForSubmission配置entries.go且用atomic.Pointer存储以支持运行时热更新注释明确说明该限制只作用于插入路径读取路径不受影响——这样在旧配置下写入的条目永远可读版本支持TypeMap中能找到该 kind且其IsSupportedVersion(ei.APIVersion())为真可插入性ei.Insertable()返回真即反序列化出的条目携带了写入所需的 writeOnly 字段。三道检查全部通过后条目才能进入签名、写入透明日志的后续阶段。与之相对的UnmarshalEntry(pe)entries.go是读取路径不校验版本是否仍可写入只做类型断言与版本路由适用于回读历史条目。5.4 解码与规范化DecodeEntry / CanonicalizeEntry两个辅助函数保证了条目数据的正确性DecodeEntry(input, output)entries.go基于mapstructure实现字段类型转换当目标字段是[]byte时自动对源字符串做 base64 解码当目标字段是strfmt.DateTime时自动解析时间串CanonicalizeEntry(ctx, entry)entries.go先把条目 marshal 出来再经jsoncanonicalizer.Transform按RFC 8785JCSJSON Canonicalization Scheme做规范化以防止 Go 的 JSON marshal 因实现差异重排字段顺序——这是保证透明日志条目字节级确定性、进而保证可校验性的关键。六、与 BuildKit 的关联证言产物如何对接 in-toto 类型理解了 Rekor 的 in-toto 类型后就能明白 BuildKit 为什么 vendor 上述代码。BuildKit 在构建镜像时支持生成SBOM、provenance 等 in-toto 证言attestation这些证言最终可被推送到 Rekor 之类的透明日志中存档验证。本仓库中exporter/attestation/make.go 的MakeInTotoStatementsL105-L120逐条读取构建结果中的 attestation 内容将其组装为 in-totoStatementmakeInTotoStatementL137-L179把每个 subject 按其类型映射为 in-toto 的Subject{Name, Digest}通过result.ToDigestMap把 digest 列表转为{algorithm: value}映射并生成以intoto.StatementInTotoV1为类型的 statement 头。证言内容读取受maxAttestationBytes 80 2080 MiB上限保护make.go读取逻辑make.go用io.LimitedReader限制大小。这段代码与 Rekor 侧正好形成闭环BuildKit 侧把构建产物包装成 in-toto Statement其 subject digest 结构就是 intoto/v0.0.2/intoto_v0_0_2_schema.json 中payloadHash/hash所覆盖的 DSSE 信封内容Rekor 侧intoto类型按 Schema 解析这些信封提取签名、计算哈希、生成IndexKeys供检索——两者通过同一套 in-toto/DSSE 数据模型对齐。这也解释了为何本仓库只需 vendordsse、hashedrekord、intoto三个类型它们是签名哈希证言这条最核心证据链的载体与 BuildKit 的镜像签名与 attestation 场景直接相关而 Alpine/RPM/Helm 等包管理器类型对构建工具链而言并非必需。七、如何扩展新类型README 指出新增类型支持请参阅 Rekor 官方文档pluggable-types 章节。从本文已分析的源码模式出发可以梳理出完整的扩展路径新建类型包在pkg/types/kind/下创建包定义KIND常量定义 Schema编写*_schema.json含版本子目录如v0.0.1/用 JSON Schema 描述条目结构并区分 writeOnly提交字段与 readOnly返回字段实现 TypeImpl定义嵌入types.RekorType的基类在init()中调用types.TypeMap.Store(KIND, New)注册New()返回携带VersionMap的类型实例注册版本实现在v0.0.1/entry.go等版本子包中实现EntryImpl含APIVersion、Canonicalize、IndexKeys、Unmarshal、CreateFromArtifactProperties、Verifiers、ArtifactHash、Insertable并在init()中调用VersionMap.SetEntryFactory(version, NewEntry)接入服务端通过SetAllowedKindsForSubmission将新 kind 加入插入白名单。其中intoto类型的ProposedIntotoEntryIterator模式intoto.go提供了一个多版本并存的参考实现在未指定版本时生成一个 proposed entry 迭代器让上层逐个版本尝试提升提交成功率。八、总结Rekor 的可插拔类型机制本质上是一套kind 注册表 semver 版本路由 JSON Schema 描述版本化 EntryImpl 实现的四层插件体系TypeMapsync.Map在初始化期完成 kind → 类型构造器的注册写少读多的访问模式选型精准SemVerEntryFactoryMap用语义化版本区间做版本路由让支持版本的表达能力远超普通字符串 map每个类型通过 writeOnly/readOnly 字段分离提交载荷与返回视图并通过 RFC 8785 规范化保证透明日志的字节级确定性插入路径的 kind 白名单与版本支持校验配合只作用于写入的allowedKindsForSubmission兼顾了服务端管控与历史条目可读性。对本仓库BuildKit而言vendor 的dsse、hashedrekord、intoto三个类型与 exporter/attestation 的证言生成逻辑共同构成了完整的供应链证据闭环BuildKit 产出 in-toto StatementRekor 侧以 in-toto/DSSE 类型将其解析、索引并固化为透明日志条目从而让镜像的 provenance 与 SBOM 可被独立验证与审计。【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Rekor 可插拔类型（Pluggable Types）机制深度解析：透明日志条目 Schema 插件体系与 BuildKit 中的落地实践

相关推荐

长沙市POI数据处理实战：从7z解压到DEM叠加分析

C++实现结构光激光中心线亚像素提取

Carbon Web Components 的 `cds-code-snippet` 渲染原理与快照测试深度解析

更多资讯

multi-agent-orchestrator TypeScript 本地快速上手：用 MultiAgentOrchestrator 构建多智能体编排应用

YOLOv5 架构深度解析：模型结构、数据增强、训练策略与损失计算全指南

Page Assist 与 Ollama 深度集成指南：模型管理、免终端拉取与下载进度追踪全攻略

es-toolkit 的 cond 函数：用函数式风格编排多条件分支的 Lodash 兼容实现

CloudNativePG 服务管理详解：rw/ro/r 三型 Service 的禁用、自定义与集群外暴露

Yi 模型 4-bit 量化实战：基于 AutoAWQ 的激活感知权重量化完整指南

今日更新

基于MATLAB的CRI显色指数计算：从SPD光谱到Ra的完整流程

JSP+Servlet+MySQL博客系统源码部署与优化全攻略

蜂窝调度算法 MATLAB 实现：比例公平、轮询与最大 C/I 对比

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？