ogulcanaydogan/LLM-Supply-Chain-Attestation
GitHub: ogulcanaydogan/LLM-Supply-Chain-Attestation
一款面向大模型生命周期的密码学证明框架，通过 Sigstore 签名与 Kubernetes 准入控制，确保 Prompt、语料及路由配置的供应链完整性与防篡改验证。
Stars: 0 | Forks: 1
# LLM 供应链证明 (`llmsa`)
**一个将软件供应链安全引入大语言模型生命周期的密码学证明框架，提供类型化的 LLM 制品来源、策略执行和部署时准入检查。**
[](https://github.com/ogulcanaydogan/LLM-Supply-Chain-Attestation/actions/workflows/ci-attest-verify.yml)
## 问题背景
现有的软件供应链框架（SLSA, in-toto, SBOM）保护传统的构建制品 —— 容器镜像、二进制文件、软件包 —— 但**完全忽略了定义 LLM 系统行为的 AI 特定组件**。Prompt、训练语料库、评估基准、路由配置和延迟预算在通过 CI/CD 流水线时没有经过完整性验证、来源追踪和策略执行。
这造成了关键的盲点：
- **系统 Prompt** 可能在生产环境中被静默修改，从而改变模型行为且不留下任何审计痕迹。
- **训练数据** 可能在准备和部署之间被投毒，且无法检测篡改。
- **评估结果** 可能被伪造或从过时的运行中重放，以绕过质量关卡。
- **路由逻辑** 可能被更改，将流量重定向到更便宜、能力更弱的模型，而无需承担 SLO 责任。
随着 LLM 系统日益驱动医疗、金融和自动驾驶等安全关键型应用，AI 制品缺乏供应链完整性代表了一个现有的工具均未解决的系统性安全缺口。
## `llmsa` 的功能
`llmsa` 是一个本地优先的 CLI 和 CI 工具链，用于生成、签名、发布、验证和执行针对五类 LLM 制品的**类型化密码学证明**：
| 证明类型 | 涵盖制品 | 证明内容 |
|---|---|---|
| **Prompt** | 系统 Prompt、模板、工具 Schema、安全策略 | 部署的确切 Prompt 与审查批准的内容一致 |
| **Corpus** | 训练数据、RAG 文档、Embedding、向量索引 | 从准备到索引的数据血缘完整无损 |
| **Eval** | 测试套件、基准结果、评分配置、基线 | 模型质量已针对特定的 Prompt+Corpus 版本进行了验证 |
| **Route** | 路由表、回退图、金丝雀配置、预算策略 | 流量路由逻辑与经过测试和批准的配置一致 |
| **SLO** | 延迟目标、成本预算、准确率阈值、查询配置文件 | 运维约束是基于已验证的路由设置定义的 |
每个证明通过签名的 [DSSE (Dead Simple Signing Envelope)](https://github.com/secure-systems-lab/dsse) 将文件摘要与元数据进行密码学绑定，从而创建一条从开发到部署的不可伪造的证据链。
## 一句话定位
`llmsa` 通过在一个操作边界下结合四项控制措施来保护 LLM 交付：
1. 针对 prompt/corpus/eval/route/SLO 变更的 **LLM 特定分类法**。
2. **来源链验证**，使下游决策受限于上游证据。
3. 在 CI 中针对缺失或无效证据实施拒绝的 **策略执行**。
4. 在 Kubernetes 中进行部署时验证的 **失败即闭环准入执行**。
## 关键技术贡献
### 1. LLM 特定的证明分类法
与通用的制品证明工具不同，`llmsa` 为 LLM 制品引入了**领域特定的类型系统**。每种证明类型都有专门的收集器，这些收集器理解 Prompt、语料库、评估、路由配置和 SLO 定义的语义结构 —— 提取正确的摘要和元数据，而不是将所有内容视为不透明的数据块。
### 2. 来源链验证
`llmsa` 在证明类型之间执行**有向无环依赖图**，确保逻辑顺序和引用完整性：
```
graph LR
PA["🔤 Prompt\nAttestation"] --> EA["📊 Eval\nAttestation"]
CA["📚 Corpus\nAttestation"] --> EA
EA --> RA["🔀 Route\nAttestation"]
RA --> SA["⚡ SLO\nAttestation"]
style PA fill:#4A90D9,color:#fff,stroke:#2E6BA6
style CA fill:#4A90D9,color:#fff,stroke:#2E6BA6
style EA fill:#7B68EE,color:#fff,stroke:#5A4FCF
style RA fill:#E8833A,color:#fff,stroke:#C06A2B
style SA fill:#50C878,color:#fff,stroke:#3BA55D
```
链验证器检查：
- **基于类型的依赖**：Eval 证明*必须*同时引用 Prompt 和 Corpus 证明。
- **基于 ID 的引用**：显式的 `depends_on` 注解连接图中特定的语句 ID。
- **时序排序**：前置证明必须在其后继者之前生成。
- **未知引用检测**：悬空的依赖引用被标记为违规。
这确保了没有任何证明可以孤立存在 —— 关于模型质量的每个声明都绑定到其测试所针对的确切制品（Prompt + Corpus），并且每个部署决策都追溯到经过验证的评估。
### 3. 隐私保护的证明模式
LLM 制品通常包含敏感的知识产权（专有 Prompt、机密训练数据）。`llmsa` 提供三种隐私模式：
```
flowchart TD
Start["Privacy Mode\nSelection"] --> Q1{"Contains\nSensitive IP?"}
Q1 -->|No| HO["hash_only\n(Default)"]
Q1 -->|Yes| Q2{"Content Recovery\nRequired?"}
Q2 -->|No| HO
Q2 -->|Yes| Q3{"Authorised\nRecipient?"}
Q3 -->|Yes| EP["encrypted_payload\n(Age X25519)"]
Q3 -->|No - Audit Only| PE["plaintext_explicit\n(Policy-Gated)"]
HO --> D1["SHA-256 digests only\nNo payload stored"]
EP --> D2["Encrypted blob\nDeterministic digest binding"]
PE --> D3["Full payload embedded\nBlocked unless allowlisted"]
style HO fill:#28A745,color:#fff
style EP fill:#FFC107,color:#000
style PE fill:#DC3545,color:#fff
```
| 模式 | 行为 | 用例 |
|---|---|---|
| `hash_only` | 仅存储 SHA-256 摘要；语句中无负载 | 默认模式 —— 在不暴露内容的情况下证明完整性 |
| `plaintext_explicit` | 嵌入完整负载（除非加入白名单，否则被策略阻止） | 需要内容审查的审计场景 |
| `encrypted_payload` | Age (X25519) 加密的 Blob，带有确定性摘要绑定 | 内容必须可由授权方恢复的合规工作流 |
`encrypted_payload` 模式使用 [age](https://age-encryption.org/) 加密及一种新颖的确定性摘要绑定方案：摘要是通过拼接接收者公钥和源字节来计算的，确保加密 Blob 在密码学上同时绑定到内容和预期接收者。
### 4. 双策略引擎
策略执行支持两种引擎，以平衡简单性和表达能力：
- **YAML Gate**：声明式的基于路径的触发器（`trigger_paths`），要求特定的证明类型。覆盖约 90% 的 CI/CD 用例，学习成本为零。
- **Rego (OPA) 引擎**：完整的 Open Policy Agent 集成，用于高级的跨语句分析 —— 隐私保护、自定义谓词、基于证明元数据的条件关卡。
两个引擎共享相同的输入契约，可以互换使用或组合使用。
### 5. 带 OIDC 身份绑定的 Sigstore Keyless 签名
生产签名使用 [Sigstore](https://www.sigstore.dev/) keyless 模式，配合来自 CI 提供商（GitHub Actions, GitLab CI）的 OIDC Token。这意味着：
- **无密钥管理**：无需轮换、存储或保护私钥。
- **身份绑定签名**：证明在密码学上绑定到生成它们的 CI 工作流身份（例如 `github.com/org/repo/.github/workflows/attest.yml@refs/heads/main`）。
- **OIDC 签发者验证**：验证器检查 Token 签发者是否与预期的提供商匹配。
- **PEM 后备**：用于本地开发和物理隔离环境的 Ed25519 密钥签名。
### 6. OCI 原生分发
签名的证明包作为一等制品发布到任何符合 OCI 规范的容器镜像仓库（GHCR, ECR, ACR, Docker Hub），并支持内容寻址的摘要固定。这实现了：
- 通过现有的容器基础设施进行全球分发。
- 通过 `registry/repo@sha256:...` 摘要 URI 进行不可变引用。
- 从任何具有镜像仓库访问权限的环境进行基于拉取的验证。
### 7. Kubernetes 准入执行
`llmsa webhook serve` 命令运行一个 **validating admission webhook**，拦截 Pod, Deployment, ReplicaSet, StatefulSet, DaemonSet 和 Job 的创建，从 OCI 镜像仓库拉取证明包，并在允许资源进入集群之前运行完整的四阶段验证流水线。
```
sequenceDiagram
participant Dev as Developer
participant K8s as K8s API Server
participant WH as llmsa Webhook
participant OCI as OCI Registry
participant VE as Verify Engine
Dev->>K8s: kubectl apply -f deployment.yaml
K8s->>WH: AdmissionReview (Pod spec)
WH->>WH: Extract image refs
loop For each container image
WH->>OCI: Pull attestation bundle
OCI-->>WH: DSSE bundle
WH->>VE: verify.Run(bundle)
VE-->>WH: Report (pass/fail)
end
alt All images verified
WH-->>K8s: Allowed
K8s-->>Dev: Pod created
else Verification failed
WH-->>K8s: Denied (with reason)
K8s-->>Dev: Error: attestation verification failed
end
```
### 8. 确定性验证
`--determinism-check N` 标志运行 N 次证明生成，并验证内容哈希是否匹配（排除运行时非确定性值，如时间戳和 UUID）。这可以在非确定性的收集器产生不可重现的证明之前捕获它们。
## 架构
```
flowchart TB
subgraph CLI["CLI (cmd/llmsa)"]
init["init"]
attest["attest create"]
sign_cmd["sign"]
publish["publish"]
verify_cmd["verify"]
gate["gate"]
report_cmd["report"]
wh["webhook serve"]
end
subgraph Collectors["Attestation Collectors"]
prompt["Prompt"]
corpus["Corpus"]
eval["Eval"]
route["Route"]
slo["SLO"]
privacy["Privacy Engine"]
end
subgraph Signing["DSSE Signing"]
sigstore["Sigstore Keyless"]
pem_sign["Ed25519 PEM"]
kms["KMS"]
end
subgraph Distribution["OCI Distribution"]
push["Publish"]
pull["Pull"]
registry[("OCI Registry\n(GHCR / ECR / ACR)")]
end
subgraph Verification["Verification Engine"]
sig_check["1. Signature"]
schema_check["2. Schema"]
digest_check["3. Digest"]
chain_check["4. Chain"]
end
subgraph Policy["Policy Engine"]
yaml_gate["YAML Gates"]
rego_gate["Rego / OPA"]
end
subgraph K8s["Kubernetes"]
webhook["Admission Webhook"]
apiserver["API Server"]
end
attest --> Collectors
Collectors --> privacy
privacy --> sign_cmd
sign_cmd --> Signing
Signing --> publish
publish --> push
push --> registry
registry --> pull
pull --> verify_cmd
verify_cmd --> Verification
Verification --> gate
gate --> Policy
apiserver --> webhook
webhook --> pull
webhook --> Verification
```
## 验证流水线
验证引擎执行四项独立检查，每项检查产生特定的退出代码：
```
flowchart LR
Bundle["DSSE\nBundle"] --> S1
subgraph Pipeline["Four-Stage Verification"]
S1["1. Signature\nVerify"]
S2["2. Schema\nValidate"]
S3["3. Digest\nRecompute"]
S4["4. Chain\nVerify"]
S1 -->|pass| S2
S2 -->|pass| S3
S3 -->|pass| S4
end
S1 -->|fail| F1["Exit 11\nSignature Fail"]
S2 -->|fail| F2["Exit 14\nSchema Fail"]
S3 -->|fail| F3["Exit 12\nTamper Detected"]
S4 -->|fail| F4["Exit 14\nChain Invalid"]
S4 -->|pass| OK["Exit 0\nAll Checks Passed ✓"]
style F1 fill:#DC3545,color:#fff
style F2 fill:#DC3545,color:#fff
style F3 fill:#DC3545,color:#fff
style F4 fill:#DC3545,color:#fff
style OK fill:#28A745,color:#fff
```
| 检查项 | 验证内容 | 失败退出代码 |
|---|---|---|
| **Signature** | DSSE 信封签名（针对公钥或 Sigstore 证书） | `11` |
| **Schema** | 语句结构（针对证明类型的 JSON Schema） | `14` |
| **Digest** | 重新计算的引用文件 SHA-256 与语句主体匹配 | `12` |
| **Chain** | 来源图满足依赖、排序和引用约束 | `14` |
## 篡改检测测试套件
`llmsa` 附带一个包含 20 个用例的综合篡改检测套件（`scripts/tamper-tests.sh`），在三个攻击面上验证安全保证：
**主体/材料字节变异 (T01–T10)**：对每种制品类型（系统 Prompt、模板、工具 Schema、安全策略、文档清单、分块配置、Embedding、测试集、路由配置、SLO 配置文件）进行单字节修改 —— 均通过摘要重计算检测到（退出代码 12）。
**签名/包篡改 (T11–T14)**：签名损坏、公钥替换、语句哈希篡改和签名移除 —— 均被 DSSE 验证捕获（退出代码 11）。
**Schema 和链完整性 (T15–T20)**：缺少必填谓词字段、无效时间戳、格式错误的摘要、不完整的依赖链和悬空引用 —— 均被 Schema 和链验证拒绝（退出代码 14）。
## 快速开始
```
# Build 和初始化
go build -o llmsa ./cmd/llmsa
./llmsa init
# 生成所有五种 attestation 类型
./llmsa attest create --type prompt_attestation --config examples/tiny-rag/configs/prompt.yaml --out .llmsa/attestations
./llmsa attest create --type corpus_attestation --config examples/tiny-rag/configs/corpus.yaml --out .llmsa/attestations
./llmsa attest create --type eval_attestation --config examples/tiny-rag/configs/eval.yaml --out .llmsa/attestations
./llmsa attest create --type route_attestation --config examples/tiny-rag/configs/route.yaml --out .llmsa/attestations
./llmsa attest create --type slo_attestation --config examples/tiny-rag/configs/slo.yaml --out .llmsa/attestations
# 使用本地 PEM 密钥签名（开发）
for s in .llmsa/attestations/statement_*.json; do
./llmsa sign --in "$s" --provider pem --key .llmsa/dev_ed25519.pem --out .llmsa/attestations
done
# 验证签名、schemas、digests 和 provenance chain
./llmsa verify --source local --attestations .llmsa/attestations \
--policy policy/examples/mvp-gates.yaml --format json --out verify.json
# 针对变更文件执行 policy gates
./llmsa gate --policy policy/examples/mvp-gates.yaml \
--attestations .llmsa/attestations --git-ref HEAD~1
# 生成人类可读的审计报告
./llmsa report --in verify.json --out verify.md
```
## CI/CD 集成
包含的 GitHub Actions 工作流（`.github/workflows/ci-attest-verify.yml`）演示了生产级的集成：
```
flowchart LR
subgraph CI["GitHub Actions Pipeline"]
direction LR
T["Test\ngo test"] --> A["Attest\n5 types"]
A --> S["Sign\nSigstore OIDC"]
S --> P["Publish\nGHCR OCI"]
P --> V["Verify\nLocal + OCI"]
V --> G["Gate\nYAML + Rego"]
G --> R["Report\nJSON + MD"]
end
OIDC["GitHub OIDC\nToken"] -.-> S
GHCR[("GHCR\nRegistry")] <-.-> P
GHCR <-.-> V
style T fill:#6C757D,color:#fff
style A fill:#4A90D9,color:#fff
style S fill:#7B68EE,color:#fff
style P fill:#E8833A,color:#fff
style V fill:#28A745,color:#fff
style G fill:#DC3545,color:#fff
style R fill:#17A2B8,color:#fff
```
## CLI 参考
| 命令 | 描述 |
|---|---|
| `llmsa init` | 初始化项目配置、策略脚手架和本地开发密钥 |
| `llmsa attest create` | 生成类型化的证明语句 |
| `llmsa sign` | 将语句封装为签名的 DSSE 包 |
| `llmsa publish` | 将包推送到 OCI 镜像仓库 |
| `llmsa verify` | 验证签名、Schema、摘要和链 |
| `llmsa gate` | 执行策略关卡（违规时退出代码 13） |
| `llmsa report` | 将 JSON 验证输出转换为 Markdown |
| `llmsa webhook serve` | 启动 Kubernetes validating admission webhook 服务器 |
| `llmsa demo run` | 执行完整的端到端流水线 |
### 退出代码
| 代码 | 含义 |
|---|---|
| `0` | 所有检查通过 |
| `10` | 缺少证明或包 |
| `11` | 签名验证失败 |
| `12` | 主体摘要不匹配（检测到篡改） |
| `13` | 策略关卡违规 |
| `14` | Schema 或版本不兼容 |
## 技术栈
| 组件 | 技术 | 用途 |
|---|---|---|
| 语言 | Go 1.25 | 性能、单一二进制分发、强类型 |
| CLI 框架 | Cobra | 子命令路由、标志解析、帮助生成 |
| 签名（生产） | Sigstore | 无密钥 OIDC 签名和验证 |
| 签名（开发） | Ed25519 PEM | 本地离线签名 |
| 加密 | age (X25519) | 隐私保护的加密证明负载 |
| 策略（简单） | YAML Gate | 声明式路径触发策略执行 |
| 策略（高级） | Open Policy Agent | 基于 Rego 的跨语句策略评估 |
| Schema 验证 | gojsonschema | 对所有语句类型进行 JSON Schema 验证 |
| OCI 分发 | go-containerregistry | 向/从镜像仓库发布/拉取证明包 |
| 信封格式 | DSSE | 行业标准签名信封（兼容 in-toto） |
| 准入控制 | K8s Admission API v1 | 部署时证明执行 |
## 项目结构
```
cmd/llmsa/ CLI entry point and command definitions
internal/
├── attest/ Typed collectors (prompt, corpus, eval, route, slo) + privacy
├── sign/ DSSE bundle creation (sigstore, pem, kms providers)
├── verify/ Multi-stage verification engine + provenance chain validator
├── policy/
│ ├── yaml/ Declarative gate engine
│ └── rego/ OPA integration engine
├── store/ OCI registry publish/pull with digest pinning
├── hash/ Canonical JSON serialisation and tree hashing
├── report/ Markdown report generator
└── webhook/ Kubernetes validating admission webhook handler
pkg/types/ Shared type definitions (Statement, Privacy, etc.)
policy/examples/ Reference YAML and Rego policy files
examples/tiny-rag/ Complete working RAG system with all 5 attestation types
deploy/
├── webhook/ Kubernetes manifests (Deployment, Service, ValidatingWebhookConfiguration)
└── helm/ Helm chart for webhook deployment
test/e2e/ End-to-end integration tests
scripts/
├── benchmark.sh Performance benchmarks with reproducibility metrics
├── tamper-tests.sh 20-case security validation suite
└── public-footprint-snapshot.sh Public metrics snapshot for external evidence tracking
docs/
├── quickstart.md Step-by-step bootstrap guide
├── threat-model.md Threat coverage and mitigation analysis
├── policy-guide.md Gate model and privacy guard documentation
├── benchmark-methodology.md Benchmark design and limitations
├── k8s-admission.md Kubernetes validating webhook deployment guide
└── public-footprint/ 30-day external validation playbook and evidence templates
```
## 文档
- [快速开始指南](docs/quickstart.md) — 6 步引导并运行完整流水线。
- [威胁模型](docs/threat-model.md) — 攻击面、缓解措施和已知限制。
- [策略指南](docs/policy-guide.md) — Gate 配置、隐私保护和 Rego 集成。
- [基准方法论](
标签：AI安全, Chat Copilot, CI/CD安全, DNS 解析, EVTX分析, Go语言, in-toto, JSONLines, Kubernetes准入控制, Linux系统监控, Llama, LLM供应链安全, OCI分发, OPA策略, SBOM, Sigstore, SLSA, Webhook, 准入验证, 力导向图, 子域名突变, 完整性校验, 密码学证明, 提示词安全, 数据溯源, 文档安全, 无密钥签名, 日志审计, 模型安全, 硬件无关, 程序破解, 训练数据安全, 跌倒检测, 软件开发工具包, 软件物料清单, 防篡改, 零信任