Argo CD Source Verification Policies：基于 Git/GPG 的源码完整性验证体系深度解析

Argo CD Source Verification Policies：基于 Git/GPG 的源码完整性验证体系深度解析

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

Source Verification Policies（SVP，源码验证策略）是 Argo CD 对传统 GnuPG 提交签名验证机制的演进式设计，它把"签名验证"从项目级的一刀切约束细化为"按源码仓库、按验证严格度"的多策略体系，并为未来接入 Helm provenance、sigstore 等更多验证方法预留了扩展空间。本文以 docs/proposals/source-verification-policies.md 提案为核心骨架，结合 pkg/apis/application/v1alpha1/source_integrity.go、util/sourceintegrity/source_integrity.go 等仓库实现与官方用户指南，系统讲解策略结构、none/head/strict三种验证模式、策略匹配顺序、密钥管理、seal 提交以及升级迁移的完整方法论。

一、背景与动机：为什么需要源码验证策略

作为部署工具，Argo CD 处于实施供应链安全要求的关键位置。对来源与制品的密码学验证对组织越来越重要，且在部分行业受到严格监管。Argo CD 很早就通过 GnuPG 提供对 Git 提交的 OpenPGP 签名验证能力，但该特性存在明显局限：

• 只验证 HEAD：Argo CD 仅验证Application解析后的targetRevision所指向的HEAD提交签名，这不足以满足许多组织对"整条历史都被签名"的要求。
• All-or-Nothing 模式：验证对任意给定AppProject是"全有或全无"的，无法对不同仓库施加不同的信任等级。不同仓库可能有不同的贡献者集合、不同的签名/贡献规范。
• 无法细分多源应用：多源应用出现后，为项目所有仓库/应用统一配置可信签名者的方式缺乏灵活性。

SVP 正是针对这些问题而生，它引入了新的验证模式、允许同一 Application 中的多个源码使用不同严格度的策略，并为此后实现更多非 GPG、非 Git 专属的验证方法奠定基础。

目标（Goals）

• 提升 Git 提交验证的置信度；
• 基于源码仓库管理签名者信任（比基于应用项目更细粒度）；
• 具备足够的灵活性以支持未来的其他验证提供方（如 Helm provenance、sigstore 签名的 Git 等）；
• 让用户易于迁移到更安全的验证策略；
• 与现有 GnuPG 提交验证机制完全向后兼容。

非目标（Non-Goals）

• 不实现 GnuPG 之外的 Git 提交验证方法——这可能留待以后，而 SVP 的设计本身已允许这些方法较容易地集成进来。

二、核心概念：Source Verification Policy 的配置结构

SVP 配置在AppProject的.spec.sourceIntegrity字段下，示意结构如下（取自 docs/proposals/source-verification-policies.md）：

apiVersion: argoproj.io/v1alpha1 kind: AppProject spec: sourceIntegrity: # 超出当前范围，此处仅演示声明结构允许未来扩展到不同来源类型 # helm: {} git: policies: - repos: - url: "https://github.com/foo/*" gpg: mode: "none|head|strict" keys: - "0xDEAD" - "0xBEEF"

在仓库中，这一结构被实现在 pkg/apis/application/v1alpha1/source_integrity.go：

• SourceIntegrity：顶层结构，当前只包含git字段（在出现替代方案之前是必填字段）；
• SourceIntegrityGit：持有policies策略列表；
• SourceIntegrityGitPolicy：一条策略由repos（仓库匹配条件）与gpg（验证方法，当前唯一受支持方法，同样为必填）构成；
• SourceIntegrityGitPolicyRepo：单一 URL 匹配模式；
• SourceIntegrityGitPolicyGPG：验证模式与可信密钥列表。

