nirxnjxnCodeS/contract-gaurd
GitHub: nirxnjxnCodeS/contract-gaurd
面向 SUI Move 智能合约的静态安全分析器，结合 Claude AI 增强提供漏洞检测与修复建议，支持 MCP 服务器和 VS Code 扩展两种使用方式。
Stars: 0 | Forks: 0
# move-guard
**SUI Move 智能合约安全分析器** — 静态分析 + Claude AI 增强，以面向 AI 助手的 MCP 服务器和面向本地开发的 VS Code 扩展形式提供。
能够捕获 capability 泄露、缺失的访问控制、未检查的 coin 数量、共享对象生命周期缺陷以及升级回归问题 — 然后会解释*确切*的修复方法。
## 它的功能
```
analyze_move_file vulnerable.move
→ Found 6 issues: 2 critical, 2 high, 1 medium, 1 low
→ Claude: "Remove AdminCap from return type; transfer directly in init() …"
```
```
diff_move_files v1.move v2.move
→ risk_verdict: breaking
→ "Any address can now drain funds — no authentication required."
→ "DO NOT deploy."
```
## 两种使用方式
| 模式 | 适用对象 | 方式 |
| --- | --- | --- |
| **MCP 服务器** | 使用 Claude Code 或任何 MCP 客户端进行 AI 辅助开发 | `npx move-guard` |
| **VS Code 扩展** | 内联分析、升级差异对比、pre-commit 钩子 | 从 VSIX 构建 |
## 快速开始 — MCP 服务器
**1. 设置您的 API 密钥：**
```
cp .env.example .env
# 编辑 .env → ANTHROPIC_API_KEY=sk-ant-...
```
**2. 添加到 Claude Code** (`~/.claude/settings.json` 或 Claude Desktop 配置中)：
```
{
"mcpServers": {
"move-guard": {
"command": "npx",
"args": ["-y", "move-guard"],
"env": { "ANTHROPIC_API_KEY": "" }
}
}
}
```
**3. 询问 Claude：**
## 快速开始 — VS Code 扩展
```
cd vscode-extension && npm install && npm run build
npx vsce package --no-dependencies
code --install-extension move-guard-vscode-0.1.0.vsix
```
在“设置”中搜索 **Move Guard** 以设置您的 API 密钥。
## MCP 工具（共 9 个）
### 静态分析
| 工具 | 功能 |
| --- | --- |
| `analyze_move_file` | 按路径分析 `.move` 文件 |
| `analyze_move_source` | 将原始 Move 源码作为字符串进行分析 |
| `check_package` | 扫描包目录中的每个 `.move` 文件 |
### 升级差异对比
| 工具 | 功能 |
| --- | --- |
| `diff_move_files` | 安全差异对比：旧 `.move` 与新 `.move` 文件 |
| `diff_move_sources` | 功能同上，接收原始源码字符串 |
| `diff_package_upgrade` | 对比整个包目录的差异 |
### 提交时智能分析
| 工具 | 功能 |
| --- | --- |
| `analyze_git_diff` | 针对指定 git 引用范围的安全报告 |
| `analyze_staged_changes` | 分析暂存区的更改（pre-commit 钩子） |
| `generate_pre_deploy_report` | 完整的差异对比 + 静态分析组合 |
**MCP 资源：** `move-guard://docs/checks` — 包含所有检查项及其原理的完整 Markdown 参考文档。
## 静态分析检查
| ID | 严重级别 | 捕获内容 |
| --- | --- | --- |
| `capability_leak` | **critical** | 返回 `AdminCap`、`TreasuryCap`、`UpgradeCap` 等的公共函数 — 任何调用者都可获得提升的权限 |
| `missing_access_control` | **high** | 调用 `borrow_mut` 但没有 capability 参数或发送者检查的 `public entry` 函数 |
| `unchecked_coin_value` | **high** | 使用 `coin::split` / `coin::take` 时附近没有 `assert!` 或边界检查 — 易受粉尘攻击和资金池耗尽影响 |
| `shared_object_deletion` | **critical** | 对共享对象执行 `freeze_object` 或 `object::delete` — 在 SUI 主网上是不可逆的 |
| `clock_dependency` | **medium** | 存在 `&Clock` 参数但未提供合理性说明 — 验证者有 ±2 秒的影响力 |
| `public_transfer_misuse` | **medium** | 对没有 `store` ability 的对象使用 `transfer::public_transfer` — 导致运行时中止 |
## 升级差异检查
| 检查项 | 风险 | 捕获内容 |
| --- | --- | --- |
| 可见性降级 | **breaking** | 函数从 private / `public(friend)` 扩大到了 `public entry` |
| 移除访问控制 | **breaking** | 从现有函数中移除了 `assert!` / capability 参数 |
| 新增未受保护的修改操作 | **high_risk** | 新增了没有身份验证的 `borrow_mut` 调用 |
| 结构体字段变更 | **high_risk** | 增加/删除/重排字段会破坏链上对象布局 |
| 函数被删除 | **high_risk** | 公共函数被删除 — 会导致所有调用方中断 |
| 新增返回 capability 的函数 | **high** | 新增的提权路径 |
| 事件发送被移除 | **medium** | 静默状态更改 — 增加审计难度 |
| 新增访问控制 | **improvement** | 标记为审计追溯的积极安全变更 |
## 提交智能检查
| 检查项 | 捕获内容 |
| --- | --- |
| 引入新风险 | 仅针对新增行的静态发现 — 过滤掉原有问题 |
| 风险已解决 | 在此次提交中被移除的发现 — 追踪安全债务的偿还 |
| Gas：新增循环 | `while`/`loop`/`for..in` — 可能引发 gas 消耗爆炸 |
| Gas：向量增长 | 热路径中的 `vector::push_back` / `vector::append` |
| Gas：动态存储写入 | `dynamic_field::add` / `table::add` — 每次写入的存储成本 |
| 对象模型：共享自有对象 | 对非新创建的对象执行 `share_object` — 属于永久性操作 |
| 对象模型：修改冻结对象 | 在 freeze 附近调用 `borrow_mut` — 必定导致运行时中止 |
| 对象模型：所有权混乱 | 从共享状态中提取后执行 `transfer` |
| 测试覆盖盲区 | 新增了没有关联 `#[test]` 的 `public entry fun` |
## 示例输出
**静态分析 (`analyze_move_file`)：**
```
{
"summary": "Found 6 issues: 2 critical, 2 high, 1 medium, 1 low, 0 info.",
"risk_level": "critical",
"findings": [
{
"id": "CAP-LEAK-29",
"title": "Capability leak in public function 'get_admin_cap'",
"severity": "critical",
"category": "capability_leak",
"line_hint": 29,
"recommendation": "Remove AdminCap from return type. Transfer it to a trusted address inside init() using transfer::transfer(cap, tx_context::sender(ctx)). Gate all admin operations behind a &AdminCap parameter instead."
}
]
}
```
**升级差异对比 (`diff_move_files`)：**
```
{
"risk_verdict": "breaking",
"plain_english": {
"what_broke": "All treasury protection was removed — anyone can now drain funds, create unlimited storage objects, and manipulate balances.",
"should_you_deploy": "Absolutely not. Revert all changes immediately."
}
}
```
## VS Code 扩展
### 命令
| 命令 | 触发方式 |
| --- | --- |
| **Move Guard: Analyze File** | 右键点击 `.move` · 编辑器上下文菜单 · 点击状态栏 |
| **Move Guard: Analyze Package** | 右键点击文件夹 · 命令面板 |
| **Move Guard: Diff Upgrade** | 命令面板 — 先选择旧 `.move`，再选择新 `.move` |
| **Move Guard: Analyze Staged Changes** | 命令面板 — `git diff --cached` |
| **Move Guard: Install Pre-commit Hook** | 命令面板 — 写入 `.git/hooks/pre-commit` |
| **Move Guard: Uninstall Pre-commit Hook** | 命令面板 |
### 状态栏
- `$(shield) Move Guard` — 尚未分析
- `$(shield-check) Move Guard` — 安全 / 低严重级别
- `$(shield-x) Move Guard` *(红色)* — 存在 critical 或 high 级别发现
### 设置
| 设置项 | 默认值 | 描述 |
| --- | --- | --- |
| `moveGuard.anthropicApiKey` | `""` | API 密钥（依次回退到 `ANTHROPIC_API_KEY` 环境变量和 `.env` 文件） |
| `moveGuard.autoAnalyzeOnSave` | `false` | 保存时自动分析 |
| `moveGuard.blockCommitOnCritical` | `true` | 当安装了钩子时，阻止存在 critical 级别发现的提交 |
## Pre-commit 钩子（手动设置）
```
#!/bin/sh
REPORT=$(echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"analyze_staged_changes\",\"arguments\":{\"repo_path\":\"$(pwd)\"}}}" \
| npx move-guard 2>/dev/null)
VERDICT=$(echo "$REPORT" | node -e \
"const d=require('fs').readFileSync('/dev/stdin','utf8');
const r=JSON.parse(d.trim().split('\n').pop());
console.log(JSON.parse(r.result.content[0].text).deploy_recommendation)")
if [ "$VERDICT" = "DO_NOT_DEPLOY" ]; then
echo "[move-guard] BLOCKED: critical security issues in staged .move changes."
exit 1
fi
```
或者通过 VS Code 命令面板使用 **Move Guard: Install Pre-commit Hook**。
## 仓库结构
```
move-guard-workspace/
├── packages/
│ ├── core/ @move-guard/core — shared analyzer (CJS)
│ └── mcp/ move-guard — MCP server (ESM, npx-runnable)
├── vscode-extension/ VS Code extension (CJS)
├── .env.example API key template
└── demo.sh Smoke-test all three tool groups
```
## API 密钥加载顺序
1. `moveGuard.anthropicApiKey` VS Code 设置项 *(仅限扩展)*
2. 工作区根目录中的 `.env`
3. 主目录 (`~/`) 中的 `.env`
4. Shell 环境中已存在的 `ANTHROPIC_API_KEY`
当未找到密钥时，静态分析仍会运行 — AI 增强将被跳过，并在每个发现的 `recommendation` 字段中添加说明。
## 环境变量
| 变量 | 描述 |
| --- | --- |
| `ANTHROPIC_API_KEY` | 用于 Claude AI 增强的 Anthropic API 密钥。完整分析时必需；仅静态分析模式下可选。 |
标签：AI辅助开发, CISA项目, Claude AI, DevSecOps, Git预提交钩子, MCP服务器, MITM代理, Move智能合约, SUI区块链, Web3安全, 上游代理, 云安全监控, 代码安全, 代码差异分析, 共享对象生命周期, 升级回归测试, 威胁情报, 开发者工具, 智能合约审计, 漏洞枚举, 能力泄露, 自动化攻击, 访问控制缺失, 静态分析