prayingperceptions/bloodhound

# 🐺 BloodHound **自主智能合约安全审计引擎。** 粘贴 GitHub 仓库 URL，选择你的 AI 模型和报告格式，即可获得一份 Code4rena 或 Immunefi 格式的漏洞报告——包括概念验证（PoC）漏洞利用——这一切由 Claude AI 驱动。 ## BloodHound 功能 - **自主审计流水线** —— 获取多达 50 个 Solidity 文件，运行 8 项静态启发式检查，然后将所有内容发送给 Claude 进行深度分析 - **三种 Claude 模型** —— Haiku 4.5（快速/便宜）、Sonnet 4（平衡，默认选项）、Opus 4（最深度分析） - **两种报告格式** —— Code4rena 竞赛审计格式或 Immunefi 漏洞赏金格式 - **实时进度** —— 在每个审计阶段完成时提供实时流式更新（SSE） - **概念验证（PoC）** —— 每个发现都包含 PoC（针对严重/高危级别提供 Foundry 风格的 PoC，针对较低严重级别提供逐步说明） - **下载报告** —— 随时导出完整的 `.md` 审计报告 - **严重性分级** —— 发现的问题被划分为严重、高危、中危、低危、信息性或 Gas 优化 - **基于捐赠的访问机制** —— 每天免费进行 1 次扫描；通过捐赠 ETH 解锁更多次数（通过链上验证） ## 技术栈 - **Runtime**: Node.js 24, TypeScript 5.9, pnpm workspaces - **API**: Express 5（esbuild CJS bundle） - **前端**: React + Vite + Tailwind + shadcn/ui + wouter - **数据库**: PostgreSQL + Drizzle ORM - **AI**: Anthropic Claude 通过 OpenRouter 访问（`openai` SDK，模型 `anthropic/claude-sonnet-4`） - **验证**: Zod (v4), drizzle-zod - **API 契约**: OpenAPI 3.1 → Orval（React Query hooks + Zod schemas） ## 在本地运行 ### 前置条件 - Node.js 24+ - pnpm 9+ - PostgreSQL 数据库 ### 环境变量 | 变量 | 必需 | 描述 | |----------|----------|-------------| | `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | | `SESSION_SECRET` | 是 | Session 签名密钥 | | `OPENROUTER_API_KEY` | 是 | 用于访问 Claude 的 OpenRouter 密钥 | | `GITHUB_TOKEN` | 推荐 | GitHub PAT（将速率限制提升至 5,000 次请求/小时） | ### 设置 ``` # 安装依赖 pnpm install # Push DB schema pnpm --filter @workspace/db run push # 启动 API server (port 来自 $PORT env，proxied 在 /api) pnpm --filter @workspace/api-server run dev # 启动 frontend (proxied 在 /) pnpm --filter @workspace/bloodhound-ui run dev ``` ### 代码生成（在 OpenAPI 规范更改后） ``` pnpm --filter @workspace/api-spec run codegen ``` ## 架构 ### 审计流水线 ``` GitHub API → Solidity parser → 8 heuristic checks → Claude AI → findings + markdown report → DB ``` 1. **GitHub 获取器**（`lib/github.ts`）—— 使用 `GITHUB_TOKEN` 进行身份验证，列出 Solidity 文件，执行 300 文件的仓库大小限制检查，并最多获取 50 个文件 2. **启发式检查**（`lib/heuristics.ts`）—— 8 项静态正则表达式/AST 检查（重入攻击、未检查的调用、访问控制、溢出等） 3. **AI 分析器**（`lib/ai-analyzer.ts`）—— 将合约及启发式检查命中的结果通过 OpenRouter 发送给 Claude；采用 4 重策略的 JSON 提取回退机制以确保可靠性 4. **扫描引擎**（`lib/hunt-engine.ts`）—— 编排整个流水线，并在每个阶段发出 SSE 进度事件 ### 实时进度（SSE） 扫描任务通过 Server-Sent Events 在 `GET /api/hunts/:id/progress` 发出进度事件。前端使用原生的 `EventSource`。内存中的 `Map` 负责分发事件——不支持集群，在服务器重启时会重置。 在服务器重启时，任何仍标记为 `running` 的扫描任务都会自动标记为 `failed`（启动恢复机制）。 ### 契约优先的 API 位于 `lib/api-spec/openapi.yaml` 的 OpenAPI 规范是唯一的真实数据源。Orval 会生成： - React Query hooks + TypeScript 类型 → `lib/api-client-react/src/generated/` - 用于 Express 的 Zod 验证 schemas → `lib/api-zod/src/generated/` 在编辑规范后，请务必运行代码生成。 ## 项目结构 ``` ├── artifacts/ │ ├── api-server/ # Express API (esbuild CJS) │ │ └── src/ │ │ ├── routes/ # hunts + donations routes │ │ └── lib/ # hunt-engine, ai-analyzer, github, heuristics │ └── bloodhound-ui/ # React + Vite frontend │ └── src/ │ ├── pages/ # home (dashboard), hunt-results │ └── components/ # donation-modal, shadcn/ui components ├── lib/ │ ├── api-spec/ # openapi.yaml (source of truth) │ ├── api-zod/ # generated Zod schemas (do not edit) │ ├── api-client-react/ # generated React Query hooks (do not edit) │ └── db/ # Drizzle schema + client └── scripts/ # utility scripts ``` ## 速率限制 - **全局**：每个 IP 每分钟 120 次请求 - **扫描创建**：由捐赠等级系统强制执行（免费每天 1 次；付费等级每周期 30 次） - **GitHub API**：使用 `GITHUB_TOKEN` 时每小时 5,000 次请求；不使用时每小时 60 次请求 ## 许可证 MIT

标签：GNU通用公共许可证, LLM应用, Node.js, Solidity, Web3安全, 智能合约审计, 漏洞扫描