anoop04singh/veraAudit

# VeraAudit VeraAudit 是一个全栈 Sui Move 智能合约审计系统，它结合了以下功能： - Tatum 用于 Sui RPC 访问和 Walrus 上传编排 - Gemini 用于结构化合约安全分析 - RAG 用于 Sui/Move 特定的安全基础 - Walrus 用于不可变审计工件存储 - Sui 主网锚定以实现公共可验证性 结果是面向证明的审计工作流程，其中每个审计都可以： 1. 从真实的链上包状态生成 2. 通过目标安全上下文丰富 3. 作为不可变证据存储 4. 在 Sui 主网上锚定 5. 在仪表板上重新打开和验证 ## 项目功能 给定一个 Sui 包 ID，VeraAudit： 1. 通过 Tatum 从 Sui 获取标准化 Move 模块 2. 收集最近的交易和事件上下文 3. 通过 RAG 获取相关的 Sui/Move 安全知识 4. 要求 Gemini 生成结构化审计结果 5. 通过 Tatum 的存储 API 在 Walrus 上存储完整的审计 blob 6. 在 Sui 主网上锚定生成的 Walrus quilt/blob 引用 7. 通过 React 前端公开审计历史、报告和验证流程 这不仅仅是一个 LLM 包装器。系统设计得如此，以至于审计记录可以在以下方面进行追踪： - 源包 ID - 分析期间使用的链上下文 - 获取的安全参考 - 不可变的 Walrus 工件 - 链上锚定事件 ## 架构摘要 ### 核心组件 - `frontend/` React + Vite UI 用于着陆页、审计工作区、审计历史和证明验证 - `server/` Express API 服务器，用于协调 Tatum、Gemini、Walrus、RAG 和 Sui 锚定 - `contracts/` Sui Move 注册合约，用于在链上存储审计锚定元数据 ### 高级职责 - 前端 收集包 ID、渲染指标、流式传输管道进度、显示存储的审计和验证证明 - 后端 获取包和交易上下文、运行 RAG + Gemini、上传 Walrus 工件、在 Sui 上锚定结果 - 合约 发出可审计的链上事件，这些事件引用 Walrus 工件和审计哈希 ## Sui 主网上运行时合约地址 当前 `.env` 中的运行时配置将应用程序指向以下实时 Sui 对象： | 项目 | 地址 | | --- | --- | | 注册包 ID | `0xdd47918fec65c24ad41115782ab780d7f234e163d6c75cf1b39622ed6bd20a21` | | 注册共享对象 ID | `0xe5fc0c83fd0331bdc3c924d83cbd9a121cde440283ae58b37f8205e0124ca530` | | 管理能力对象 ID | `0xb77fe7f28a3e8d35271e6b1a26024d0de48f22b245bb9e01a3b2f68076d1e9a9` | | 时钟对象 ID | `0x6` | ## Move 合约 Sui 注册合约位于 [contracts/sources/registry.move](/C:/Users/singa/Downloads/veraAudit/contracts/sources/registry.move). 它存储审计元数据并为每个锚定的审计发出 `AuditSubmitted` 事件。 ### 主要数据结构 - `AuditRegistry` 共享链上注册表，包含： - 管理员地址 - 总审计计数 - 从审计包地址到 `vector` 的映射 - `AuditEntry` 存储： - Walrus blob/quilt ID - 审计哈希 - 审计员地址 - 埃波克 - 严重性 - 时间戳 - `AuditSubmitted` 事件发出以进行链下索引和审计历史重建 ### 主要入口点 - `submit_audit` 将新的审计条目写入注册表并发出相应的事件 ## 完整审计管道 管道实现位于 [server/src/auditPipeline.js](/C:/Users/singa/Downloads/veraAudit/server/src/auditPipeline.js). ### 步骤流程 1. 获取包模块 - 调用 `sui_getNormalizedMoveModulesByPackage` - 接收目标包的标准化 Move 模块 ABI/数据 2. 构建交易和事件上下文 - 从标准化模块中枚举公开函数 - 使用 `suix_queryTransactionBlocks` 查询交易块 - 压缩和限制链上下文以供模型输入 - 当需要时回退到受保护的 `suix_queryEvents` 查询 3. 获取 RAG 上下文 - 从以下内容生成面向安全的检索查询： - 模块名称 - 公开函数名称 - 结构名称 - 字段/类型信号 - 近期事件类型 - 当启用时使用嵌入 - 当嵌入调用不可用时回退到词汇检索 4. 运行 Gemini 审计 - 构建包含以下内容的结构化提示： - 标准化模块 - 近期交易上下文 - 近期事件上下文 - 获取的 RAG 指导 - 强制 Gemini 返回与审计模式匹配的严格 JSON 5. 组装不可变审计工件 - 在单个 JSON blob 中存储完整的审计有效负载、链快照和检索元数据 6. 上传到 Walrus - 通过 Tatum 的 Walrus 上传 API 发送审计 JSON - 轮询直到上传得到认证 - 提取最终的 quilt/blob 标识符 7. 在 Sui 主网上锚定 - 计算审计 blob 的 SHA-256 哈希 - 在注册合约上提交 `submit_audit` - 存储： - 审计的合约/包 ID - Walrus quilt/blob ID - 审计哈希 - 严重性 - 时间戳 8. 将结果公开给 UI - 在运行期间发出结构化 SSE 步骤事件 - 通过 Sui 事件和 Walrus 存储保持可发现性 ## 详细 ASCII 图表 ``` V E R A A U D I T ======================================================================================== User / Frontend | | 1. submit package id v POST /api/audit -------------------------------------------------------------+ | | v | +----------------------+ | | Express Audit Server | | +----------------------+ | | | | 2. fetch normalized modules | | 3. fetch tx/event context | v | +---------------------------+ | | Tatum Sui RPC Gateway | | | https://sui-mainnet... | | +---------------------------+ | | | | returns package ABI, tx blocks, events | v | +---------------------------+ | | Pipeline Context Builder | | | - exposed function scan | | | - tx compaction | | | - event extraction | | +---------------------------+ | | | | 4. build RAG queries | v | +---------------------------+ 5a. embedding retrieval (optional) | | RAG Retriever | ------------------------------------------+ | | - local knowledge base | | | | - lexical ranking | | | | - embedding ranking | v | +---------------------------+ +--------------------------+ | | Gemini Embeddings API | | 5b. top security chunks | gemini-embedding-001 | v +--------------------------+ +---------------------------+ | | Prompt Assembler | | | - modules | | | - tx context | | | - event context | | | - RAG guidance | | +---------------------------+ | | | | 6. structured audit request | v | +---------------------------+ | | Gemini Audit Model | | | generates JSON findings | | +---------------------------+ | | | | 7. full audit artifact JSON | v | +---------------------------+ | | Walrus Upload via Tatum | --> POST /v4/data/storage/upload | | certification polling | --> GET /v4/data/storage/upload/:jobId | +---------------------------+ | | | | returns quilt/blob id | v | +---------------------------+ | | Hash + Anchor Builder | | | sha256(auditBlob) | | +---------------------------+ | | | | 8. submit_audit move call | v | +---------------------------+ | | Sui Mainnet Registry | | | AuditSubmitted event | | +---------------------------+ | | | +--------------------> 9. UI reads /api/check, /api/metrics, /api/blob --+ and reconstructs history from: - Sui events - Walrus blob - stored audit report ``` ## Tatum 集成 Tatum 是链和 Walrus 交互的操作骨干。 ### Tatum 的使用位置 1. Sui JSON-RPC 访问 - 包内省 - 交易查找 - 事件查询 - 锚定交易提交 2. Walrus 上传编排 - 审计 blob 上传 - 认证轮询 3. 请求节流和重试处理 - 外部 Tatum 请求通过 [server/src/tatumTransport.js](/C:/Users/singa/Downloads/veraAudit/server/src/tatumTransport.js）序列化 - `TATUM_MIN_INTERVAL_MS` 空间请求以减少速率限制问题 ### Tatum 使用的端点 #### Tatum Sui RPC 基础 URL - `https://sui-mainnet.gateway.tatum.io` #### 通过 Tatum 使用的 JSON-RPC 方法 - `sui_getNormalizedMoveModulesByPackage` - `suix_queryTransactionBlocks` - `suix_queryEvents` - `sui_executeTransactionBlock` - `sui_getLatestCheckpointSequenceNumber` #### Tatum Walrus 端点使用 - `POST https://api.tatum.io/v4/data/storage/upload` 排队 Walrus 上传 - `GET https://api.tatum.io/v4/data/storage/upload/:jobId` 轮询认证状态直到 `CERTIFIED` ### Tatum 回退行为 锚定首先尝试配置的 Tatum Sui RPC 端点。如果失败，后端回退到： - `https://fullnode.mainnet.sui.io:443` 此回退仅用于交易锚定，不用于 Walrus 上传。 ## Walrus 集成 Walrus 集成在 [server/src/walrus.js](/C:/Users/singa/Downloads/veraAudit/server/src/walrus.js）中实现。 ### 存储内容 每个审计 blob 包括： - 目标包 ID - 审计时间戳 - Gemini 模型信息 - 模块快照 - 交易快照 - 事件快照 - RAG 检索元数据 - 摘要 - 严重性 - 安全交互结论 - 发现 - 置信度 ### 上传行为 1. 后端将审计有效负载序列化为 JSON 2. 它计算一个确定性的文件名 3. 它通过 Tatum 的 Walrus 上传端点上传文件 4. 它轮询直到上传成为 `CERTIFIED` 5. 它返回 `quiltPatchId` 或 `blobId` ### 读取行为 存储的审计工件通过 Walrus 主网聚合器读取： - `https://aggregator.walrus-mainnet.walrus.space/v1/blobs/by-quilt-patch-id/:quiltId` ### 为什么使用 Walrus Walrus 作为不可变证据层。而不是在链上存储完整的审计有效负载，VeraAudit 在 Walrus 上存储： - 完整报告离线但不可变 - 紧凑的引用和哈希在链上 这使得验证更便宜且更实际，同时保留审计可追踪性。 ## Gemini 集成 Gemini 集成在 [server/src/gemini.js](/C:/Users/singa/Downloads/veraAudit/server/src/gemini.js）中实现。 ### 使用的模型 - 审计生成模型 - 默认配置：`gemini-2.5-flash` - RAG 的嵌入模型 - `gemini-embedding-001` 实际的运行时值来自 `.env`. ### Gemini 收到的内容 Gemini 获取一个包含以下内容的提示： - 标准化模块快照 - 近期紧凑的交易上下文 - 近期事件上下文 - 获取的 RAG 上下文 - 明确的安全说明 - 严格的 JSON 模式 ### Gemini 返回的内容 模型必须返回以下内容的 JSON： - `summary` - `severity` - `safe_to_interact` - `safe_to_interact_rationale` - `findings` - `positive_patterns` - `confidence` 这通过 `responseMimeType: "application/json"` 和响应模式强制执行。 ## RAG 集成 RAG 集成在 [server/src/rag.js](/C:/Users/singa/Downloads/veraAudit/server/src/rag.js）中实现。 ### 为什么 RAG 存在于此项目 通用 LLM 审计对于 Sui Move 来说不够，因为许多重要风险是特定领域的： - 对象所有权滥用 - 共享对象安全性 - 能力泄露 - 传输语义 - 升级性假设 - Sui-和 Move 特定的授权模式 RAG 在 Gemini 评估包之前注入了目标安全知识。 ### 检索如何工作 1. 从标准化模块中提取信号 - 模块名称 - 公开函数名称 - 结构名称 - 字段名称/类型 2. 推断类别 - 访问控制 - 能力 - 对象管理 - 算术 - 传输 - 闪电贷款 - 输入验证 - 升级性 3. 从以下内容构建检索查询： - 合约/包 ID - 函数签名 - 结构签名 - 近期事件类型 4. 对本地知识库进行评分 - 当启用时使用嵌入相似度 - 词汇相似度作为基线/回退 5. 返回 top-k 块 - 默认为 `RAG_TOP_K` ### RAG 回退行为 如果 Gemini 嵌入调用失败，系统不会中止。它回退到词汇检索并继续审计。 ## API 接口 后端服务器位于 [server/src/index.js](/C:/Users/singa/Downloads/veraAudit/server/src/index.js）。 ### 公共后端端点 #### `GET /api/health` 返回： - 服务健康 - 网络标签 - 配置的 Tatum RPC URL - 配置的 Walrus 聚合器 - 标志显示是否存在关键配置 #### `GET /api/test-tatum` 通过请求最新的 Sui 检查点测试 Tatum RPC 连接。 #### `GET /api/check/:contractId` 从 Sui 加载先前锚定的审计事件，并为合约/包返回排序的审计历史。 #### `GET /api/blob/:blobId` 从 Walrus 获取不可变的审计工件。 #### `GET /api/verify/:blobId` 通过以下方式验证 Walrus blob 与链上数据： - 获取 blob - 查找匹配的 Sui 审计事件 - 重新计算 SHA-256 - 将其与锚定的链上哈希进行比较 返回证明是否验证。 #### `POST /api/audit` 启动新的审计运行并通过 SSE 流式传输进度。 请求体： ``` { "contractId": "0x..." } ``` SSE 事件类型： - `progress` - `step_log` - `step_output` - `complete` - `error` #### `GET /api/metrics` 返回仪表板指标： - 总审计 - 唯一合约 - 严重性分布 - 近期审计 ## 前端页面 ### 着陆页 - 项目定位 - 来自 `/api/metrics` 的真实审计指标 - 架构解释 - RAG/Gemini/Tatum/Walrus 解释 ### 审计工作区 - 接受 Sui 包 ID - 开始或检查审计 - 渲染最近的审计卡片 - 显示管道状态和历史记录 ### 审计详情页 - 列出先前的锚定审计事件 - 链接合约、tx 和 blob 引用 - 渲染存储的审计报告 ### 验证页面 - 从 Walrus 加载审计 blob - 将其计算出的哈希与链上审计事件进行比较 ## 项目结构 ``` veraAudit/ |-- contracts/ | |-- sources/registry.move | |-- Move.toml | `-- Published.toml |-- frontend/ | |-- public/ | |-- src/ | | |-- components/ | | |-- pages/ | | |-- utils/ | | |-- App.jsx | | |-- main.jsx | | `-- styles.css | |-- index.html | `-- vite.config.js |-- server/ | |-- src/ | | |-- index.js | | |-- auditPipeline.js | | |-- anchor.js | | |-- gemini.js | | |-- rag.js | | |-- ragKnowledge.js | | |-- tatum.js | | |-- tatumTransport.js | | |-- walrus.js | | `-- ... | `-- test/ |-- .env.example |-- package.json `-- README.md ``` ## 设置和安装 ### 先决条件 - Node.js 18+ 推荐使用 - npm - Tatum API 密钥 - Gemini API 密钥 - Sui 私钥用于实时锚定 ### 1. 克隆和安装 ``` git clone cd veraAudit npm install ``` ### 2. 配置环境 复制示例文件： ``` cp .env.example .env ``` 在 Windows PowerShell 中： ``` Copy-Item .env.example .env ``` 然后填写所需值。 ### 3. 必要的环境变量 #### 服务器 - `PORT` - `NODE_ENV` #### Tatum RPC + Walrus - `TATUM_API_KEY` - `TATUM_SUI_RPC` - `TATUM_WALRUS_UPLOAD_URL` - `TATUM_WALRUS_STATUS_POLL_MS` - `TATUM_WALRUS_STATUS_MAX_ATTEMPTS` - `TATUM_MIN_INTERVAL_MS` #### Gemini - `GEMINI_API_KEY` - `GEMINI_MODEL` - `GEMINI_EMBEDDING_MODEL` - `GEMINI_EMBEDDING_DIMENSIONS` #### Sui 锚定配置 - `REGISTRY_PACKAGE_ID` - `REGISTRY_OBJECT_ID` - `ADMIN_CAP_OBJECT_ID` - `SUI_CLOCK_OBJECT_ID` - `SUI_PRIVATE_KEY` - `UI_ANCHOR_RPC_FALLBACK` #### 管道调整 - `RETRY_MAX_ATTEMPTS` - `RETRY_BASE_DELAY_MS` - `RETRY_MAX_DELAY_MS` - `CONTEXT_MODULE_QUERY_CONCURRENCY` - `MAX_CONTEXT_FUNCTION_QUERIES` - `CONTEXT_TRANSACTIONS_PER_FUNCTION` - `MAX_CONTEXT_TRANSACTIONS` - `MAX_CONTEXT_EVENTS` - `MAX_MODULE_CHARS_FOR_AUDIT` - `MAX_TRANSACTION_CHARS_FOR_AUDIT` - `MAX_EVENT_CHARS_FOR_AUDIT` - `MAX_RAG_CHARS_FOR_AUDIT` - `RAG_ENABLED` - `RAG_USE_EMBEDDINGS` - `RAG_TOP_K` ### 4. 启动应用程序 同时运行前端和后端： ``` npm run dev ``` 默认本地 URL： - 前端：`http://localhost:5173` - 后端

标签：日志审计, 自定义脚本, 逆向工具