blocksharkcom/blockshark

## 功能介绍 BlockShark 会生成候选的漏洞利用代码，**在 Foundry 的真实 EVM 上执行它**，并让链来决定资金是否实际发生了转移——然后保留第一个有效的漏洞利用（支持 N 中取优及自我修复）。 ``` ┌──────────┐ Attacker.sol ┌───────────────┐ pass/fail ┌──────────┐ │ generate │ ───────────────▶ │ execute on │ ────────────▶ │ EVM is │ │ (LLM) │ ◀─── self-repair │ Foundry (fork)│ funds moved?│ judge │ └──────────┘ forge output └───────────────┘ └──────────┘ ``` 由于发现的结果就是一个**有效的概念验证（PoC）**，因此准确率在构建之初就接近 100%。我们优化的指标是**召回率（recall）**——即我们实际捕获了多少可利用的漏洞。每次运行都会打印出我们*自己*的召回率数值，这是实测得出的，而非口头宣称的。 ## 为什么与众不同 - **Oracle 由测试框架（harness）控制。** 模型只负责编写 `Attacker` 合约。判定通过/失败的 `require()` 语句位于每个目标的 `template.sol` 中，因此模型**无法伪造成功**——EVM 才是裁判，而不是 LLM。 - **基于执行验证，而非启发式算法。** 与那些只输出概率的风险扫描器（GoPlus、TokenSniffer、QuickIntel）不同，BlockShark 会返回一个可重现的、已转移资金的 PoC——或者什么都不返回。 - **无 runtime 依赖。** 纯标准库测试框架；目标都是自包含的，且 cheatcodes 以内联方式声明。只要安装了 Foundry，它就能运行。 ## 快速开始 ``` # 前提条件：Foundry (https://getfoundry.sh) 和 Python 3.11+ pip install -e ".[dev]" # 1. 端到端验证 harness + oracle（无需 API key）： blockshark run --mode mock # 2. 真正的自主 exploitation： cp .env.example .env # add your ANTHROPIC_API_KEY source .env blockshark run --mode llm --samples 5 --repairs 2 --jobs 4 # 列出 benchmark： blockshark list ``` ## 基准测试 `targets/` 目录中提供了涵盖四类漏洞的五个目标（mock 模式可以 100% 验证全部五个目标——这是 CI 的回归测试门禁）： | 目标 | 漏洞类别 | 漏洞详情 | |-------------------|----------------------|---------| | `ether_store` | reentrancy | `withdraw()` 在清零余额前发送了 ETH | | `shares_vault` | reentrancy | `redeem()` 在 `unchecked` 减少份额前进行了转账 | | `access_control` | access-control | `setOwner()` 未设权限保护 → 任何人都能夺取所有权并清空资金 | | `price_oracle` | oracle-manipulation | 依赖可被原子操纵的 AMM 现货价格进行借款 | | `delegatecall` | delegatecall | 代理合约 `delegatecall` 到调用者提供的目标 → 所有权被劫持 | ## 文档说明 - [`docs/architecture.md`](./docs/architecture.md) — 循环流程、组件以及由测试框架控制的 oracle 设计 - [`docs/adding-targets.md`](./docs/adding-targets.md) — 几分钟内编写一个新目标（包含 mainnet-fork 相关字段） - [`docs/benchmarking.md`](./docs/benchmarking.md) — 召回率/准确率是如何测量的，以及为什么我们从不宣称“安全” - [`docs/roadmap.md`](./docs/roadmap.md) — 从当前的 MVP → 推理时搜索 → RLVR → 持续监控 ## 项目结构 ``` blockshark/ the package: cli · engine · forge_runner · providers · targets · report src/ vulnerable victim contracts (the benchmark set) targets// manifest.json + template.sol (owns the oracle) + reference_attacker.sol tests/ pytest unit + integration suite results/ one JSON per run: recall, per-bug-class breakdown, attempts, tokens ``` ## 客观范围说明 这是用于**验证/发现的雏形**，而非最终产品。它针对已知存在漏洞的合约运行，以验证整个循环流程并建立召回率基准。对可疑漏洞进行高召回率的*验证*是其在短期内的核心优势；对未标记的 mainnet 合约进行冷启动*发现*，则是我们下一步要攻克的更艰难领域（参见路线图）。目前的准确率是实打实的；覆盖率则是我们要持续拓展的方向。 ## 负责任的使用 BlockShark 是一款**双用途的攻击性安全工具**，仅限用于**已授权的**测试——即您拥有的合约、审计/漏洞赏金活动以及学术研究。任何现实世界中的发现都必须通过**协调披露**（[SECURITY.md](./SECURITY.md), [ETHICS.md](./ETHICS.md)）流程进行处理。 ## 贡献 我们特别欢迎新的漏洞利用目标和漏洞类别——请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。基于 [Apache-2.0](./LICENSE) 授权。

标签：Foundry, Maven, Web3安全, 以太坊, 智能合约审计, 漏洞验证, 自动化利用, 逆向工具