AuditZK/zero-knowledge-aggregator

# Track Record Enclave Worker **用于机密交易数据聚合的可信计算基** [](LICENSE) []() []() []() ## 概述 本代码仓库包含 Track Record 平台数据聚合服务的**可信计算基**。它实现了一种零知识架构，用于在 AMD SEV-SNP 硬件隔离的安全区域内处理敏感交易数据。 **本代码仓库有两个用途：** 1. **主要开发仓库**：这是 Enclave Worker 代码积极开发的场所。所有 Enclave 功能都在此构建和测试。 2. **公开审计与验证**：发布代码旨在进行独立的安全审计和可复现构建验证。这使得审计人员能够验证生产二进制文件是否与经过审计的源代码匹配。 **有关开发说明**，请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。 ## 目录 - [安全模型](#security-model) - [架构](#architecture) - [可信计算基](#trusted-computing-base) - [威胁模型](#threat-model) - [审计流程](#audit-process) - [可复现构建](#reproducible-builds) - [API 规范](#api-specification) ## 安全模型 ### 信任假设 1. **硬件信任根**：AMD SEV-SNP 提供内存加密和认证 2. **数据库隔离**：PostgreSQL 用户 `enclave_user` 拥有对敏感表的独占访问权限 3. **网络隔离**：Enclave 不暴露于公共互联网，仅通过内部 gRPC 通信 4. **密码学原语**：用于凭证加密的 AES-256-GCM（符合 FIPS 140-2 标准） ### 安全保障 | 属性 | 保障 | 机制 | |----------|-----------|-----------| | **凭证机密性** | API 密钥绝不离开 Enclave 内存 | 硬件内存加密 (SEV-SNP) | | **交易隐私** | 单笔交易绝不被传输 | Enclave 边界内的数据聚合 | | **代码完整性** | 二进制文件与审计过的源码匹配 | 可复现构建 + 认证 | | **隔离性** | Hypervisor 无法访问内存 | AMD SEV-SNP VMPL 保护 | ### 非目标 - 针对时序侧信道攻击的防护（超出范围） - 针对硬件物理访问的防护 - 针对 AMD 固件受损的防护 ## 架构 ### 系统上下文 ``` ┌─────────────────────────────────────────────────────────────┐ │ API Gateway (Untrusted Zone) │ │ - HTTP REST API (public-facing) │ │ - Authentication, rate limiting │ │ - Access: aggregated data only │ │ - Database: snapshot_data (READ) │ │ - Code: NOT in this repository (proprietary) │ └────────────────────────┬────────────────────────────────────┘ │ gRPC over mTLS │ Port: 50051 (internal network) ▼ ╔═════════════════════════════════════════════════════════════╗ ║ Enclave Worker (Trusted Zone - THIS REPOSITORY) ║ ╟─────────────────────────────────────────────────────────────╢ ║ AMD SEV-SNP VM (Hardware Isolation) ║ ║ ║ ║ ┌───────────────────────────────────────────────────────┐ ║ ║ │ Autonomous Daily Sync Scheduler (00:00 UTC) │ ║ ║ │ - DailySyncSchedulerService (node-cron) │ ║ ║ │ - Triggers daily snapshots for ALL active users │ ║ ║ │ - Rate-limited (23h cooldown per user/exchange) │ ║ ║ │ - Audit trail: SyncRateLimitLog table │ ║ ║ └───────────────────────────────────────────────────────┘ ║ ║ ║ ║ ┌───────────────────────────────────────────────────────┐ ║ ║ │ gRPC Server (Port 50051) │ ║ ║ │ - ProcessSyncJob (manual sync) │ ║ ║ │ - GetAggregatedMetrics │ ║ ║ │ - HealthCheck │ ║ ║ └───────────────────────────────────────────────────────┘ ║ ║ ║ ║ ┌───────────────────────────────────────────────────────┐ ║ ║ │ Core Services │ ║ ║ │ ┌─────────────────────────────────────────────────┐ │ ║ ║ │ │ EncryptionService (src/services/) │ │ ║ ║ │ │ - AES-256-GCM credential decryption │ │ ║ ║ │ │ - Key derivation (SHA-256) │ │ ║ ║ │ │ - No key logging or persistence │ │ ║ ║ │ └─────────────────────────────────────────────────┘ │ ║ ║ │ ┌─────────────────────────────────────────────────┐ │ ║ ║ │ │ TradeSyncService (src/services/) │ │ ║ ║ │ │ - Exchange polling orchestration │ │ ║ ║ │ │ - Trade deduplication │ │ ║ ║ │ └─────────────────────────────────────────────────┘ │ ║ ║ │ ┌─────────────────────────────────────────────────┐ │ ║ ║ │ │ EquitySnapshotAggregator (src/services/) │ │ ║ ║ │ │ - Equity snapshot creation (daily at 00:00) │ │ ║ ║ │ │ - P&L calculation (realized + unrealized) │ │ ║ ║ │ │ - Deposit/withdrawal tracking │ │ ║ ║ │ └─────────────────────────────────────────────────┘ │ ║ ║ │ ┌─────────────────────────────────────────────────┐ │ ║ ║ │ │ SyncRateLimiterService (src/services/) │ │ ║ ║ │ │ - 23-hour cooldown enforcement │ │ ║ ║ │ │ - Prevents cherry-picking via manual API calls │ │ ║ ║ │ │ - Audit trail for systematic snapshot proof │ │ ║ ║ │ └─────────────────────────────────────────────────┘ │ ║ ║ └───────────────────────────────────────────────────────┘ ║ ║ ║ ║ ┌───────────────────────────────────────────────────────┐ ║ ║ │ Exchange Connectors (src/connectors/) │ ║ ║ │ - CcxtExchangeConnector (Binance, Bitget, MEXC) │ ║ ║ │ - IbkrFlexConnector (Interactive Brokers) │ ║ ║ │ - AlpacaConnector (Alpaca Markets) │ ║ ║ └───────────────────────────────────────────────────────┘ ║ ║ ║ ║ ┌───────────────────────────────────────────────────────┐ ║ ║ │ Database Layer (src/repositories/) │ ║ ║ │ - User: enclave_user (full privileges) │ ║ ║ │ - Tables: trades (R/W), snapshot_data (W) │ ║ ║ │ - Audit: sync_rate_limit_logs (R/W) │ ║ ║ │ - All queries parameterized (Prisma ORM) │ ║ ║ └───────────────────────────────────────────────────────┘ ║ ╚═════════════════════════════════════════════════════════════╝ Output: Aggregated daily snapshots only (no individual trades) Autonomous: Daily sync at 00:00 UTC for all active users ``` ### 数据流 ``` ┌─────────────────────────────────────────────────────────┐ │ AUTONOMOUS SCHEDULER (00:00 UTC daily) │ │ ┌──────────────────────────────────────────────────┐ │ │ │ DailySyncSchedulerService (node-cron) │ │ │ │ 1. Get all active users from database │ │ │ │ 2. For each user, get active exchange conns │ │ │ │ 3. Check rate limit (23h cooldown) │ │ │ │ 4. Trigger snapshot creation │ │ │ │ 5. Record sync in audit log │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ │ ▼ External Exchange APIs (Binance, IBKR, Alpaca) │ ▼ ┌──────────────┐ │ Credentials │ ◄── Retrieved encrypted from PostgreSQL │ (encrypted) │ AES-256-GCM decryption IN ENCLAVE └──────────────┘ │ ▼ ┌──────────────┐ │ Current │ ◄── Fetched via HTTPS (TLS 1.3) │ Account │ Total equity, realized balance, unrealized P&L │ State │ Deposits/withdrawals detection └──────────────┘ │ ▼ ┌──────────────┐ │ Create Daily │ ◄── EquitySnapshotAggregator │ Snapshot │ Timestamp: 00:00 UTC └──────────────┘ Fields: totalEquity, realizedBalance, unrealizedPnL, │ deposits, withdrawals, breakdown_by_market ▼ ┌──────────────┐ │ Store │ ◄── PostgreSQL snapshot_data table │ snapshot_ │ Gateway has SELECT access │ data │ No individual trades visible └──────────────┘ One snapshot per day per user/exchange │ ▼ ┌──────────────┐ │ Rate Limiter │ ◄── SyncRateLimiterService │ Audit Log │ Records sync timestamp └──────────────┘ Prevents manual cherry-picking │ ▼ API Gateway (untrusted) → Frontend (public) ``` ### 关键安全属性 1. **零知识架构**：单笔交易**绝不**传输到 Enclave 之外。只有聚合后的每日快照（总权益、P&L）通过 gRPC 越过 Enclave 边界。API Gateway（以及任何攻破它的攻击者）**只能**看到每日摘要，绝看不到单笔交易或价格。 2. **自主系统化快照**：调度器在硬件认证的 Enclave 内部于每日 UTC 00:00 运行，确保快照是系统化生成的，无法在有利的市场条件下进行挑选。速率限制器强制执行 23 小时的冷却时间，防止手动 API 滥用。 3. **审计追踪**：所有同步操作都记录在 `sync_rate_limit_logs` 表中并带有时间戳，证明快照是由 Enclave 调度器系统化创建的，而不是为了掩盖亏损而手动触发的。 ## 可信计算基 ### 规模指标 | 组件 | 文件数 | 代码行数 | 用途 | |-----------|-------|-----|---------| | **EncryptionService** | 1 | 151 | AES-256-GCM 凭证解密 | | **Exchange Connectors** | 3 | 810 | CCXT, IBKR, Alpaca 集成 | | **External API Services** | 2 | 532 | 从交易所获取账户状态 | | **EquitySnapshotAggregator** | 1 | 555 | 创建带 P&L 的每日快照 | | **TradeSyncService** | 1 | 259 | 同步编排 | | **DailySyncSchedulerService** | 1 | 193 | 自主 Cron 调度器 (00:00 UTC) | | **SyncRateLimiterService** | 1 | 201 | 速率限制与审计追踪 | | **Repositories** | 4 | 817 | 数据库访问层 | | **EnclaveWorker + Server + Index** | 3 | 1,812 | gRPC 服务器、Worker 和入口点 | | **总计** | **20** | **~5,300** | 最小化攻击面 | **TCB 规模的理由**：通过仅隔离**必须**处理凭证和创建快照的代码，我们将攻击面从约 12,000 行代码（完整平台）减少到约 5,300 行代码（仅 Enclave）。这使得安全审计变得可行，并降低了漏洞的概率。自主调度器和速率限制器包含在 TCB 中，以通过硬件认证证明快照的完整性。 ### 依赖项 关键依赖项（包含在 TCB 审计范围内）： | 包 | 版本 | 用途 | CVEs | |---------|---------|---------|------| | `@prisma/client` | 6.15.0 | 数据库 ORM (参数化查询) | 无 | | `@grpc/grpc-js` | 1.14.1 | gRPC 实现 | 无 | | `ccxt` | 4.5.2 | 加密货币交易所集成 | 无 | | `@stoqey/ib` | 1.5.1 | Interactive Brokers API | 无 | | `@alpacahq/alpaca-trade-api` | 3.1.3 | Alpaca Markets API | 无 | | `node-cron` | 3.0.3 | 自主调度器 (每日 00:00 UTC) | 无 | | `tsyringe` | 4.10.0 | 依赖注入 | 无 | | `winston` | 3.17.0 | 日志记录 (敏感数据已脱敏) | 无 | 传递依赖总计：49 个包（已使用 `npm audit` 审计） ## 威胁模型 ### 范围内的威胁 #### 1. API Gateway 被攻破 **威胁**：攻击者获得 API Gateway 服务的控制权。 **影响**：如果没有 Enclave 隔离，攻击者可以访问所有单笔交易和凭证。 **缓解措施**： - Gateway 在 Enclave 之外运行，具有受限的数据库访问权限 - PostgreSQL 权限阻止 gateway_user 读取 `trades` 表 - Gateway 仅通过 gRPC 接收聚合后的每日快照 - 速率限制器审计日志证明快照是系统化的，而非挑选的 **验证**：审计人员应验证 Gateway 代码（不在此仓库中）无法访问敏感表或绕过速率限制。 #### 2. Hypervisor 被攻破 **威胁**：恶意云服务提供商或攻击者攻破 VM Hypervisor。 **影响**：如果没有 SEV-SNP，Hypervisor 可以读取 Enclave 内存并窃取凭证。 **缓解措施**： - AMD SEV-SNP 使用 Hypervisor 无法访问的密钥加密 VM 内存 - 内存加密使用 AES-128，每个 VM 使用临时密钥 - 认证在凭证解密前验证 Enclave 二进制完整性 **验证**：审计人员应验证在 Enclave 启动时检查 SEV-SNP 认证（见 `src/config/enclave-container.ts`）。 #### 3. 供应链攻击 **威胁**：通过受损的 npm 包注入恶意代码。 **影响**：攻击者可以窃取凭证或交易数据。 **缓解措施**： - `package-lock.json` 锁定确切的依赖版本和哈希值 - 可复现构建允许验证部署的二进制文件与审计过的源代码匹配 - 定期 `npm audit` 检查已知漏洞 **验证**：审计人员应审查 `package-lock.json` 完整性哈希并检查可疑依赖项。 #### 4. 恶意内部人员（基础设施） **威胁**：有权访问生产基础设施的内部人员试图提取敏感数据。 **影响**：如果没有认证，内部人员可以部署修改后的 Enclave 代码。 **缓解措施**： - SEV-SNP 认证报告在 Gateway 连接前验证二进制哈希 - 生产构建中禁用调试接口 - 所有 Enclave 访问都被记录（审计追踪） **验证**：审计人员应验证生产代码路径中不存在调试端点。 ### 范围外的威胁 - **AMD SEV-SNP 固件被攻破**：需要硬件信任根 - **服务器的物理访问**：物理安全属于运维问题 - **侧信道攻击**：时序/功耗分析超出范围 - **拒绝服务**：可用性与机密性是分开的 ### 攻击面 | 接口 | 暴露面 | 攻击向量 | 缓解措施 | 审计重点 | |-----------|----------|---------------|------------|-------------| | **gRPC API** | 仅限内部网络 | 格式错误的消息 | Protobuf Schema 验证 | 验证无未认证端点 | | **PostgreSQL** | 本地套接字 | SQL 注入 | 参数化查询 | 审查所有查询构造 | | **Exchange APIs** | HTTPS 出站 | MitM, 响应篡改 | TLS 1.3, 响应验证 | 检查 TLS 配置, 输入清洗 | | **Dependencies** | npm 包 | 恶意代码 | 锁文件固定, 审计 | 审查 package-lock.json 哈希 | ## 审计流程 ### 范围 本代码仓库专为独立安全审计而设计。审计人员应关注： 1. **凭证处理**：验证凭证仅在内存中解密且从不被记录 2. **交易隐私**：确认单笔交易绝不离开 Enclave 边界 3. **密码学正确性**：审查 AES-256-GCM 实现 4. **输入验证**：检查所有外部输入（gRPC, 交易所 API）是否已清洗 5. **输出脱敏**：确保聚合数据不包含单笔交易细节 6. **可复现构建**：验证部署的二进制文件与源代码匹配 ### 审计清单 **凭证安全：** - [ ] 审查 `src/services/encryption-service.ts` 中的密钥派生和 AES-GCM 使用 - [ ] 验证 `src/utils/logger.ts` 或 `src/utils/logger.service.ts` 中未记录凭证 - [ ] 检查凭证未以解密形式持久化（grep 搜索 `writeFile`, `console.log`） - [ ] 确认解密后的凭证仅存储在 Enclave RAM 中（无全局变量） **快照隐私：** - [ ] 审查 `src/services/equity-snapshot-aggregator.ts` 快照创建逻辑 - [ ] 验证 gRPC 响应（见 `src/enclave-server.ts`）仅包含聚合数据 - [ ] 检查 snapshot_data 表中无单笔交易 - [ ] 确认日志中无交易细节（搜索包含交易数据的 `logger.debug`） - [ ] 审查 `src/services/sync-rate-limiter.service.ts` 的速率限制执行 - [ ] 验证 `sync_rate_limit_logs` 审计追踪防止挑选行为 - [ ] 检查 `src/services/daily-sync-scheduler.service.ts` 系统性地在 00:00 UTC 运行 **输入验证：** - [ ] 审查 `src/enclave-server.ts` 中的 gRPC 消息验证 - [ ] 检查 `src/external/` (ccxt, ibkr, alpaca) 中的交易所 API 响应解析 - [ ] 验证 `src/repositories/enclave-repository.ts` 中的 Prisma 查询使用参数化语句 - [ ] 测试 SQL 注入向量（手动或自动） **依赖项：** - [ ] 运行 `npm audit` 并查看结果 - [ ] 检查 `package-lock.json` 完整性哈希 - [ ] 审查关键依赖项：`ccxt`, `@stoqey/ib`, `@alpacahq/alpaca-trade-api` - [ ] 验证传递依赖中无可疑包 **构建验证：** - [ ] 在干净的 Ubuntu 22.04 VM 上克隆仓库并构建 - [ ] 验证构建哈希与发布的哈希匹配 - [ ] 审查 `tsconfig.json` 中的构建过程是否有可疑标志 - [ ] 检查 Source Map 暴露（生产构建不应包含 Source Maps） ### 推荐工具 - **静态分析**：ESLint, TypeScript strict mode (在 `tsconfig.json` 中启用) - **依赖扫描**：`npm audit`, Snyk, GitHub Dependabot - **秘密检测**：GitLeaks, TruffleHog - **代码审查**：侧重安全的手动审查 ###往审计 | 日期 | 审计员 | 版本 | 状态 | 报告 | |------|---------|---------|--------|--------| | 待定 | 待定 | v1.0.0 | 待处理 | - | ### 负责任披露 安全漏洞应私下报告给： - **邮箱**：security@trackrecord.com - **响应 SLA**：确认需 48 小时，初步评估需 7 天 请**不要**针对安全漏洞公开提 GitHub Issue。 ## 可复现构建 ### 目的 可复现构建允许验证生产环境中运行的二进制文件是否与审计过的源代码匹配。这可以防止“信任信任”问题，即源代码是干净的，但部署的二进制文件被篡改。 ### 构建流程 ``` # 克隆仓库 git clone https://github.com/AuditZK/zero-knowledge-aggregator.git cd zero-knowledge-aggregator # 检出特定版本 git checkout v1.0.0 # 验证 commit hash git rev-parse HEAD # 预期: 0622144abcdef... (发布于 release page) # 安装精确依赖 npm ci # 生成 Prisma client npm run prisma:generate # 构建 TypeScript npm run build # 计算 build hash find dist -type f -name "*.js" -exec sha256sum {} \; | sort -k 2 | sha256sum # 预期: (发布于 release page) ``` ### 构建环境 为了实现逐位可复现： - **Node.js**: 20.11.0 (精确版本) - **npm**: 10.2.3 - **OS**: Ubuntu 22.04 LTS (Linux 内核 5.15+) - **架构**: x86_64 - **区域设置**: `LANG=C.UTF-8` 详细说明：[BUILD.md](BUILD.md) ### 认证（仅限生产环境） 在 AMD SEV-SNP 上的生产部署中： 1. Enclave 生成包含以下内容的认证报告： - 二进制哈希 (SHA-256) - VM 度量 - SEV-SNP 固件版本 2. API Gateway 在连接到 Enclave 之前验证认证 3. 认证报告可由审计人员独立验证 **注意**：认证仅在 AMD SEV-SNP 硬件上可用，不适用于开发环境。 ## API 规范 ### gRPC 服务定义 ``` service EnclaveService { // Process sync job for a user's exchanges // Returns: Aggregated snapshot data (NOT individual trades) rpc ProcessSyncJob(SyncJobRequest) returns (SyncJobResponse); // Get aggregated metrics // Returns: Summary statistics (balance, P&L totals) rpc GetAggregatedMetrics(AggregatedMetricsRequest) returns (AggregatedMetricsResponse); // Health check rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse); } ``` 完整规范：[src/proto/enclave.proto](src/proto/enclave.proto) ### API 的安全属性 **关键**：所有 gRPC 响应**仅**包含聚合数据。单笔交易价格、时间戳或数量**绝不**传输到 Enclave 之外。 #### ProcessSyncJob 响应结构 ``` { success: true, userUid: "user123", exchange: "binance", synced: true, latestSnapshot: { // Aggregated daily snapshot (00:00 UTC) totalEquity: 10500.00, // Total account value (realized + unrealized) realizedBalance: 10250.42, // Available cash/balance unrealizedPnL: 249.58, // Unrealized P&L from open positions deposits: 0, // Cash deposited today withdrawals: 0, // Cash withdrawn today timestamp: "2025-01-15T00:00:00Z" // Daily snapshot timestamp } // NO individual trades array // NO trade prices // NO trade timestamps // NO position sizes } ``` #### GetAggregatedMetrics 响应结构 ``` { totalBalance: 10250.42, // Total realized balance across all exchanges totalEquity: 10500.00, // Total equity (realized + unrealized) totalRealizedPnl: 500.00, // Cumulative realized P&L totalUnrealizedPnl: 249.58, // Current unrealized P&L totalFees: 25.50, // Cumulative fees paid totalTrades: 150, // Count only (no trade details) lastSync: "2025-01-15T00:00:00Z" // Timestamp of last snapshot // NO individual trades // NO exchange-specific breakdown with identifying details } ``` ## 合规性 - **GDPR 第 32 条**（处理的安全性）：保护个人数据的技术措施 - **FIPS 140-2 Level 1**：密码学原语（通过 Node.js crypto 模块实现 AES-256-GCM） - **SOC 2 Type II**：数据处理的审计控制（进行中） ## 参考资料 - [AMD SEV-SNP 白皮书](https://www.amd.com/content/dam/amd/en/documents/epyc-business-docs/white-papers/SEV-SNP-strengthening-vm-isolation-with-integrity-protection-and-more.pdf) - [CCXT 文档](https://docs.ccxt.com/) - [Interactive Brokers Flex Web API](https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm) - [gRPC 安全指南](https://grpc.io/docs/guides/auth/) - [可复现构建项目](https://reproducible-builds.org/) ## 许可证 MIT 许可证 - 详见 [LICENSE](LICENSE) 此代码发布用于透明度和审计目的。不支持第三方部署。 ## 联系方式 - **支持邮箱**：support@auditzk.com - **GitHub Issues**：https://github.com/AuditZK/zero-knowledge-aggregator/issues

标签：AES-256-GCM, AMD SEV-SNP, FIPS 140-2, GNU通用公共许可证, gRPC, MITM代理, Node.js, PostgreSQL, Python工具, StruQ, 加密货币交易, 可信执行环境 (TEE), 可信计算基 (TCB), 可重现构建, 多交易所数据, 安全飞地, 密钥保护, 投资组合管理, 抗篡改, 数据主权, 数据聚合, 机密计算, 测试用例, 硬件加密内存, 硬件安全, 私密计算, 自动化攻击, 请求拦截, 远程证明, 金融科技, 零知识证明, 零知识隐私