0xRayaa/scoping-bee

Scoping Bee 自动化执行安全审计中最关键（且最繁琐）的阶段——初始范围界定。给它一个代码库，你将收到一份以蜜蜂为主题的范围报告，其中包含流程图、复杂度评分、优先攻击清单以及时间估算。 ``` ⬡─────────────────────────────────────────────────────────────⬡ │ │ │ 📥 Source Fetch → 🛡️ Threat Scan → 📊 Analysis → 🐝 Report │ │ │ ⬡─────────────────────────────────────────────────────────────⬡ ``` ## 🔧 安装说明 Scoping Bee 是一组 bash 脚本加上一个 AI 技能定义——无需编译步骤，无需安装包。克隆它并将你的 AI 助手指向它，或者直接运行脚本。 ### 1. 克隆仓库 ``` git clone https://github.com//scoping-bee.git ~/.scoping-bee ``` （或者克隆到你喜欢的任何位置；该路径会通过 `CLAUDE.md` 或技能加载器从你的项目中被引用。） ### 2. 前置条件 | 工具 | 用途 | 安装方式 | |:-----|:----|:--------| | `bash` 4+ | 运行脚本 | macOS: `brew install bash`; Linux: 预装 | | `perl` | 剥离注释 / 统计 nSLOC | macOS/Linux: 预装 | | `find`, `wc`, `grep`, `sed`, `awk`, `od` | 核心 shell 实用工具 | 预装 | | `git` | GitHub 克隆输入 | `brew install git` / apt / dnf | | `curl`, `jq` | 区块浏览器 API 抓取（仅用于地址 / 浏览器 URL 输入） | `brew install curl jq` | | `unzip` | ZIP 归档输入 | 预装 | 威胁情报扫描和分析阶段仅使用上述工具——不需要安装 pip/npm。 ### 3. 接入 AI 助手（可选） **Claude Code（按项目）：** ``` cd /path/to/your/scoping-project mkdir -p .claude cat > CLAUDE.md << 'EOF' # 🐝 Scoping 项目 Use the scoping-bee skill at ~/.scoping-bee for all audit scoping tasks. When given a GitHub URL, ZIP, or contract address, run the full scoping pipeline from SKILL.md. EOF ``` **Cursor / 其他助手：**直接引用 `SKILL.md` 并在你的提示词中传递技能文件夹路径。 ### 4. 环境变量（可选） 仅用于浏览器 / 合约地址输入： ``` export EXPLORER_API_KEY= ``` ### 5. 冒烟测试 ``` bash ~/.scoping-bee/scripts/sloc_counter.sh ~/.scoping-bee --lang solidity # 预期："No source files found"（scoping-bee 本身没有 .sol 文件） bash ~/.scoping-bee/scripts/sloc_counter.sh /path/to/some/contracts ``` 如果打印出 nSLOC，你就准备好了。

### ⬡ 渲染报告 ⬡

## 🖼️ 如何在报告中查看 Mermaid 图表 生成的 `_scope_report.md` 嵌入了 Mermaid 流程图。它们在某些查看器中可以**原生**渲染，而在其他查看器中则需要插件。 | 查看器 | 开箱即用？ | 备注 | |:-------|:---------------------|:------| | GitHub web UI | ✅ 是 | 自 2022 年起在任何 `.md` 文件中原生渲染 | | GitLab web UI | ✅ 是 | 原生渲染 | | VS Code（默认预览） | ❌ 否 | 需要扩展（见下文） | | Cursor | ❌ 否 | 与 VS Code 相同的扩展 | | Obsidian | ✅ 是 | 原生渲染 | | Typora | ✅ 是 | 原生渲染 | | 任何纯文本编辑器 | ❌ 否 | 将带有 ` ```mermaid ` 标记的代码块粘贴到支持 Mermaid 的查看器中 | ### ✅ 推荐：VS Code / Cursor 扩展 安装 **Markdown Preview Mermaid Support**（免费，无需订阅，无需登录）： ``` # VS Code code --install-extension bierner.markdown-mermaid # Cursor cursor --install-extension bierner.markdown-mermaid ``` 然后打开报告并按 `Cmd/Ctrl+Shift+V` 进行预览——图表将内联渲染。 ### ✅ 替代方案：推送到 GitHub 将报告提交到任何 GitHub 仓库（公开或私有）并在 web UI 中打开它——Mermaid 代码块无需任何配置即可渲染。 ### ⚠️ 关于 mermaid.live 的说明 `mermaid.live` 无需账号即可在浏览器中用于快速的临时渲染。只有当你尝试将图表保存或分享到其云端时，它才会提示你登录。对于查看报告，你不需要注册——推荐使用 VS Code 扩展或 GitHub 以获得更流畅的本地工作流。

### ⬡ 作为 AI 技能 ⬡ 当与 AI 编码助手集成时，只需询问： ### ⬡ 功能 ⬡

