ogulcanaydogan/Verifiable-AI-Output-Ledger
GitHub: ogulcanaydogan/Verifiable-AI-Output-Ledger
为受监管行业提供密码学可验证的AI/LLM输出审计账本，解决AI决策来源、策略合规性和记录完整性的可证明问题。
Stars: 0 | Forks: 1
# VAOL — 可验证 AI 输出账本
**用于 AI/LLM 推理决策的密码学可验证、仅追加审计账本。**
为受监管行业提供防篡改审计追踪，帮助组织证明每个 AI 生成输出的来源、策略合规性和完整性。支持 DSSE 信封、RFC 6962 Merkle 树、OPA 策略即代码 以及多租户 JWT 认证。
[](https://github.com/ogulcanaydogan/Verifiable-AI-Output-Ledger/actions/workflows/ci.yml)
[](https://scorecard.dev/viewer/?uri=github.com/ogulcanaydogan/Verifiable-AI-Output-Ledger)
[](https://www.bestpractices.dev/projects/0000)
[](https://goreportcard.com/report/github.com/ogulcanaydogan/Verifiable-AI-Output-Ledger)
[](LICENSE)
[](go.mod)
[](sdk/python)
[](sdk/typescript)
## 为什么存在这个项目
受监管行业（医疗、金融、法律、政府）中的 AI 系统面临一个关键挑战：**如何证明 AI 系统实际说了什么、何时说的、在什么策略下说的，以及记录未被篡改？**
当前的方法是不够的：
- 应用程序日志可以被修改或删除
- 数据库记录缺乏密码学完整性保证
- 没有标准化的方法来证明推理时的策略合规性
- 审计人员无法独立验证 AI 决策来源
VAOL 通过提供一个**密码学审计账本**解决了这个问题，它：
- 通过数字签名和哈希链创建每次 AI 推理的**防篡改记录**
- 通过 OPA/Rego 在决策时评估，强制执行**策略即代码**
- 使用 RFC 6962 Merkle 树提供审计人员可独立验证的**可验证证明**
- 支持**隐私保护模式** —— 根据策略仅存储哈希、加密内容或明文
- 实现**零信任验证** —— 客户端无需信任服务器即可验证签名和证明
该项目面向需要为监管、法律或企业要求构建具备可验证治理的 AI 系统的合规团队、审计人员和工程师。
## 工作原理
```
graph LR
A[Application] --> B[VAOL SDK/Proxy]
B --> C[LLM Provider]
B --> D[VAOL Server]
D --> E[Policy Engine
OPA/Rego] D --> F[Signer
Ed25519/Sigstore/KMS] D --> G[Merkle Log
RFC 6962] D --> H[Ledger Store
PostgreSQL] G --> I[Auditor
CLI Verifier] H --> I style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#7B68EE,stroke:#5B48CE,color:#fff style C fill:#50C878,stroke:#3AA862,color:#fff style D fill:#F5A623,stroke:#C7851A,color:#fff style E fill:#FF6B6B,stroke:#CC4444,color:#fff style F fill:#FF8C42,stroke:#CC6A2E,color:#fff style G fill:#4ECDC4,stroke:#36B5AC,color:#fff style H fill:#9B59B6,stroke:#7D3C98,color:#fff style I fill:#2ECC71,stroke:#27AE60,color:#fff ``` 每次您的应用程序调用 LLM 时，VAOL 都会捕获一个包含以下内容的 **DecisionRecord**： | 字段 | 描述 | |-------|-------------| | **Identity** | 发起请求的租户、用户、服务 | | **Model** | 提供商、名称、版本、端点 | | **Prompt** | 密码学哈希（默认情况下从不存储原始内容） | | **Policy** | OPA bundle、决策结果、评估的规则 ID | | **RAG Context** | 文档 ID、分块哈希、引用 | | **Output** | 哈希，可选择加密或明文 | | **Proof** | 数字签名、哈希链链接、Merkle 包含证明 | 每条记录都经过**签名**（Ed25519、Sigstore 无密钥 或 KMS/HSM），**哈希链接**到其前一条记录，并锚定在具有可验证包含证明的 **RFC 6962 Merkle 树**中。 ## 验证层 ``` graph TD A[DecisionRecord] --> B{Layer 1
Signature} B -->|Valid| C{Layer 2
Schema} B -->|Invalid| X[REJECT] C -->|Valid| D{Layer 3
Hash Chain} C -->|Invalid| X D -->|Valid| E{Layer 4
Merkle Proof} D -->|Invalid| X E -->|Valid| F[VERIFIED ✓] E -->|Invalid| X style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#FF6B6B,stroke:#CC4444,color:#fff style C fill:#FF8C42,stroke:#CC6A2E,color:#fff style D fill:#F5A623,stroke:#C7851A,color:#fff style E fill:#7B68EE,stroke:#5B48CE,color:#fff style F fill:#2ECC71,stroke:#27AE60,color:#fff style X fill:#E74C3C,stroke:#C0392B,color:#fff ``` | 层级 | 验证内容 | 目的 | |-------|-------------|---------| | **1. Signature** | DSSE 信封签名有效 (Ed25519/Sigstore/KMS) | 证明记录真实性 | | **2. Key Revocation** | 签名 keyid 在签名时间戳时未被撤销（当配置了撤销列表时） | 检测受损的签名身份 | | **3. Schema** | DecisionRecord 符合 v1 JSON Schema | 确保结构完整性 | | **4. Hash Chain** | `previous_record_hash` 与前一条记录匹配 | 检测插入/删除 | | **5. Merkle Inclusion** | 包含证明对树根有效 | 实现全局一致性审计 | `vaol verify` CLI 命令和 `/v1/verify` API 执行这些检查，当提供撤销列表时，会启用密钥撤销强制执行。 ## 隐私模式 ``` graph LR subgraph Modes ["Privacy Mode Selection"] A[hash_only
Maximum Privacy] B[encrypted
Recoverable] C[plaintext
Full Audit] end A --> D[SHA-256
Digest Only] B --> E[age X25519
Encrypted + Digest] C --> F[Raw Content
Policy-Gated] style A fill:#2ECC71,stroke:#27AE60,color:#fff style B fill:#F5A623,stroke:#C7851A,color:#fff style C fill:#E74C3C,stroke:#C0392B,color:#fff style D fill:#4ECDC4,stroke:#36B5AC,color:#fff style E fill:#4ECDC4,stroke:#36B5AC,color:#fff style F fill:#4ECDC4,stroke:#36B5AC,color:#fff ``` | 模式 | 存储内容 | 用例 | |------|--------------|----------| | `hash_only` (默认) | 仅 SHA-256 摘要 | 最大隐私；在不暴露内容的情况下证明完整性 | | `encrypted` | age X25519 加密数据块 + 摘要 | 内容可通过密钥恢复；摘要绑定防止交换 | | `plaintext` | 原始文本（策略门控） | 内部审计的完整内容；需要明确的策略允许 | ## 快速开始 ### Docker Compose ``` # 启动 VAOL server + PostgreSQL + OPA docker compose -f deploy/docker/docker-compose.yml up -d # 检查健康状态 curl http://localhost:8080/v1/health # 可选：运行 mandatory-citations policy VAOL_OPA_POLICY=v1/data/vaol/mandatory_citations \ docker compose -f deploy/docker/docker-compose.yml up -d ``` ### 从源码构建 ``` make build # 使用内存存储运行 server（开发环境） ./bin/vaol-server --addr :8080 --auth-mode disabled --policy-mode allow-all # 可选：在第二个监听器上启用 gRPC API ./bin/vaol-server --addr :8080 --grpc-addr :9090 --auth-mode disabled --policy-mode allow-all # 使用 PostgreSQL 运行 server ./bin/vaol-server --addr :8080 --dsn "postgres://vaol:vaol@localhost:5432/vaol" # 使用 signer backends 运行 ./bin/vaol-server --signer-mode ed25519 --key ~/.vaol/keys/vaol-signing.pem ./bin/vaol-server --signer-mode sigstore --sigstore-rekor-required ./bin/vaol-server --signer-mode kms --kms-provider aws-kms --kms-key-uri arn:aws:kms:... # 可选的大规模 append event 发布到 Kafka ./bin/vaol-server \ --ingest-mode kafka \ --ingest-kafka-brokers kafka-1:9092,kafka-2:9092 \ --ingest-kafka-topic vaol.decision-records \ --ingest-kafka-client-id vaol-server \ --ingest-kafka-required # 强制启动 anchor 连续性验证（生产加固） ./bin/vaol-server --anchor-mode local --anchor-continuity-required # 对 /v1/verify 和 /v1/verify/bundle 强制执行 verifier key 吊销 ./bin/vaol-server --verify-revocations-file /etc/vaol/revocations.json # 由 Kafka append events 驱动的异步大规模 Merkle/checkpoint worker ./bin/vaol-ingest-worker \ --kafka-brokers kafka-1:9092,kafka-2:9092 \ --kafka-topic vaol.decision-records \ --kafka-group-id vaol-ingest-worker \ --checkpoint-topic vaol.tenant-checkpoints \ --anchor-mode local \ --checkpoint-every 100 ``` ### Python SDK ``` pip install vaol ``` ``` from openai import OpenAI import vaol client = OpenAI() vaol_client = vaol.VAOLClient("http://localhost:8080") # Instrument：每次 LLM 调用现在都会发出 DecisionRecord wrapped = vaol.instrument_openai(client, vaol_client, tenant_id="my-org") response = wrapped.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Summarize this patient report."}], ) # DecisionRecord 自动随 prompt hash、 # output hash、model identity 和 policy context 发出。 # Anthropic 和 LiteLLM wrappers 也可用： # vaol.instrument_anthropic(anthropic_client, vaol_client, tenant_id="my-org") # vaol.instrument_litellm(vaol_client, tenant_id="my-org") ``` ### TypeScript SDK ``` npm install @vaol/sdk ``` ``` import OpenAI from "openai"; import { VAOLClient, instrumentOpenAI } from "@vaol/sdk"; const openai = new OpenAI(); const vaol = new VAOLClient({ baseURL: "http://localhost:8080" }); // Instrument: every LLM call now emits a DecisionRecord instrumentOpenAI(openai, { client: vaol, tenantID: "my-org", subject: "my-service", }); const response = await openai.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "Summarize this patient report." }], }); // DecisionRecord automatically emitted to VAOL ``` ### 客户端验证 两个 SDK 都支持无需信任服务器的离线验证： **Python:** ``` from vaol import verify_dsse_ed25519, verify_inclusion_proof sig_result = verify_dsse_ed25519(envelope, public_key_bytes) proof_result = verify_inclusion_proof(leaf_data, leaf_index, tree_size, hashes, root) ``` **TypeScript:** ``` import { verifyDSSEEd25519, verifyInclusionProof } from "@vaol/sdk"; const sigResult = verifyDSSEEd25519(envelope, publicKey); const proofResult = verifyInclusionProof(leafData, leafIndex, treeSize, hashes, root); ``` ## 架构 ``` graph TB subgraph Clients ["Client Integration"] SDK_PY[Python SDK] SDK_TS[TypeScript SDK] PROXY[OpenAI Proxy] CLI[CLI Tool] end subgraph Server ["VAOL Server — Go"] API[REST API] AUTH[JWT/OIDC Auth] POLICY[OPA Policy Engine] SIGNER[Signer
Ed25519 · Sigstore · KMS] MERKLE[Merkle Log
RFC 6962] EXPORT[Evidence Exporter] end subgraph Storage ["Data Layer"] PG[(PostgreSQL)] MEM[(In-Memory
Dev Only)] end SDK_PY --> API SDK_TS --> API PROXY --> API CLI --> API API --> AUTH AUTH --> POLICY POLICY --> SIGNER SIGNER --> MERKLE MERKLE --> PG MERKLE --> MEM EXPORT --> PG style Clients fill:#1a1a2e,stroke:#4A90D9,color:#fff style Server fill:#1a1a2e,stroke:#50C878,color:#fff style Storage fill:#1a1a2e,stroke:#F5A623,color:#fff style API fill:#4A90D9,stroke:#2C5F8A,color:#fff style AUTH fill:#7B68EE,stroke:#5B48CE,color:#fff style POLICY fill:#FF6B6B,stroke:#CC4444,color:#fff style SIGNER fill:#FF8C42,stroke:#CC6A2E,color:#fff style MERKLE fill:#4ECDC4,stroke:#36B5AC,color:#fff style EXPORT fill:#9B59B6,stroke:#7D3C98,color:#fff style PG fill:#336791,stroke:#254E6C,color:#fff style MEM fill:#95A5A6,stroke:#7F8C8D,color:#fff ``` ## 策略引擎 VAOL 使用 OPA/Rego 进行运行时策略评估，采用**失败即关闭 (fail-closed)** 默认设置： ``` graph LR A[Request] --> B{OPA
Configured?} B -->|Yes| C{Policy
Evaluation} B -->|No| D[DENY
missing_policy_engine] C -->|Allow| E[Proceed] C -->|Deny| F[DENY
policy_violation] C -->|Error| G[DENY
policy_error] style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#F5A623,stroke:#C7851A,color:#fff style C fill:#7B68EE,stroke:#5B48CE,color:#fff style D fill:#E74C3C,stroke:#C0392B,color:#fff style E fill:#2ECC71,stroke:#27AE60,color:#fff style F fill:#E74C3C,stroke:#C0392B,color:#fff style G fill:#E74C3C,stroke:#C0392B,color:#fff ``` **内置策略：** | 策略 | 目的 | |--------|---------| | `base.rego` | 必填字段验证 | | `deny_plaintext.rego` | 防止明文输出存储 | | `model_allowlist.rego` | 仅允许已批准的模型 | | `phi_redaction.rego` | 医疗租户必须进行 PHI/PII 脱敏 | | `mandatory_citations.rego` | RAG 输出必须包含引用 | 仅用于本地开发时，使用 `--policy-mode allow-all`。 ## CLI ``` # 初始化 VAOL config ./bin/vaol init # 生成 signing keys ./bin/vaol keys generate # 写入：~/.vaol/keys/vaol-signing.pem (private) # 写入：~/.vaol/keys/vaol-signing.pub (public) # 验证 audit bundle ./bin/vaol verify bundle audit-bundle.json \ --public-key ~/.vaol/keys/vaol-signing.pub \ --revocations-file ./revocations.json \ --transcript-json verification-transcript.json \ --report-markdown verification-report.md # 验证单个 DSSE record 并强制执行 key revocation ./bin/vaol verify record record.json \ --public-key ~/.vaol/keys/vaol-signing.pub \ --revocations-file ./revocations.json # Revocation list 格式示例 cat > revocations.json <<'JSON' { "version": "v1", "generated_at": "2026-02-23T00:00:00Z", "revocations": [ { "keyid": "ed25519:abc123...", "effective_at": "2026-02-01T00:00:00Z", "reason": "compromised" } ] } JSON # 检查 DSSE envelope ./bin/vaol inspect record.json ``` ### 审计员演示 ``` ./scripts/demo_auditor.sh ``` 在 `tmp/demo-auditor//` 下创建可复现的证据包。完整演练请参阅 `docs/demo-auditor-storyline.md`。
### OpenAI 兼容代理
```
# 启动 transparent proxy
./bin/vaol-proxy --upstream https://api.openai.com --vaol-server http://localhost:8080
# 将您的应用指向 proxy
export OPENAI_BASE_URL=http://localhost:8443/v1
# 所有请求现在自动记录到 VAOL
```
## API 参考
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/v1/records` | 追加 DecisionRecord |
| `GET` | `/v1/records/{id}` | 检索记录 |
| `GET` | `/v1/records` | 列出记录（带过滤器） |
| `GET` | `/v1/records/{id}/proof` | 获取 Merkle 包含证明 |
| `GET` | `/v1/proofs/{id}` | 通过证明 ID 获取包含证明 |
| `POST` | `/v1/verify` | 验证 DSSE 信封（`profile` 查询参数或 `verification_profile` 请求体） |
| `POST` | `/v1/verify/record` | 验证记录 (`basic\|strict\|fips`) |
| `POST` | `/v1/verify/bundle` | 验证审计包（`profile` 查询参数或 `verification_profile` 请求体） |
| `GET` | `/v1/ledger/checkpoint` | 获取最新的 Merkle 检查点 |
| `GET` | `/v1/ledger/checkpoints/latest` | 最新签名检查点的别名 |
| `GET` | `/v1/ledger/consistency` | 获取一致性证明 (`from`,`to`) |
| `POST` | `/v1/export` | 导出审计包 |
| `GET` | `/v1/health` | 健康检查 |
当启用 `--grpc-addr` 时，也可以通过 `VAOLLedger` 使用 gRPC API。请参阅 `proto/vaol/v1/ledger.proto`。
## 认证
| 模式 | 描述 |
|------|-------------|
| `disabled` | 无 JWT 验证（仅限本地开发） |
| `optional` | 如果提供 JWT 则进行验证 |
| `required` (默认) | 需要有效的 JWT 并绑定租户/主体声明 |
支持的算法：`HS256`, `RS256`, `ES256`，密钥材料来自 `--jwks-file`, `--jwks-url`, 或 `--jwt-hs256-secret`。
### 租户绑定访问
租户范围的 API 需要标头：
- `X-VAOL-Tenant-ID`（首选），或
- `X-Tenant-ID`
跨租户访问将被拒绝，并返回确定性的拒绝原因代码。
## 项目结构
```
vaol/
├── cmd/
│ ├── vaol-server/ # Ledger server
│ ├── vaol-cli/ # CLI tool
│ └── vaol-proxy/ # OpenAI-compatible proxy
├── pkg/
│ ├── record/ # DecisionRecord types + JCS canonicalization
│ ├── signer/ # DSSE envelopes, Ed25519, Sigstore, KMS
│ ├── merkle/ # RFC 6962 Merkle tree + proofs
│ ├── store/ # PostgreSQL + in-memory backends
│ ├── policy/ # OPA engine + fail-closed wrapper
│ ├── auth/ # JWT/OIDC verification + tenant binding
│ ├── verifier/ # Composite verification
│ ├── export/ # Audit bundle creation
│ ├── crypto/ # SHA-256, age encryption
│ ├── api/ # REST API server
│ └── grpc/ # gRPC API server
├── sdk/
│ ├── python/ # Python SDK with OpenAI/Anthropic/LiteLLM instrumentation
│ └── typescript/ # TypeScript SDK with OpenAI instrumentation
├── policies/ # OPA/Rego example policies
├── schemas/v1/ # JSON Schema for DecisionRecord
├── deploy/
│ ├── docker/ # Docker Compose
│ └── helm/ # Kubernetes Helm charts
├── scripts/ # Demo and operational scripts
├── docs/ # Architecture, API, deployment guides
└── tests/ # E2E + tamper detection tests
```
## 文档
- [架构](docs/architecture.md)
- [API 参考](docs/api-reference.md)
- [密码学设计](docs/crypto-design.md)
- [威胁模型](docs/threat-model.md)
- [审计员指南](docs/auditor-guide.md)
- [部署指南](docs/deployment-production-profile.md)
- [HA 排序模型](docs/ha-sequencing-model.md)
- [灾难恢复手册](docs/dr-playbook.md)
- [多区域参考](docs/multi-region-reference.md)
- [合规运营基线](docs/compliance-operations.md)
- [v1 兼容性契约](docs/v1-compatibility-contract.md)
- [外部审计准备包](docs/external-audit-readiness.md)
- [审计 RFP 简表模板](docs/audit/rfp-shortlist.md)
- [审计 SOW 模板](docs/audit/sow.md)
- [审计控制矩阵](docs/audit/control-matrix.md)
- [公开整改报告模板](docs/audit/remediation-report-template.md)
- [发布 Runbook](docs/releases/release-runbook.md)
- [更新日志](CHANGELOG.md)
- [示例](examples/)
## 技术栈
| 层级 | 技术 | 用途 |
|-------|-----------|---------|
| **Server** | Go 1.24+ | 高性能账本服务器 |
| **Storage** | PostgreSQL 15 | 持久化记录和证明存储 |
| **Policy** | OPA/Rego | 运行时策略评估 |
| **Cryptography** | Ed25519, Sigstore, age | 签名和加密 |
| **Auth** | JWT/OIDC | 多租户认证 |
| **SDKs** | Python 3.10+, TypeScript 5.0+ | 客户端集成 |
| **Infrastructure** | Docker, Kubernetes (Helm) | 部署目标 |
## 许可证
Apache License 2.0 — 详见 [LICENSE](LICENSE)。
OPA/Rego] D --> F[Signer
Ed25519/Sigstore/KMS] D --> G[Merkle Log
RFC 6962] D --> H[Ledger Store
PostgreSQL] G --> I[Auditor
CLI Verifier] H --> I style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#7B68EE,stroke:#5B48CE,color:#fff style C fill:#50C878,stroke:#3AA862,color:#fff style D fill:#F5A623,stroke:#C7851A,color:#fff style E fill:#FF6B6B,stroke:#CC4444,color:#fff style F fill:#FF8C42,stroke:#CC6A2E,color:#fff style G fill:#4ECDC4,stroke:#36B5AC,color:#fff style H fill:#9B59B6,stroke:#7D3C98,color:#fff style I fill:#2ECC71,stroke:#27AE60,color:#fff ``` 每次您的应用程序调用 LLM 时，VAOL 都会捕获一个包含以下内容的 **DecisionRecord**： | 字段 | 描述 | |-------|-------------| | **Identity** | 发起请求的租户、用户、服务 | | **Model** | 提供商、名称、版本、端点 | | **Prompt** | 密码学哈希（默认情况下从不存储原始内容） | | **Policy** | OPA bundle、决策结果、评估的规则 ID | | **RAG Context** | 文档 ID、分块哈希、引用 | | **Output** | 哈希，可选择加密或明文 | | **Proof** | 数字签名、哈希链链接、Merkle 包含证明 | 每条记录都经过**签名**（Ed25519、Sigstore 无密钥 或 KMS/HSM），**哈希链接**到其前一条记录，并锚定在具有可验证包含证明的 **RFC 6962 Merkle 树**中。 ## 验证层 ``` graph TD A[DecisionRecord] --> B{Layer 1
Signature} B -->|Valid| C{Layer 2
Schema} B -->|Invalid| X[REJECT] C -->|Valid| D{Layer 3
Hash Chain} C -->|Invalid| X D -->|Valid| E{Layer 4
Merkle Proof} D -->|Invalid| X E -->|Valid| F[VERIFIED ✓] E -->|Invalid| X style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#FF6B6B,stroke:#CC4444,color:#fff style C fill:#FF8C42,stroke:#CC6A2E,color:#fff style D fill:#F5A623,stroke:#C7851A,color:#fff style E fill:#7B68EE,stroke:#5B48CE,color:#fff style F fill:#2ECC71,stroke:#27AE60,color:#fff style X fill:#E74C3C,stroke:#C0392B,color:#fff ``` | 层级 | 验证内容 | 目的 | |-------|-------------|---------| | **1. Signature** | DSSE 信封签名有效 (Ed25519/Sigstore/KMS) | 证明记录真实性 | | **2. Key Revocation** | 签名 keyid 在签名时间戳时未被撤销（当配置了撤销列表时） | 检测受损的签名身份 | | **3. Schema** | DecisionRecord 符合 v1 JSON Schema | 确保结构完整性 | | **4. Hash Chain** | `previous_record_hash` 与前一条记录匹配 | 检测插入/删除 | | **5. Merkle Inclusion** | 包含证明对树根有效 | 实现全局一致性审计 | `vaol verify` CLI 命令和 `/v1/verify` API 执行这些检查，当提供撤销列表时，会启用密钥撤销强制执行。 ## 隐私模式 ``` graph LR subgraph Modes ["Privacy Mode Selection"] A[hash_only
Maximum Privacy] B[encrypted
Recoverable] C[plaintext
Full Audit] end A --> D[SHA-256
Digest Only] B --> E[age X25519
Encrypted + Digest] C --> F[Raw Content
Policy-Gated] style A fill:#2ECC71,stroke:#27AE60,color:#fff style B fill:#F5A623,stroke:#C7851A,color:#fff style C fill:#E74C3C,stroke:#C0392B,color:#fff style D fill:#4ECDC4,stroke:#36B5AC,color:#fff style E fill:#4ECDC4,stroke:#36B5AC,color:#fff style F fill:#4ECDC4,stroke:#36B5AC,color:#fff ``` | 模式 | 存储内容 | 用例 | |------|--------------|----------| | `hash_only` (默认) | 仅 SHA-256 摘要 | 最大隐私；在不暴露内容的情况下证明完整性 | | `encrypted` | age X25519 加密数据块 + 摘要 | 内容可通过密钥恢复；摘要绑定防止交换 | | `plaintext` | 原始文本（策略门控） | 内部审计的完整内容；需要明确的策略允许 | ## 快速开始 ### Docker Compose ``` # 启动 VAOL server + PostgreSQL + OPA docker compose -f deploy/docker/docker-compose.yml up -d # 检查健康状态 curl http://localhost:8080/v1/health # 可选：运行 mandatory-citations policy VAOL_OPA_POLICY=v1/data/vaol/mandatory_citations \ docker compose -f deploy/docker/docker-compose.yml up -d ``` ### 从源码构建 ``` make build # 使用内存存储运行 server（开发环境） ./bin/vaol-server --addr :8080 --auth-mode disabled --policy-mode allow-all # 可选：在第二个监听器上启用 gRPC API ./bin/vaol-server --addr :8080 --grpc-addr :9090 --auth-mode disabled --policy-mode allow-all # 使用 PostgreSQL 运行 server ./bin/vaol-server --addr :8080 --dsn "postgres://vaol:vaol@localhost:5432/vaol" # 使用 signer backends 运行 ./bin/vaol-server --signer-mode ed25519 --key ~/.vaol/keys/vaol-signing.pem ./bin/vaol-server --signer-mode sigstore --sigstore-rekor-required ./bin/vaol-server --signer-mode kms --kms-provider aws-kms --kms-key-uri arn:aws:kms:... # 可选的大规模 append event 发布到 Kafka ./bin/vaol-server \ --ingest-mode kafka \ --ingest-kafka-brokers kafka-1:9092,kafka-2:9092 \ --ingest-kafka-topic vaol.decision-records \ --ingest-kafka-client-id vaol-server \ --ingest-kafka-required # 强制启动 anchor 连续性验证（生产加固） ./bin/vaol-server --anchor-mode local --anchor-continuity-required # 对 /v1/verify 和 /v1/verify/bundle 强制执行 verifier key 吊销 ./bin/vaol-server --verify-revocations-file /etc/vaol/revocations.json # 由 Kafka append events 驱动的异步大规模 Merkle/checkpoint worker ./bin/vaol-ingest-worker \ --kafka-brokers kafka-1:9092,kafka-2:9092 \ --kafka-topic vaol.decision-records \ --kafka-group-id vaol-ingest-worker \ --checkpoint-topic vaol.tenant-checkpoints \ --anchor-mode local \ --checkpoint-every 100 ``` ### Python SDK ``` pip install vaol ``` ``` from openai import OpenAI import vaol client = OpenAI() vaol_client = vaol.VAOLClient("http://localhost:8080") # Instrument：每次 LLM 调用现在都会发出 DecisionRecord wrapped = vaol.instrument_openai(client, vaol_client, tenant_id="my-org") response = wrapped.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Summarize this patient report."}], ) # DecisionRecord 自动随 prompt hash、 # output hash、model identity 和 policy context 发出。 # Anthropic 和 LiteLLM wrappers 也可用： # vaol.instrument_anthropic(anthropic_client, vaol_client, tenant_id="my-org") # vaol.instrument_litellm(vaol_client, tenant_id="my-org") ``` ### TypeScript SDK ``` npm install @vaol/sdk ``` ``` import OpenAI from "openai"; import { VAOLClient, instrumentOpenAI } from "@vaol/sdk"; const openai = new OpenAI(); const vaol = new VAOLClient({ baseURL: "http://localhost:8080" }); // Instrument: every LLM call now emits a DecisionRecord instrumentOpenAI(openai, { client: vaol, tenantID: "my-org", subject: "my-service", }); const response = await openai.chat.completions.create({ model: "gpt-4o", messages: [{ role: "user", content: "Summarize this patient report." }], }); // DecisionRecord automatically emitted to VAOL ``` ### 客户端验证 两个 SDK 都支持无需信任服务器的离线验证： **Python:** ``` from vaol import verify_dsse_ed25519, verify_inclusion_proof sig_result = verify_dsse_ed25519(envelope, public_key_bytes) proof_result = verify_inclusion_proof(leaf_data, leaf_index, tree_size, hashes, root) ``` **TypeScript:** ``` import { verifyDSSEEd25519, verifyInclusionProof } from "@vaol/sdk"; const sigResult = verifyDSSEEd25519(envelope, publicKey); const proofResult = verifyInclusionProof(leafData, leafIndex, treeSize, hashes, root); ``` ## 架构 ``` graph TB subgraph Clients ["Client Integration"] SDK_PY[Python SDK] SDK_TS[TypeScript SDK] PROXY[OpenAI Proxy] CLI[CLI Tool] end subgraph Server ["VAOL Server — Go"] API[REST API] AUTH[JWT/OIDC Auth] POLICY[OPA Policy Engine] SIGNER[Signer
Ed25519 · Sigstore · KMS] MERKLE[Merkle Log
RFC 6962] EXPORT[Evidence Exporter] end subgraph Storage ["Data Layer"] PG[(PostgreSQL)] MEM[(In-Memory
Dev Only)] end SDK_PY --> API SDK_TS --> API PROXY --> API CLI --> API API --> AUTH AUTH --> POLICY POLICY --> SIGNER SIGNER --> MERKLE MERKLE --> PG MERKLE --> MEM EXPORT --> PG style Clients fill:#1a1a2e,stroke:#4A90D9,color:#fff style Server fill:#1a1a2e,stroke:#50C878,color:#fff style Storage fill:#1a1a2e,stroke:#F5A623,color:#fff style API fill:#4A90D9,stroke:#2C5F8A,color:#fff style AUTH fill:#7B68EE,stroke:#5B48CE,color:#fff style POLICY fill:#FF6B6B,stroke:#CC4444,color:#fff style SIGNER fill:#FF8C42,stroke:#CC6A2E,color:#fff style MERKLE fill:#4ECDC4,stroke:#36B5AC,color:#fff style EXPORT fill:#9B59B6,stroke:#7D3C98,color:#fff style PG fill:#336791,stroke:#254E6C,color:#fff style MEM fill:#95A5A6,stroke:#7F8C8D,color:#fff ``` ## 策略引擎 VAOL 使用 OPA/Rego 进行运行时策略评估，采用**失败即关闭 (fail-closed)** 默认设置： ``` graph LR A[Request] --> B{OPA
Configured?} B -->|Yes| C{Policy
Evaluation} B -->|No| D[DENY
missing_policy_engine] C -->|Allow| E[Proceed] C -->|Deny| F[DENY
policy_violation] C -->|Error| G[DENY
policy_error] style A fill:#4A90D9,stroke:#2C5F8A,color:#fff style B fill:#F5A623,stroke:#C7851A,color:#fff style C fill:#7B68EE,stroke:#5B48CE,color:#fff style D fill:#E74C3C,stroke:#C0392B,color:#fff style E fill:#2ECC71,stroke:#27AE60,color:#fff style F fill:#E74C3C,stroke:#C0392B,color:#fff style G fill:#E74C3C,stroke:#C0392B,color:#fff ``` **内置策略：** | 策略 | 目的 | |--------|---------| | `base.rego` | 必填字段验证 | | `deny_plaintext.rego` | 防止明文输出存储 | | `model_allowlist.rego` | 仅允许已批准的模型 | | `phi_redaction.rego` | 医疗租户必须进行 PHI/PII 脱敏 | | `mandatory_citations.rego` | RAG 输出必须包含引用 | 仅用于本地开发时，使用 `--policy-mode allow-all`。 ## CLI ``` # 初始化 VAOL config ./bin/vaol init # 生成 signing keys ./bin/vaol keys generate # 写入：~/.vaol/keys/vaol-signing.pem (private) # 写入：~/.vaol/keys/vaol-signing.pub (public) # 验证 audit bundle ./bin/vaol verify bundle audit-bundle.json \ --public-key ~/.vaol/keys/vaol-signing.pub \ --revocations-file ./revocations.json \ --transcript-json verification-transcript.json \ --report-markdown verification-report.md # 验证单个 DSSE record 并强制执行 key revocation ./bin/vaol verify record record.json \ --public-key ~/.vaol/keys/vaol-signing.pub \ --revocations-file ./revocations.json # Revocation list 格式示例 cat > revocations.json <<'JSON' { "version": "v1", "generated_at": "2026-02-23T00:00:00Z", "revocations": [ { "keyid": "ed25519:abc123...", "effective_at": "2026-02-01T00:00:00Z", "reason": "compromised" } ] } JSON # 检查 DSSE envelope ./bin/vaol inspect record.json ``` ### 审计员演示 ``` ./scripts/demo_auditor.sh ``` 在 `tmp/demo-auditor/
标签：DSSE封装, EVTX分析, Go语言服务器, LLM审计日志, Merkle Tree证明, OPA策略即代码, Python SDK, RFC 6962, TypeScript SDK, Zenmap, 人工智能审计, 可验证AI输出, 合规科技, 多租户JWT认证, 大语言模型安全, 子域名突变, 审计追踪, 密码学验证, 数据完整性, 日志审计, 机密管理, 测试用例, 溯源, 监管科技, 请求拦截, 软件供应链安全, 远程方法调用, 逆向工具, 防篡改账本