Akk525/trustGraph

# TrustGraph **检测具有确定性**：四元谓词规则集 (E ∧ P ∧ V ∧ ¬G) 决定每项发现与严重性评定。可选的 Gemini 2.5 Flash 会在发现完成后添加通俗易懂的解释——它无法创建、修改或抑制任何发现。 ## 快速演示 ``` trustgraph audit examples/vulnerable-crosschain/src \ --generate-test \ --run-foundry \ --report-format both \ --output-dir .trustgraph ``` ``` Critical → receiveMessage VulnerableReceiver.sol:27 Medium → mint MockToken.sol:18 [PASS] test_directInvocationExploit() (gas: 67996) ``` ``` .trustgraph/ ├── report.md ├── report.json └── tests/ └── VulnerableReceiverExploit.t.sol ``` ## TrustGraph 存在的意义 跨链桥接收函数是反复出现的攻击面：一个 `external` 函数接受任意负载且不检查 `msg.sender`，因此任何地址都可能直接触发特权状态变更。2024 年 8 月的 CrossCurve 桥接漏洞（损失约 500 万美元）就是具体案例；相同模式也出现在 LayerZero 接收器、Axelar 网关以及自定义桥接集成中。 TrustGraph 通过三项工程保障应对此类问题： - **可审计的发现** —— 每个结果都追溯至基于函数源码评估的固定谓词 (E ∧ P ∧ V ∧ ¬G)。没有模型置信度分数，没有采样方差。 - **可执行的概念验证** —— 每个严重或中等发现都会生成一个 Foundry 测试。若 `forge test` 通过，则确认特定的漏洞利用路径有效。若测试失败，仍会报告该发现并附上测试以供人工审查。 - **决策路径中不依赖 LLM** —— Gemini 是在严重性评定后添加的可选解释层。传入 `--no-ai` 参数后，扫描器、漏洞利用生成器和报告均保持不变。 ## 设计原则 **基于确定性分析而非概率评分。** 发现结果由显式且固定的谓词产生。相同的函数源码在每次运行中都会产生相同的结果。无需调整、采样或依赖模型。 **可复现的漏洞利用验证。** 每个发现都由生成的 Foundry 测试支持。所生成路径的可利用性是一个二元结果——`forge test` 通过或不通过。 **人类可审计的证据。** 每个发现都暴露匹配的谓词条件和触发它们的函数源码。不存在黑箱推理。 **可选的 AI 增强，永不依赖 AI。** Gemini 会在发现完成后添加通俗易懂的解释。使用 `--no-ai` 禁用后，工具功能完全相同。 **集成开发者工作流。** 发现结果作为诊断信息出现在编辑器中，而不仅仅是报告文件。调查路径为：行内高亮 → 发现侧边栏 → 详情面板 → 漏洞利用测试 → 补丁模板。 ## 非目标范围 TrustGraph 的范围限于特定漏洞类别。它明确不尝试以下操作： - **符号执行** —— 不使用 SMT 求解器，不进行路径探索，不提供形式化验证 - **全面合约审计** —— 不分析重入、整数溢出、调用者守卫之外的访问控制模式或其他任意漏洞类别 - **跨文件或跨合约分析** —— 每个函数在其源文件内评估 - **自动打补丁** —— 补丁模板仅为人工审查建议；不会自动修改代码 - **替代审计** —— TrustGraph 呈现的是潜在的信任边界，并非专业审计的替代品 - **生产就绪性认证** —— 通过的概念验证仅确认所生成的漏洞利用路径可执行；对其他攻击面不作任何声明 ## 功能特性 - 对所有外部可调用函数进行四元谓词静态分析 (E/P/V/G) - 跨链接收器漏洞检测 - 自动生成 Foundry 漏洞利用概念验证测试，通过 `forge test` 执行 - 可选 Gemini 2.5 Flash 解释层——检测和严重性不受影响 - 当 Gemini 缺失或出错时自动回退至纯确定性模式 - Markdown + JSON 报告输出 - VS Code 扩展：行内诊断、发现侧边栏、漏洞利用测试查看器、补丁模板 - 包含 GitHub Actions CI/CD 工作流 ## 安装说明 **要求：** Python ≥ 3.10，[Foundry](https://book.getfoundry.sh/getting-started/installation)（运行 `--run-foundry` 时必需） ``` git clone https://github.com/your-org/trustgraph cd trustgraph pip install -e . ``` **包含可选 Gemini 解释：** ``` pip install -e ".[gemini]" export GEMINI_API_KEY="your_key_here" export GEMINI_MODEL="gemini-2.5-flash" # optional, this is the default ``` 若无 Gemini API 密钥，TrustGraph 会自动以纯确定性模式运行。密钥也可存储在 `.env` 文件中（该文件已被 gitignore）： ``` GEMINI_API_KEY=your_key_here ``` ## 使用方法 ``` # 基础审计 trustgraph audit path/to/contracts/src # 生成 Foundry 漏洞利用 PoC 测试 trustgraph audit path/to/src --generate-test # 生成测试并运行 forge test trustgraph audit path/to/src --generate-test --run-foundry # Markdown + JSON 报告 trustgraph audit path/to/src --report-format both # 仅确定性（无 LLM 调用） trustgraph audit path/to/src --no-ai ``` **所有选项：** ``` Arguments: PATH .sol file or directory [required] Options: --generate-test / --no-generate-test Generate Foundry exploit PoC [default: generate-test] --run-foundry / --no-run-foundry Execute forge test [default: no-run-foundry] --report-format TEXT markdown | json | both [default: markdown] --output-dir TEXT Output directory [default: trustgraph-output] --no-ai Disable LLM calls ``` ## VS Code 调查工作流 TrustGraph 附带一个用于交互式调查的本地 VS Code 扩展。 **设置：** ``` cd vscode-extension npm install npm run compile ``` 1. 在 VS Code 中打开 `vscode-extension/` 并按 **F5** 启动扩展开发主机。 2. 在新窗口中打开主 TrustGraph 仓库。 3. 在命令面板中运行 `TrustGraph: Run Audit`。 **推荐的 `.vscode/settings.json`：** ``` { "trustgraph.cliPath": "/path/to/trustgraph", "trustgraph.contractPath": "examples/vulnerable-crosschain/src", "trustgraph.outputDir": ".trustgraph", "trustgraph.runFoundry": true } ``` 报告和漏洞利用测试将写入 `.trustgraph/` 目录（已被 gitignore）。 **扩展功能：** | 功能 | 描述 | |---|---| | 行内诊断 | 漏洞函数上的红色/黄色波浪线 | | 发现侧边栏 | 按严重性分组的树状图，附带扫描摘要 | | 详情网页视图 | 谓词证据、守卫判定、Gemini 解释、Foundry 结果、补丁模板 | | 跳转到源码 | 跳转到标记的行 | | 打开漏洞利用测试 | 打开生成的 `.t.sol` 文件 | | 复制补丁 | 将推荐的修复方案复制到剪贴板 | **行内诊断 —— 编辑器中高亮显示的漏洞函数及“问题”面板条目：**  **发现侧边栏 —— 按严重性分组的树状图，扫描后填充：**  **严重发现详情面板 —— 谓词证据、信任假设分析、Foundry 结果：**  ## 漏洞模型 当所有四个谓词条件均满足时，函数将被标记： ``` Vulnerable(f) = E(f) ∧ P(f) ∧ V(f) ∧ ¬G(f) ``` | 谓词 | 含义 | 检测方式 | |---|---|---| | `E(f)` | `external` 或 `public` 可见性 | 函数签名中的可见性关键字匹配 | | `P(f)` | 接受攻击者控制的负载 | `bytes calldata`、`abi.decode`、参数名包含 `payload`/`data`/`message` | | `V(f)` | 主体中的关键状态变更 | `.mint(`、`.transfer(`、`.withdraw(`、`balances[` | | `G(f)` | 主体中存在调用者守卫 | `require(msg.sender ==`、`onlyOwner`、`onlyBridge`、`trustedBridge` | **严重性评定：** | 条件 | 严重性 | |---|---| | E + P + V + 无守卫 | **严重** | | E + V + 无守卫 | **中等** | | 其他情况 | 信息性 | ## 架构 ``` flowchart TD A[Solidity Contracts] --> B[TrustGraph CLI] B --> C[Static Scanner\nE / P / V / G predicate scoring] C --> D[Trust Assumption Inference\ndeterministic + optional Gemini explanation] D --> E[Guard Validation\nconfirm guard absence in function body] E --> F[Exploit Generator\nFoundry PoC template rendering] F --> G[Foundry Runner\nforge test subprocess] G --> H[Reports\nMarkdown + JSON] G --> I[VS Code Extension\ndiagnostics + investigation] ``` 该流水线作为一个 8 阶段有向无环图 (DAG) 运行，使用 [LangGraph](https://github.com/langchain-ai/langgraph) 作为执行框架。每个阶段是类型化状态对象上的纯函数；LangGraph 未用于智能体规划或 LLM 路由——它仅处理 DAG 连线和状态传递。 **项目布局：** ``` trustgraph/ ├── cli.py — Typer CLI entry point ├── graph.py — 8-stage pipeline DAG ├── models.py — Pydantic models + WorkflowState ├── scanners/ │ └── solidity.py — Function extractor + E/P/V/G scorer ├── agents/ │ ├── trust_assumption.py — Deterministic classifier + optional Gemini call │ ├── exploit_generator.py — Foundry PoC template engine │ └── patch_recommender.py — Patch suggestion templates ├── runners/ │ └── foundry.py — forge test subprocess wrapper └── reports/ ├── markdown.py — Markdown report generator └── json_report.py — JSON report generator ``` ## 漏洞利用生命周期 ``` flowchart LR A["External Entry Point\npublic / external"] --> B["Attacker-Controlled Payload\nbytes calldata / abi.decode"] B --> C["Missing Guard\nno require(msg.sender == trusted)"] C --> D["Critical State Mutation\n.mint / .transfer / .withdraw"] D --> E["Generated Foundry PoC\n.t.sol"] E --> F["forge test\npass = exploit path confirmed"] ``` **生成的漏洞利用测试 —— TrustGraph 为附带示例生成的 Foundry 概念验证：**  ## 确定性优先设计 ``` flowchart LR subgraph det["Deterministic Scanner — sole source of truth"] direction TB A[Exposure Detection E] B[Payload Detection P] C[State Mutation Detection V] D[Guard Detection G] E[Severity Assignment] F[Exploit Generation] end subgraph gem["Gemini 2.5 Flash — explanation only"] direction TB G[Trust Assumption Explanation] H[Natural-Language Reasoning] end det --> R[Findings + Reports + PoC] gem -. enriches explanation .-> R ``` Gemini 在严重性已评定后，针对每个发现仅被调用一次。它接收函数源码和谓词判定作为上下文。其输出填充报告和 VS Code 详情面板中的 `ai_analysis` 字段。它无法更改 `severity`、`is_vulnerable` 或漏洞利用生成。 **Gemini 回退行为：** | 条件 | 行为 | |---|---| | 传入 `--no-ai` | 仅确定性模式——不进行 API 调用 | | 无 `GEMINI_API_KEY` | 确定性回退，仍报告发现 | | API 错误或配额超限 | 确定性回退，仍报告发现 | | 无效或无法解析的响应 | 确定性回退，仍报告发现 | | 成功 | 发现被补充自然语言解释 | ## CI/CD TrustGraph 包含一个 GitHub Actions 工作流 (`.github/workflows/trustgraph.yml`)，其功能如下： 1. 检出仓库（含子模块 forge-std） 2. 安装 TrustGraph 和 Foundry 3. 对附带的示例合约运行审计 4. 断言检测到一个严重的 `receiveMessage` 发现 5. 将报告作为构建产物上传 ## 局限性 检测通过关键字模式匹配对各个函数主体进行操作。当前范围界限： - **不检测仅修饰符守卫** —— 函数签名上的 `onlyOwner` 不被评估；仅检查函数体内的 `require(...)` - **无继承解析** —— 父合约中定义的守卫不会追溯到子合约 - **无跨函数守卫传播** —— 包装器或调用函数中的守卫不会归功于被调用函数 - **单文件范围** —— 跨多个 `.sol` 文件的数据流不被追踪 - **模式敏感** —— 非标准命名约定可能导致假阴性；异常模式可能导致假阳性 ## 未来工作 - 通过 `solc --ast-compact-json` 进行 AST 级别解析以替代关键字提取 - 修饰符和继承解析 - 跨函数和跨合约调用图分析 - 集成 Slither 作为补充分析通道 - 从已确认的发现中导出 Semgrep 规则 ## 安全声明 TrustGraph 是一个早期阶段工具，其本身尚未经过安全审计。 通过的 Foundry 测试确认生成的概念验证漏洞利用在生成的测试环境中成功执行。它并不能证明不存在其他攻击路径，也不能证明合约在其他方面是安全的。所有发现在得出生产结论前都需要人工审查。TrustGraph 不能替代专业的智能合约审计。 ## 致谢 受到 2024 年 8 月 CrossCurve 桥接漏洞以及跨链接收器架构中更广泛的信任边界故障类别的启发。

标签：DeFi 安全, exploit 生成, Foundry, Solidity, Subfinder, VSCode 扩展, Web3 安全, 云安全监控, 以太坊安全, 信任边界分析, 区块链安全, 可执行验证, 审计工具, 智能合约安全, 杀软绕过, 桥接漏洞, 确定性分析, 跨链桥安全, 逆向工具, 静态分析