## 📥 多源输入 接受来自多个来源的审计目标——无需手动设置： ``` # GitHub 仓库 bash scripts/source_fetcher.sh https://github.com/org/repo # 任意区块浏览器上的 Verified contract bash scripts/source_fetcher.sh https://bscscan.com/address/0x1234... # Raw address + chain bash scripts/source_fetcher.sh 0x1234...abcd --chain bsc # 来自客户端的 ZIP 文件 bash scripts/source_fetcher.sh ./contracts.zip # 本地目录 bash scripts/source_fetcher.sh ./src ``` **支持的浏览器：**Etherscan, BSCScan, Polygonscan, Arbiscan, Optimism, Fantom, Avalanche, Base（及测试网） ## 🛡️ 审计前威胁情报扫描 每次范围界定会话都以强制性的 **10 阶段**蜂巢安全扫描开始。不受信任的审计代码库可能包含 shell 注入、网络数据泄露、钓鱼工具包、供应链攻击，以及针对审计员机器的混淆 payload。 ``` Recommended workflow: 1. Fetch source → sandbox environment (VM / Docker / cloud instance) 2. Run threat_intel_scan.sh inside the sandbox 3. If CLEAN ✅ → clone/copy to local machine and proceed with scoping 4. If BLOCKED 🛑 → do NOT move to local. Review findings in sandbox first. ``` ``` # 步骤 1：先在 sandbox 中运行 bash scripts/threat_intel_scan.sh ./target-repo # 步骤 2：只有在获得 CLEAN 结论后，才能在本地继续 bash scripts/sloc_counter.sh ./target-repo ``` ``` ┌─────────────────────────────────────────────────────────┐ │ 🐝 HIVE SECURITY SWEEP — 10 PHASES │ ├─────────────────────────────────────────────────────────┤ │ ⬡ Phase 1 Code Behavior Analysis (HIGH) │ │ ⬡ Phase 2 HTML Fingerprint Matching (MED-HI) │ │ ⬡ Phase 3 Banner & Favicon Analysis (HIGH) │ │ ⬡ Phase 4 Client-Side JS Inspection (MED-HI) │ │ ⬡ Phase 5 Post-Signature Distributor Check (HIGH) │ │ ⬡ Phase 6 Codebase Profile Analysis (MED) │ │ ⬡ Phase 7 Function Purpose Analysis (MED-HI) │ │ ⬡ Phase 8 Dependency Audit (HIGH) │ │ ⬡ Phase 9 Reachability Analysis (MED) │ │ ⬡ Phase 10 OSS Feed & Vuln Check (MED-HI) │ ├─────────────────────────────────────────────────────────┤ │ Verdict: CLEAN ✅ / WARNING ⚠️ / BLOCKED 🛑 │ └─────────────────────────────────────────────────────────┘ ``` ## 🗺️ 代码库复杂度可视化工具 生成 Mermaid 图表，以可视化方式映射代码复杂度、合约关系和攻击面： ``` # 将所有图表生成到 markdown 文件 bash scripts/codebase_visualizer.sh ./src --output complexity_map.md # 仅生成 inheritance 图表 bash scripts/codebase_visualizer.sh ./src --diagram inheritance # 包含测试文件 bash scripts/codebase_visualizer.sh ./src --include-tests --output full_map.md ``` **8 种图表类型：** | # | 图表 | 展示内容 | |--:|:--------|:-------------| | 1 | 继承层级 | 合约的 `is` 链和 trait 实现 | | 2 | 合约间调用图 | 哪些合约调用了哪些合约 | | 3 | 状态变量图 | 状态变量和函数的类图 | | 4 | 访问控制流 | 角色、modifier 和受保护的函数 | | 5 | 外部依赖图 | OpenZeppelin, Solmate, 自定义 import | | 6 | 函数流程 | 入口点 → 内部 → 外部调用 | | 7 | 复杂度热力图 | 每个文件的指标表 | | 8 | 价值流转 | Token 的存款、取款、转账路径 | ## 📊 可配置的审计节奏 工作量估算使用可配置的**每天代码行数**速率： ``` # 默认值：350 nSLOC/天 bash scripts/sloc_counter.sh ./src # 高复杂度代码：300 nSLOC/天 bash scripts/sloc_counter.sh ./src --pace 300 # 简单模式：400 nSLOC/天 bash scripts/sloc_counter.sh ./src --pace 400 ``` ## 🔍 双语言支持 自动检测 Solidity 或 Rust/Anchor 并应用正确的分析： | 功能 | Solidity | Rust/Anchor | |:--------|:---------|:------------| | nSLOC 统计 | 剥离 pragma、import、SPDX | 剥离 use、mod、attribute | | 攻击面 | 24 项 EVM 特定检查 | 18 项 Solana 特定检查 | | 系统映射 | 函数、modifier、事件 | 指令、PDA、CPI | | 框架检测 | Foundry / Hardhat | Anchor / 原生 Solana | ## 🎯 42 项攻击面检查 | EVM (24) | Solana (18) | |:---------|:------------| | 重入、代理模式、身份验证绕过 | 缺少签名者、PDA seed 混淆 | | 预言机操纵、份额膨胀 | CPI 漏洞、类型伪装 | | 闪电贷、精度损失、MEV | 账户关闭、重新初始化 | | 签名重放、Gas 拒绝服务 | 剩余账户、Lamport 操纵 |