type SourceIntegrityGitPolicyGPG struct { Mode SourceIntegrityGitPolicyGPGMode `json:"mode" protobuf:"bytes,1,name=mode"` // List of key IDs to trust. The keys need to be in the repository server keyring. Keys []string `json:"keys" protobuf:"bytes,3,name=keys"` }

策略的 repos 匹配规则

repos是与待验证源码 URL 进行匹配的 glob 风格模式列表。当模式匹配到某个源时，该源会被验证；否则跳过对该源的验证。

用户指南 docs/user-guide/source-integrity-git-gpg.md 进一步明确了实际实现中的匹配语义：repos可以同时包含正向 glob 与以!开头的负向 glob（排除模式），当 URL 匹配任一正向 glob 且不被任何负向 glob 匹配时，该策略生效：

spec: sourceIntegrity: git: policies: - repos: - url: "https://github.com/my-group/*" - url: "!https://github.com/my-group/ignored.git" gpg: mode: "none|head|strict" keys: - "D56C4FCA57A46444"

对应源码在 util/sourceintegrity/source_integrity.go 的findMatchingGitPolicies与repoMatches函数中：正向模式命中返回 1（include），!前缀的负向模式命中返回 -1（排除并中断），否则返回 0。

GPG 验证策略

目前 GPG 是唯一受支持的验证方法，它使用 GnuPG 验证 Git 提交上的 PGP 签名，本质上是带配置密钥环调用git verify-commit/git verify-tag，并确保签名使用的密钥 ID 位于策略声明的可信密钥 ID 列表内（见 docs/user-guide/source-integrity-git-gpg.md 及 util/sourceintegrity/source_integrity.go 的verify函数）。

关于keys的要点：

• keys列出用于签名提交的可信密钥 ID 集合；
• 若提交由列表中未出现的 ID 签名，验证将失败；
• 若未配置任何可信密钥，则信任argocd-gpg-keys-cmConfigMap 中的所有签名者；
• 除了将密钥 ID 列入白名单，密钥本身还必须通过既有机制导入 Argo CD（导入仓库服务器密钥环）；
• 从源码实现看，还支持"签名子密钥"自动解析回主密钥：当 git 使用子密钥签名而策略中列出的是主密钥时，gpgProblemMessage会通过lookupPrimaryKeyID将 16 位短密钥 ID 解析为主密钥再判断是否允许（util/sourceintegrity/source_integrity.go）。

mode定义 GPG 验证的严格程度，其类型常量在 pkg/apis/application/v1alpha1/source_integrity.go 中定义：

mode	含义	源码注释要点
none	不执行任何 GPG 验证	对排障场景有用
head	验证目标修订所指向的 HEAD 提交	对注解标签验证标签签名
strict	验证目标修订的全部祖先提交直至 git init 或 seal 提交	若指向注解标签，同时验证标签签名与提交历史

三、验证模式详解

以一个简单的修订历史为例（见 docs/proposals/source-verification-policies.md）：

HEAD 1.0 2.0 + + | | A---B---C---D---E---F - - - + + +

其中A到F是构成仓库历史的提交，1.0与2.0是分别指向对应提交的注解标签。HEAD指向F（即2.0）。+/-表示提交或标签是否由可信密钥签名——提交D、E、F已签名，两个标签也已签名。

模式none

此模式下，Application 可以同步上述任意修订，无论源上是否存在有效签名。不执行验证。需要注意：none模式不仅接受未签名提交，也接受某种意义上有缺陷的签名（过期、不可验证等）的提交（见 docs/user-guide/source-integrity-git-gpg.md）。

模式head

• 若targetRevision指向提交A、B或C，将不被信任（未签名）；
• 指向D、E或F则被信任；
• 指定HEAD（命名分支的尖端）、1.0或2.0会成功验证：HEAD因指向的修订已签名，1.0/2.0因是签名标签。

实际语义上，若修订是注解标签，则验证标签本身签名（标签必须通过git tag -s签名）；否则若目标是分支名、引用名（如HEAD）或提交 SHA，Argo CD 验证提交的 GnuPG 签名。这一点在 util/git/client.go 的LsSignatures中体现：当修订是注解标签且deep为 false 时，仅返回标签签名。

模式strict

严格模式不会信任该 git 历史的任何一点，因为历史包含未签名的提交A、B和C。它验证目标修订及其全部祖先，确保历史上不存在任何未签名变更；若修订为注解标签，标签签名与提交历史（含其指向的提交）一并验证。

四、策略顺序的意义与多源应用

策略是非累积的：每个源码仓库只应用一条策略，因此定义的顺序非常重要。

• 多源应用的各源码仓库可分别基于不同的 SVP 进行验证；
• Argo CD 选择第一条匹配仓库源 URL 的策略，并忽略其后任何策略；
• 策略自上而下求值，因此更具体的策略必须放在更宽泛的策略之前。

示例（来自 docs/proposals/source-verification-policies.md）：希望验证来自github.com的所有仓库的提交都带有 GitHub web 签名密钥的有效签名，但对某个特定仓库施加不同的策略——使用strict模式并额外允许另一个签名者。正确写法是具体策略在前、宽泛策略在后：

apiVersion: argoproj.io/v1alpha1 kind: AppProject metadata: name: gpg namespace: argocd spec: sourceIntegrity: git: policies: - repos: - url: 'https://github.com/example/super-secure' gpg: mode: strict keys: - 4AEE18F83AFDEB23 - D56C4FCA57A46444 - repos: - url: 'https://github.com/*' gpg: mode: head keys: - 4AEE18F83AFDEB23

若顺序颠倒，https://github.com/example/super-secure的专用策略永远不会被匹配，因为该 URL 已被https://github.com/*模式匹配，宽泛策略会被应用。

从源码看，这种"多策略匹配即视为配置错误"的行为有防御性设计：lookupGit中若发现同一仓库匹配多条策略，会返回一个必然失败的检查结果，以确保配置错误不会静默关闭验证（util/sourceintegrity/source_integrity.go）。这与提案中"自上而下取第一条"的规则互为补充——正常情况下应只匹配一条，多匹配属于需要告警的异常。

提案还指出，Argo CD CLI 与 UI 需要提供视觉指示，标出未执行 GPG 验证的项目仓库，为管理员提供仓库匹配求值的反馈。

五、源码级纵深：从策略声明到签名验证的调用链

SVP 的实际执行横跨多个模块，理解调用链有助于排障与二次开发：

1. 策略求值入口：util/sourceintegrity/source_integrity.go 的VerifyGit依据 git client 的RepoURL()查找到期匹配的策略，找不到时返回空（跳过验证）；HasCriteria则判断任一源是否声明了相关标准（排除 OCI 与 Helm 源）。

2. GPG 验证开关：IsGPGEnabled()读取环境变量ARGOCD_GPG_ENABLED，当其值为false/no（不区分大小写）时返回 false（util/sourceintegrity/source_integrity.go）。策略中 GPG 验证方法可通过该环境变量整体停用。

3. 底层 git 操作：verify调用gitClient.LsSignatures(ctx, verifiedRevision, deep)（util/git/client.go），该函数：

   • 先解析语义化版本标签约束（如v1.0.x）到具体标签；
   • 通过VerifyCommitSignature获得兼容 legacy 行为的描述字符串（用于signatureKeys兼容路径）；
   • 若目标是注解标签，读取标签签名；非 deep 模式就此返回；
   • 通过git rev-list列出提交签名信息（CSV 形式），构造RevisionSignatureInfo列表。

4. 问题描述与结果：describeProblems汇总最多 10 条最近的问题签名/未签名提交（避免刷屏 UI 与日志），同密钥相关问题会被折叠；SourceIntegrityCheckResult通过PassedChecks()/AsError()/IsValid()供上层判断同步是否放行（pkg/apis/application/v1alpha1/source_integrity.go）。多源场景下用InjectSourceName为各源的问题消息加上源名前缀以便区分。

5. strict 模式下的 seal 提交：LsSignatures在 deep 模式下会先搜索带Argocd-gpg-seal:trailer 的签名提交作为"封条"，仅验证从目标修订回溯至最近 seal 提交之间的历史（util/git/client.go）。相关行为有单元测试覆盖，见 util/git/gpg_verification_test.go（Test_LsSignatures_Sealed_linear、Test_LsSignatures_UnsignedSealedCommitDoesNotStopHistorySearch）。

6. CLI 管理入口：cmd/argocd/commands/project_source_integrity.go 提供argocd proj source-integrity git policies子命令树（list/add/update/delete），支持以--repo-url、--gpg-mode、--gpg-key等标志声明式管理策略；add/update时还会调用warnOnProblems检查策略是否含空仓库模式、密钥是否已存在于 repo-server 密钥环（不在则告警，见同文件warnOnProblems函数）。

六、GnuPG 密钥环管理

验证的前提是可信密钥已进入 Argo CD 的 GnuPG 密钥环。Argo CD 采用极简信任模型：密钥一旦导入即被信任，不支持更复杂的信任模型，也不需要对导入的公钥进行再签名（见 docs/user-guide/source-integrity-git-gpg.md）。

RBAC 规则

管理 GnuPG 密钥对应的资源记法是gpgkeys：

p, role:myrole, gpgkeys, get, *, allow # 列出 p, role:myrole, gpgkeys, create, *, allow # 添加 p, role:myrole, gpgkeys, delete, *, allow # 删除

CLI 管理

argocd gpg list # 列出所有已配置密钥 argocd gpg get <key-id> # 查看某密钥信息 argocd gpg add --from <path-to-key> # 导入公钥（二进制或 ASCII armor 格式） argocd gpg rm <key-id> # 移除密钥

Web UI 与声明式配置

Web UI 的Settings → GnuPG keys模块支持列出、导入与移除（UI 导入目前要求 ASCII armor 格式）。声明式配置下，密钥存放在argocd-gpg-keys-cmConfigMap 中，条目名为公钥 ID、值为 ASCII armor 密钥数据，例如 GitHub web-flow 签名密钥（节选）：

4AEE18F83AFDEB23: | -----BEGIN PGP PUBLIC KEY BLOCK----- ... -----END PGP PUBLIC KEY BLOCK-----

密钥环位置与同步

密钥环由argocd-repo-serverPod 维护，从argocd-gpg-keys-cmConfigMap 同步（该 ConfigMap 以卷挂载方式提供给 repo-server Pod）。可通过kubectl exec进入 repo-server Pod 检查：

$ kubectl exec -it argocd-repo-server-7d6bdfdf6d-hzqkg bash argocd@argocd-repo-server-7d6bdfdf6d-hzqkg:~$ GNUPGHOME=/app/config/gpg/keys gpg --list-keys

注意：Pod 内密钥环是瞬态的，每次重启都会从配置重建，不应手工增删 Pod 内密钥；私有密钥也是临时的，仅用于构建运行中的信任数据库。若密钥环长期与配置不同步，可重启 repo-server Pod。

七、升级 / 降级迁移策略

升级（向后兼容）

升级是无缝的。当 Argo CD 检测到旧的 Git 提交验证配置（即AppProject的.spec.signatureKeys已填充）时，新实现会表现得与当前实现一致。内部会创建一个与此前示例类似的单一验证策略，从.spec.signatureKeys取密钥。

该兼容逻辑实现在AppProject.EffectiveSourceIntegrity()（pkg/apis/application/v1alpha1/types.go）：legacy 密钥被转换为repos: [{url: "*"}]+gpg: {mode: head, keys: legacyKeys}的单一策略；若项目同时声明了sourceIntegrity与signatureKeys，会记录错误并忽略后者；若只有非 git 的sourceIntegrity，则做深拷贝合并。signatureKeys字段本身已标记 Deprecated，将在下一个大版本移除（pkg/apis/application/v1alpha1/types.go）。

要迁移到新的源码验证策略，用户需要先移除.spec.signatureKeys，然后在.spec.sourceIntegrity.git.policies中定义期望的策略。

要在项目中复刻 legacy Argo CD 验证行为，使用以下配置（docs/proposals/source-verification-policies.md）：

apiVersion: argoproj.io/v1alpha1 kind: AppProject spec: sourceIntegrity: git: policies: - repos: # 针对项目中的任意仓库 - url: "*" gpg: mode: "head" # 仅验证 targetRevision 的 HEAD keys: - "..." # 来自 .spec.signatureKeys 的密钥

降级

降级时，用户必须将.spec.signatureKeys重新配置到所有曾移除它的 AppProject，并同时删除.spec.sourceIntegrity.git.policies。除非降级动机是 Argo CD 实现中的 bug，否则将模式移到head或none（取决于降级目标版本）通常已足够。用户指南补充提醒：legacy 功能缺乏新特性——对项目所有仓库而言它只是"全 head 模式"。

与 legacy 配置的共存约束

GnuPG 验证自 v1.7 起以signatureKeys形式作为项目级约束引入；自 Argo CD 3.5 起成为源码完整性验证方法之一，但采用不同的声明格式。配置在signatureKeys中的密钥将继续受支持，但不能与sourceIntegrity同时使用（见 docs/user-guide/source-integrity-git-gpg.md 的兼容性说明）。

八、安全考量

实施本提案将显著增强对 Git 仓库被攻破时的恢复力，典型威胁场景包括：

• 未授权贡献者获得提交权限；
• 签名密钥被泄露。

当攻击者同时攻破开发者凭据与签名密钥时，对手只能在其密钥被加入的那些仓库中迫使 Argo CD 信任其提交，而无法扩展到其他仓库——这就是"按仓库划分签名者集合"成为密钥泄露事件中又一道防线的意义。

需要注意的是，源码完整性验证具有全局影响：一旦启用，将无法再从本地源同步（即argocd app sync --local不可用，见 docs/user-guide/source-integrity.md 的警告）。另外，git generator 填充且project字段模板化的 ApplicationSet 不支持签名验证。

九、strict 模式与 Git 历史封条（Seal Commit）

"理想状态"是仓库从 init 起所有提交都经密码学签名，但现实往往并非如此。历史中出现未签名或签名但不可信提交的常见原因包括：

• 用户忘记签名提交 / 使用了非预期密钥；
• （配置错误的）工具创建的未签名提交，如 merge&squash、自动化或 IDE 创建；
• 密钥曾获批但因泄露、过期、密码学淘汰而轮换；
• 前贡献者不再受信任（离职等）；
• 希望接受不可信方的 Pull Request 并在未经可信 GPG 密钥重签的情况下合并；
• 仓库策略过去并未要求 GPG 签名。

处理这类提交若要求验证全部历史，往往需要 git 历史重写（rebase、force-push），这在技术与组织层面都存在诸多问题：force-push 常被作为安全措施明令禁止，要求用户"为提升安全而放松安全"是一种两难选择。部分问题可通过要求 push 时携带 GPG 签名来预防，但并非全部；且相比限制只能由固定 GPG 密钥集 push，在 git 托管平台禁用 force-push 更容易配置。

因此本提案将 git 历史重写视为不受欢迎、甚至技术上被禁止的操作，并引入**Git 历史封条（seal commit）**机制：

Seal Commit 的定义与用法

Seal commit 是一个 GPG 签名的提交，充当"批准印章"，证明其全部祖先提交要么由可信密钥签名，要么经提交作者审阅并信任。Argo CD 验证 GnuPG 签名时，只回溯到各祖先分支上最近的 seal 提交为止。

实际操作中，提交者先审阅自上一个 seal 以来所有未签名或不可信密钥签名的提交，然后创建一个（可能为空的）提交并在消息中包含自定义 trailer。这类提交可表达组织层面的语义：

• "从今往后，本仓库所有提交都将 GPG 签名，之前未签名的无须验证。"
• "我合并了来自不可信外部贡献者的变更，并对它们表示认可。"
• "我正在移除 Bob 的 GPG 密钥。他之前的所有提交仍受信任，但之后的新提交不再受信任。"
• "我正在用新密钥替换旧密钥：此提交之前由旧密钥签名的提交可信任，此后信任我的新密钥。"

创建 seal 提交的命令：

git commit --signoff --gpg-sign --trailer="Argocd-gpg-seal: <justification>"

随后推送到 Argo CD 拉取的分支。其优势是：同一套流程可以应对上述所有"历史中存在未签名/不可信提交"的情形，消除了因重写历史而出现 rebase 错误、进而危及安全或正确性的空间。还可以引入工具来帮助识别所有历史 seal 提交及之后产生的不可信提交，使管理员清楚自己在"封签"什么。

三种模式下的验证范围对比

## head mode T <- verified | \ | o | | o | | | | o | / o | o ## strict mode T <- verified | \ | o <- verified | | o | <- verified | | | o <- verified | / o <- verified | o <- verified ## strict mode - with seal commits T <- verified | \ | S <- verified (seal) | | S | <- verified (seal) | | | o | / o | o

（图示取自 docs/proposals/source-verification-policies.md。）

Git 历史封条可作为strict模式的一部分、最终通过标志启用，也可作为独立的"更宽松"模式启用。两种方式都不需要 force-push。仓库实现中，LsSignatures在 deep 模式下通过git rev-list --grep=Argocd-gpg-seal:搜索签名 seal 提交，并构造--boundary ... --not <seal...>过滤参数来界定验证范围（util/git/client.go）。

与原始 progressive 模式的比较

Seal-signing 的灵感来自一种原始模式：从targetRevision验证到上一次 Argo CD Application 成功同步的提交。两者都只向后验证历史到某个被视为天然可信的点。但仓库与 Application（甚至 Argo CD 实例）之间的非平凡 N:M 映射在原提案中引发了许多边界情况；而 seal-signing 把"从何处起不再验证"的标记放进仓库本身，确保所有 Argo CD 实例及其应用对可信边界有一致看法，与 Application 从 Argo CD 移除、Argo CD 迁移等事件无关。两种方案本质上都是通过限制待验证提交数来优化性能；对封条方案，即使没有未签名变更，提交者也需要手动添加 seal 提交以加速验证。此外，实现层面可对"每个仓库与策略最近一次 strict 验证通过的提交"做缓存，以尽力优化验证速度。

十、权衡与备选方案

权衡（Drawbacks）

• 配置源码验证策略给 Argo CD 实现与用户配置都增加了复杂度；
• 配置或实现不当本身可能成为安全事故源。

备选：如何对待本地 manifest

当前实现会在 GPG 开启且项目声明签名密钥时拒绝本地 manifest，未来可基于源码完整性标准的适用性（Git/OCI/Helm 与仓库）做选择性处理。

备选：验证策略配置在哪里

验证策略可以放在AppProject的sourceRepos中，例如：

spec: sourceRepos: # ...

但这将是破坏性变更，因为当前sourceRepos的条目类型只是string，必须变为复杂类型。提案建议可在下一个大版本中考虑把sourceIntegrity移入这些位置之一。

十一、结语与延伸阅读

Source Verification Policies 将 Argo CD 的源码验证从"项目级、单点、仅 HEAD"提升为"仓库级、多策略、可分级"的体系，同时通过EffectiveSourceIntegrity无缝兼容 legacysignatureKeys。无论你是想为关键仓库启用全历史签名校验，还是想对多源应用中不同仓库施加差异化信任，都可以按本文的方法在AppProject上完成配置。

相关资源（可在当前仓库中继续深入）：

• 提案原文：docs/proposals/source-verification-policies.md
• 用户指南总览：docs/user-guide/source-integrity.md
• Git GPG 验证指南（密钥管理、模式、迁移、排障）：docs/user-guide/source-integrity-git-gpg.md
• API 类型与模式常量定义：pkg/apis/application/v1alpha1/source_integrity.go
• Legacy 兼容转换逻辑：pkg/apis/application/v1alpha1/types.go
• 策略匹配与验证核心实现：util/sourceintegrity/source_integrity.go
• Git 签名枚举与 seal 提交实现：util/git/client.go
• 相关单元测试：util/git/gpg_verification_test.go、pkg/apis/application/v1alpha1/source_integrity_test.go
• CLI 管理命令：cmd/argocd/commands/project_source_integrity.go
• E2E 测试：test/e2e/app_management_source_integrity_test.go

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd