vujcec/sc-vuln-llm-vs-tools
GitHub: vujcec/sc-vuln-llm-vs-tools
一个用于比较LLM辅助智能合约审计与传统静态分析工具效果的学术研究框架，支持三种检测工作流的自动化实验与统计评估。
Stars: 2 | Forks: 0
# sc-vuln-llm-vs-tools
用于比较三种智能合约漏洞检测工作流的硕士论文代码库脚手架：
1. **tools-only**（仅工具：Slither + Mythril + 可选 Foundry tests/fuzz）
2. **llm-only**（仅 LLM：GitHub Models chat completions）
3. **hybrid**（混合：LLM 结合工具输出作为上下文）
实验协议集中配置在 `configs/protocol.yaml`，评分依据为 `ground-truth/taxonomy.yaml` 及每个案例的 `case.yaml` 标签。
Ground truth 分类体系及 SWC 映射位于 `ground-truth/taxonomy.yaml`。
## 快速开始（本地）
前置条件：
- Python 3.11+
- Docker（用于 Mythril）
- Foundry (`forge`)
- Slither (`pip install slither-analyzer`)
设置：
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
运行示例案例：
```
python pipelines/run_case.py --mode tools --case EXAMPLE-001
python pipelines/run_case.py --mode llm --case EXAMPLE-001 # requires GITHUB_TOKEN with Models access
python pipelines/run_case.py --mode hybrid --case EXAMPLE-001
python pipelines/score.py
```
输出写入 `outputs///` 并汇总至 `outputs/summary.csv`。
用于论文撰写的其他汇总文件：
- `outputs/summary_by_mode.csv` — 按模式的微平均指标（以及良性误报率）。
- `outputs/summary_by_taxonomy.csv` — 按类别的 precision/recall/F1（以及 SWC 映射 + 描述）。
- `outputs/summary_explained.md` — 描述各列的数据字典。
验证案例结构（快速）：
```
python pipelines/validate_cases.py
```
运行所有案例（所有工作流）：
```
rm -rf outputs
python pipelines/run_all.py --modes tools,llm,hybrid --keep-going
python pipelines/score.py
cat outputs/summary.csv
cat outputs/summary_by_mode.csv
cat outputs/summary_by_taxonomy.csv
cat outputs/summary_explained.md
# RQ4 (自动化代理评分；无人工输入)
python pipelines/ratings.py --auto
python pipelines/ratings.py --merge
cat outputs/summary_by_mode_with_ratings.csv
```
### 重复实验（LLM 随机性 + 混合策略消融）
为评估 LLM/混合模式的随机性并比较 **hybrid-expansive 与 hybrid-conservative**，使用：
```
python pipelines/run_experiment.py --hybrid-policy expansive,conservative --repeats 3 --modes tools,llm,hybrid --keep-going
```
每次运行归档至：
```
experiments///run-XX/outputs/
```
并写入汇总的均值/标准差：
```
cat experiments//aggregate_by_mode.csv
cat experiments//aggregate_by_taxonomy.csv
```
这是论文主要评估（RQ1–RQ3）以及在扩展数据集上进行稳健 RQ4 分析的推荐工作流。
RQ4（小规模子集的人工验证）：
```
python pipelines/ratings.py --init
# 编辑 outputs/ratings_template.csv (每次运行 1–5 评分)
python pipelines/ratings.py --merge
cat outputs/summary_by_mode_with_ratings.csv
```
## Hybrid 证据门控策略
Hybrid 运行是将工具输出包含在上下文中的 LLM 分析。为减少误报，Hybrid 支持通过 `configs/hybrid_policy.yaml` 进行显式证据门控：
- **expansive**：保留所有 LLM 发现（在允许的分类范围内）
- **conservative**：对选定类别（默认：`unchecked-low-level-calls`）要求工具确证，并对仅 LLM 的发现要求证据锚点。
Hybrid 输出包括：
- `outputs/hybrid//findings.normalised.json` — 用于评分的门控后发现
- `outputs/hybrid//findings.suppressed.json` — 被抑制的发现（仅当保守门控抑制了内容时存在）
- `outputs/hybrid//findings.tools.normalised.json` — 工具标准化后的发现（用于审计/调试）
Hybrid 运行元数据写入 `outputs/hybrid//meta.json`，包括：
- `hybrid_policy`（expansive/conservative）
- `hybrid_suppressed_findings`（计数）
## GitHub Actions
提供了三个工作流：
- `.github/workflows/tools-only.yml`
- `.github/workflows/llm-only.yml`
- `.github/workflows/hybrid.yml`
它们调用可复用工作流 `.github/workflows/_run.yml`，安装依赖并将 `outputs/` 作为 artifact 上传。
注意：GitHub Models 需要工作流/作业权限 `models: read`。请参阅 GitHub 文档了解 Models 推理和权限相关内容。
## 添加新案例
创建 `contracts/cases//`，包含：
- `case.yaml`（ground-truth 标签）
- `foundry.toml`
- `src/*.sol`
然后将案例 ID 添加到 `.github/workflows/_run.yml` 的矩阵中并重新运行工作流。
## 数据集扩展（SmartBugs Curated）
SmartBugs Curated 是一个广泛使用的精选数据集，用于评估智能合约分析工具。本代码库包含一个确定性导入器，可将其子集转换为 `contracts/cases/SB-*` 案例。
重要：SmartBugs Curated 在注释中包含显式的漏洞标记（例如 ` ...`）。导入器**会移除这些标记**，以避免标签泄露给 LLM。
将数据集克隆到本代码库旁边（或内部）：
```
git clone https://github.com/smartbugs/smartbugs-curated.git
```
导入确定性切片并生成清单：
```
# 删除旧的导入案例 (可选)
rm -rf contracts/cases/SB-*
python pipelines/ingest_smartbugs_curated.py \
--smartbugs-path ./smartbugs-curated \
--limit 50 \
--overwrite \
--debug
python pipelines/validate_cases.py
# 所选切片记录在此：
cat datasets/smartbugs_manifest.csv | head
```
## 统计评估辅助工具
在生成 `outputs/summary.csv` 后，您可以计算配对 Bootstrap 置信区间（Δmicro-F1）和 McNemar 就绪表：
```
python pipelines/stats_eval.py --summary outputs/summary.csv --modes tools,llm,hybrid
```
## 冻结协议
使用 `docs/frozen_protocol.md` 作为论文评估的确切协议。任何变更都应进行版本控制，并作为有效性威胁加以报告。
标签：DLL 劫持, Foundry, GPT, LLM, Mythril, Python, Slither, SWC注册表, Unmanaged PE, Web3安全, 云安全监控, 区块链安全, 去中心化应用安全, 大语言模型, 安全工具对比, 实验框架, 密钥泄露防护, 形式化验证, 无后门, 智能合约审计, 机器学习安全, 混合分析, 漏洞管理, 请求拦截, 静态分析