raghavendraprasath/guardscan

# GuardScan **AI 辅助的智能合约漏洞扫描器** GuardScan 将确定性的 Solidity 检测器与基于事实根据的 LLM 解释相结合，用于检测、排名、解释智能合约安全问题并提出修复建议——且不会产生自由发挥的幻觉。 | 字段 | 详情 | |---|---| | **作者** | Raghavendra Prasath Sridhar | | **课程** | INFO7500 — 加密货币与智能合约（2026 年夏季） | | **领域** | 区块链安全 | | **状态** | 最终项目提案 + 可运行的≤5小时 MVP 原型 | | **代码库** | [github.com/raghavendraprasath/guardscan](https://github.com/raghavendraprasath/guardscan) | ## 1. 概述 本代码库是 **GuardScan** 的所在地，这是一个 AI 辅助的智能合约漏洞扫描器。该系统结合了： 1. **确定性检测器**，可从 Solidity 源码生成结构化且有证据支撑的发现结果 2. **基于事实根据的 LLM 解释层**，用于对严重程度进行排名、用通俗易懂的语言解释风险并提出修复建议——仅受限于检测器提供的证据 GuardScan 旨在解决嘈杂的专家级静态分析输出与不可信的自由发挥型“AI 审计聊天机器人”之间的实际差距。初步范围侧重于与 AMM / ERC-20 类型合约相关的模式，建立在先前的课程作业（`SimpleAMM` 和 LLM Text-to-SQL 工具）之上。 ## 2. 背景：初学者的关键概念 本节定义了提案中使用的主要术语，以便初涉区块链安全的读者能够跟上进度。 | 术语 | 通俗解释 | |---|---| | **Blockchain** | 一种共享的、只能追加的账本。一旦数据被确认，就很难更改，这就是为什么已部署的 Bug 代价高昂。 | | **Smart contract** | 存储在区块链（通常是以太坊）上的程序，可自动执行有关资金、代币或其他链上状态的规则。 | | **Solidity** | 编写以太坊智能合约最常用的编程语言。GuardScan 会扫描 Solidity 源文件。 | | **EVM** | Ethereum 虚拟机——在兼容以太坊的链上执行智能合约字节码的 runtime。 | | **Transaction** | 一项经过签名的、调用合约或转移价值的操作。这里的安全假设一旦失败，可能会转移真实的资金。 | | **Token / ERC-20** | 以太坊上可替代代币（类似硬币的余额）的通用标准。许多 DeFi 应用都会转移 ERC-20 代币。 | | **AMM (Automated Market Maker)** | 一种智能合约形式的交易所，它根据流动性池公式而不是订单簿来为交易定价（例如，Uniswap 风格的池）。 | | **Liquidity pool** | 锁定在合约中的代币储备，以便用户可以将一种资产兑换为另一种资产。 | | **Immutability** | 部署后，合约代码通常不能像普通的 Web 应用那样进行修补。修复通常需要重新部署和迁移。 | | **Vulnerability / exploit** | 攻击者可利用其窃取资金、冻结资产或获取未经授权控制权的弱点。 | | **Reentrancy** | 一种 Bug 模式，外部调用允许攻击者在状态更新之前重新进入函数，通常会耗尽资金。 | | **Access control** | 关于谁可以调用敏感函数的规则（例如，只有 owner 才能更改关键设置）。 | | **`tx.origin` vs `msg.sender`** | `msg.sender` 是直接调用者；`tx.origin` 是最初的以太坊外部账户。使用 `tx.origin` 进行授权是一种已知的反模式。 | | **Slippage / `minOut`** | 在 swap 中，价格可能会在交易结算前发生变动。最小输出量（`minOut`）检查可保护用户，避免其实际获得的远少于预期。 | | **Static analysis** | 使用规则/启发式方法检查源代码，而无需执行完整的实际攻击。像 Slither 这样的工具就是做这个的；GuardScan 的检测器是该概念的一个小型教学版本。 | | **Detector** | 一种确定性检查，可标记特定模式并返回结构化证据（文件/行号/代码片段）。在 GuardScan 中，检测器是事实来源。 | | **LLM (Large Language Model)** | 能够用自然语言解释文本/代码的 AI 模型。对提高可读性很有用，但如果允许其随意捏造漏洞，则是不安全的。 | | **Grounded explanation** | 限制在检测器已生成的证据范围内的 LLM 响应——仅负责解释并提出修复建议，不捏造新的发现结果。 | | **Severity** | 发现结果的优先级标签（例如 Critical / High / Medium / Info），以便开发者优先修复风险最高的问题。 | | **Audit** | 对合约进行安全审查。GuardScan 不能替代专业的审计；它只是一个供开发者使用的反馈工具。 | **这些部分如何契合 GuardScan：** Solidity 智能合约（通常与 AMM / ERC-20 相关）可能包含影响巨大的 Bug。确定性检测器会找出潜在问题；基于事实根据的 LLM 会用通俗易懂的语言进行解释，以便初学者和忙碌的开发者能更快地根据结果采取行动。 ## 3. 问题陈述 智能合约在部署后是不可变的。诸如 reentrancy、缺失的 access control、不安全的外部调用以及自动做市商 (AMM) 恒等式被破坏等 Bug 可能会导致不可逆转的资金损失。 手动审计仍然很有价值，但速度慢、成本高，并且在开发过程中难以持续运行。现有工具在可用性和信任度方面留有空白： 1. **静态分析工具**（例如 Slither）会产生有用的技术发现，但其输出结果可能非常嘈杂，经验较少的开发者难以快速解读。 2. **纯粹的 LLM 审计员**在捏造代码中不存在的漏洞时，听起来可能会非常自信。 3. 开发者需要一个**快速、可用的反馈循环**：粘贴或上传 Solidity → 结构化的发现结果 → 严重程度排名 → 通俗易懂的英语解释和建议修复方案，且全程有证据支撑。 ## 4. 为什么这个问题很重要 1. **真正的经济影响。** DeFi 和代币合约保护着巨大的价值。历史上的漏洞利用事件表明，微小的编码错误可能会演变成灾难性的损失。 2. **应用安全技能。** 将 Solidity、AMM 和 EVM 安全概念转化为可运行的工具，展现出了超越概念理解的应用层面的掌握能力。 3. **用于风险工作流的可信 AI。** AI 越来越多地被应用于风险、合规和安全场景中。这里困难的工程问题在于可信度：减少幻觉、提供证据支撑，并对严重程度进行排名。 4. **作品集相关性。** 本项目将在 Python、LLM、评估/guardrails 以及风险导向系统方面的经验延伸到了区块链安全工具中——这是 AI 工程、金融科技和安全相关职位的一个绝佳交叉点。 ## 5. 相关工作 ### 5.1 学术论文和研究方向 - **Oyente** — 针对以太坊智能合约的早期符号执行研究 - **Securify** — 针对 Solidity 的语义/合规模式分析方法 - **GPTScan (ICSE 2024)** 及相关的 LLM 漏洞检测研究 — 将 LLM 与程序分析相结合，并记录了误报/幻觉带来的挑战 - **漏洞分类和指南：** SWC Registry、DASP Top 10、Consensys 智能合约最佳实践 ### 5.2 开源和工业界系统 - **Slither (Trail of Bits)** — 被广泛使用的静态分析工具，带有实用的检测器 - **Mythril** — 侧重于符号执行的分析工具 - **Solhint / Aderyn** — linting 和面向 AST 的检查工具 - **OpenZeppelin Contracts** — 安全的构建模块，可降低常见的实现风险 - **专业审计报告语料库** — 用于定性参考，了解发现结果是如何被编写、排名和解释的 ### 5.3 本项目旨在解决的空白 大多数成熟的工具都是为专家审计员优化的。GuardScan 则针对**面向开发者的循环**进行优化：首先进行结构化检测，然后使用受该证据约束的 LLM 进行解释。其新颖之处不在于“取代 Slither”，而是为教育和早期开发工作流提供**可用的、基于事实根据的解释和优先级排序**，并将与 AMM 相关的检查与真实合约联系起来。 ## 6. 提议的解决方案 ### 6.1 产品概念 **GuardScan** 是一个极简的 AI 辅助 Solidity 漏洞扫描器。初步范围侧重于与 AMM / ERC-20 类型合约相关的模式，使用 SimpleAMM 实现及其故意包含漏洞的变体作为主要目标。 ### 6.2 系统架构 ``` Solidity source | |-- Deterministic detectors (heuristics / optional Slither JSON) |-- Finding schema (id, severity, lines, evidence) `-- LLM explainer (OpenRouter) | explain + suggest fix ONLY for listed findings v CLI + simple Web UI report ``` ### 6.3 核心能力 1. 接收 Solidity 文件或粘贴的源码 2. 运行一组精选的检测器（从 4–6 条规则开始），包括： - 敏感函数上缺失 access control - 状态更新前的外部调用（reentrancy 启发式检查） - 没有 slippage 保护的 swap（`minOut` 或等价物） - 不安全的 ERC-20 transfer / allowance 模式（简化版） - `tx.origin` 身份验证反模式 3. 输出按严重程度排名的发现结果：`Critical` / `High` / `Medium` / `Info` 4. 仅使用 LLM 来解释发现结果并提出修复建议，遵循类似于受约束的 Text-to-SQL 系统的防护理念（结构化约束；拒绝没有证据支持的声明） ### 6.4 明确的模拟内容（用于≤5小时原型的范围控制） | 组件 | MVP 处理方式 | |---|---| | 完整的形式化验证 / 符号执行 | 通过启发式算法 + fixture 合约进行模拟 | | 仅针对链上 bytecode 的扫描 | 超出范围（源码优先） | | 广泛的多链支持 | 仅限 Solidity 本地文件 | | 完整的生产级 Slither 集成 | 可选；可能会 stub JSON 发现结果 | ### 6.5 复用先前的课程作业 | 先前的工作 | 在 GuardScan 中的复用 | |---|---| | [SimpleAMM](https://github.com/raghavendraprasath/automated-market-maker) (Solidity, Hardhat, tests/coverage) | 主要扫描目标 + 易受攻击的变体 | | [Block Explorer AI / Text-to-SQL](https://github.com/raghavendraprasath/ai-generated-block-explorer) (OpenRouter, prompt constraints, Streamlit) | Prompt 设计、API 连接、UI/CLI 交付 | | 课程安全主题（reentrancy, access control） | 检测器类别和评估 fixture | ## 7. 最小可行示例（最多 5 小时） ### 7.1 目标 快速演示一条端到端的工作路径，即使分析的深度有意做得比较浅。 ### 7.2 五小时构建计划 | 小时 | 交付物 | |---|---| | 1 | 创建 2–3 个 fixture 合约（较安全的 AMM 代码片段、reentrancy 玩具、缺失的 owner 检查） | | 2 | 构建带有 3–5 个检测器的 Python CLI，用于生成 JSON 发现结果 | | 3 | 实现 OpenRouter prompt：仅解释提供的发现结果；不要捏造新的漏洞 | | 4 | 添加最小的 Streamlit 或 HTML UI：粘贴代码 → 渲染报告 | | 5 | 编写使用文档，截取屏幕截图，准备一次有脚本预演的演示运行 | ### 7.3 原型成功标准 1. 粘贴代码并在大约 30 秒内收到报告 2. 在已知的错误 fixture 上检测出至少一个 true positive 3. 确保 LLM 叙述引用的是检测器的证据，而不是执行无约束的“全面审计” ## 8. 每周计划 | 里程碑 | 目标 | 交付物 | |---|---|---| | **提案** | 7月24日当周 | 此代码库的 README / 提案 URL | | **进度更新** | 7月31日 | 5–10 分钟的进度汇报：扩展的检测器、发现结果的 schema、误报说明、实时扫描演示 | | **平行课程作业** | 7月31日 | SimpleAMM Web3 UI（单独作业）；AMM 仍然是 GuardScan 的主要扫描目标 | | **最终交付** | 8月7日 | 可用的 GuardScan 系统：CLI/UI、检测器集、小型的标注评估套件、包含局限性和相关工作的 README、最终汇报演示 | ### 预期的每周成果 1. **提案周：** 发布提案；完成≤5小时的模拟 MVP；演示 fixtures → 发现结果 → 基于事实根据的 LLM 解释 2. **至 7月31日：** 扩展检测器；强化发现结果的 schema；记录误报说明；实时扫描 SimpleAMM 及易受攻击的变体 3. **至 8月7日：** CLI/UI；组装小型的标注评估集（良好/糟糕的合约）；可选地摄入 Slither JSON；最终确定演示材料 ## 9. 风险与缓解措施 | 风险 | 缓解措施 | |---|---| | LLM 产生幻觉虚构出漏洞 | 检测器是事实来源；LLM 仅解释列出的发现结果 | | 范围蔓延至完整的审计平台 | 限制检测器数量；模拟沉重的分析组件 | | 与 Web3 UI 作业的工作量冲突 | 将最终项目保持在 Python/LLM 轨道上；将 Web3 UI 隔离为单独的交付物 | | 与现有工具相比缺乏新意 | 强调基于事实根据的解释 UX、专注于 AMM 的检查以及客观诚实的评估 | ## 10. 完成定义 一个可用的本地或可通过 Web 访问的系统，该系统能够： 1. 扫描 Solidity 源码以查找一组特定的漏洞 2. 通过基于事实根据的 LLM 返回按严重程度排名的、人类可读的报告 3. 在 AMM 类型的合约上展示出清晰的结果 4. 诚实客观地记录相关工作、局限性和未来的工作 5. 支持每周的进度更新和最终的汇报演示 ## 11. 原型使用说明（≤5小时的 MVP） ### 11.1 目录结构 ``` guardscan/ README.md # proposal + usage (this file) fixtures/ # vulnerable + safer Solidity samples src/ # detectors, finding schema, LLM explainer, scanner ui/app.py # Streamlit report surface tests/ # detector tests cli.py # JSON CLI entrypoint requirements.txt .env.example ``` ### 11.2 设置 ``` python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: # source .venv/bin/activate pip install -r requirements.txt copy .env.example .env # or: cp .env.example .env # 可选：在 .env 中设置 OPENROUTER_API_KEY 以获取实时 grounded explanations ``` ### 11.3 CLI 扫描 (JSON) ``` # Detectors + mock/live explanation python cli.py fixtures/VulnerableVault.sol --pretty --mock-llm # Detectors only python cli.py fixtures/VulnerableAMM.sol --no-explain --pretty # 更安全的 contrast fixture python cli.py fixtures/SaferAMM.sol --pretty --mock-llm ``` ### 11.4 Streamlit UI ``` streamlit run ui/app.py ``` 粘贴 Solidity 代码或加载 fixture，然后点击 **Scan**。如果没有 `OPENROUTER_API_KEY`，解释将在 mock 模式下运行（仍然仅基于检测器的发现结果生成）。 ### 11.5 测试 ``` pytest -q ``` ### 11.6 原型局限性（有意为之） - 启发式检测器（非完整的 Slither / 符号执行） - 仅限源码优先（无仅针对 bytecode 的扫描） - LLM 必须仅解释列出的发现结果；它不会捏造新的问题 - Fixtures 是用于教学演示的程序——请勿部署它们 ## 12. 相关代码库 - [automated-market-maker](https://github.com/raghavendraprasath/automated-market-maker) — SimpleAMM 智能合约（扫描目标） - [ai-generated-block-explorer](https://github.com/raghavendraprasath/ai-generated-block-explorer) — 比特币 Text-to-SQL / LLM 工具模式在此处被复用 ## License MIT License。详见 [LICENSE](LICENSE)。

标签：DLL 劫持, Kubernetes, Solidity, 云安全监控, 加密, 区块链安全, 大语言模型, 智能合约审计, 漏洞扫描器, 逆向工具, 静态分析