### ⬡ 蜂巢结构 ⬡

``` scoping-bee/ ├── 📋 CLAUDE.md # Pipeline instructions ├── 📖 SKILL.md # Core methodology ├── 📄 README.md # This file │ ├── 🍯 references/ │ ├── scope-report-template.md # Bee-themed output template │ ├── attack-surfaces.md # 42 attack surface checklists │ └── complexity-rubric.md # 5-metric scoring rubric │ └── 🔧 scripts/ ├── source_fetcher.sh # Multi-source input fetcher ├── threat_intel_scan.sh # 10-phase threat scanner ├── codebase_visualizer.sh # Mermaid diagram generator └── sloc_counter.sh # Dual-language nSLOC counter ```

### ⬡ 范围界定工作流 ⬡

``` ⬡─────────────────────────────────────────────────────────────⬡ │ │ │ 1. 📥 Source Acquisition │ │ │ GitHub / Explorer / ZIP / Local │ │ │ │ │ 2. 🛡️ Threat Intel Scan (MANDATORY) │ │ │ CLEAN → proceed / BLOCKED → stop │ │ │ │ │ 3. 🔍 Codebase Ingestion │ │ │ Contract inventory, nSLOC, dependencies │ │ │ │ │ 4. 🔀 Flow Diagram & Dependencies │ │ │ Value flow, cross-contract calls, trust map │ │ │ │ │ 5. 🔬 Complexity & Risk Scoring │ │ │ 5-metric weighted score per contract │ │ │ │ │ 6. 🐝 Report Assembly │ │ │ Bee-themed scope document │ │ │ ⬡─────────────────────────────────────────────────────────────⬡ ``` **输出：**一个结构化的 `_scope_report.md`，包含： | 章节 | 内容 | |:--------|:--------| | 🛡️ 威胁扫描 | 蜂巢安全扫描结果 | | 📋 执行摘要 | 协议一览 | | ⏱️ 预估工作量 | 带有复杂度乘数的天数明细 | | 📦 合约清单 | 蜂巢——带有蜜蜂角色的合约 | | 🔀 流程图 | 摇摆舞——价值流转 + 依赖项 | | 🔬 复杂度评分 | 每个合约的加权评分 | | 🎯 审计清单 | 蜂刺区 / 观察区 / 低花粉区 | | 🛠️ 方法论 | 针对每个合约的推荐方法 | | ❓ 待解决问题 | 交给协议团队的事项 |

### ⬡ 复杂度评分 ⬡

每个合约基于 5 项加权指标进行评分： | 指标 | 权重 | |:-------|-------:| | nSLOC | 25% | | 外部集成风险 | 25% | | 状态耦合 | 20% | | 访问控制复杂度 | 15% | | 可升级性风险 | 15% | **风险层级：** ``` 🟢 LOW (1.0–1.5) → Checklist review — Low Pollen 🟡 MEDIUM (1.6–2.5) → Vector scan — Watch Zone 🟠 HIGH (2.6–3.5) → Deep interrogation — Sting Zone 🔴 CRITICAL (3.6–4.0) → Full methodology + PoC — Critical Sting Zone ```

### ⬡ 快速开始 ⬡

### 🔧 独立脚本 ``` # 从 GitHub 获取 bash scripts/source_fetcher.sh https://github.com/org/repo # 从 BSCScan 获取 Verified contract bash scripts/source_fetcher.sh https://bscscan.com/address/0x1234... --api-key YOUR_KEY # 通过 address + chain 获取 bash scripts/source_fetcher.sh 0xAbCd...1234 --chain polygon # 解压 ZIP bash scripts/source_fetcher.sh ./client-contracts.zip --output ./audit-target # 在打开仓库前进行 Threat intel 扫描 bash scripts/threat_intel_scan.sh /path/to/audit/repo # 生成 Mermaid 复杂度图表 bash scripts/codebase_visualizer.sh /path/to/src --output complexity_map.md # 计算 nSLOC 并估算工作量 bash scripts/sloc_counter.sh /path/to/src --pace 350 # 计算 Rust/Solana nSLOC bash scripts/sloc_counter.sh /path/to/programs --lang rust --pace 300 ``` ## License MIT

``` ⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡ 🐝 Built for auditors, by auditors. 🍯 Stop wasting time on manual scoping. ⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡⬡ ```

标签：AI辅助, Solana, Solidity, 代码审计, 安全审计, 智能合约, 自动化分析, 跨站脚本