src-hunter fleet

自动化 SRC 漏洞挖掘舰队：多 worker 并行执行、SQLite 持久化状态、Web 面板实时观测。

仅限已获授权的安全测试、研究或演练环境使用。

这是什么

如果你是第一次接触这个项目，可以把它理解成一个“批量跑任务的调度器”：

• 你先准备目标清单
• 脚本把目标拆成很多小任务
• 多个 worker 并行调用 Claude 去执行 playbook
• 结果写进数据库
• Web Dashboard 用来查看进度、失败原因和产出情况

它适合在 Windows + PowerShell 环境里本地运行。

功能概览

• 多 worker 并行跑任务，支持 supervisor 托管与异常拉起
• SQLite 记录任务、事件、worker session 与运行状态
• 支持断点续跑，已完成任务可自动跳过
• Web Dashboard 查看总览、worker、趋势与错误原因
• PowerShell 配置，适合 Windows 本地批量运行

架构

start-fleet.ps1          # 入口：校验环境 → 启动 supervisor → 启动 N 个 worker
supervisor.ps1           # 守护进程：监控 worker 心跳、接收启停指令、异常重启
worker.ps1               # 核心循环：claim 任务 → claude -p → 解析结果 → 写报告
build-buckets.ps1        # 将 scope TSV 导入 SQLite，拆分为 (url × playbook) 任务
prompt-builder.ps1       # 组装 prompt（系统模板 + 规则 + playbook 指导）

dashboard/app.py         # Flask API + 静态页面入口
dashboard/static/        # Dashboard 前端

state/fleet.db           # SQLite：tasks / worker_sessions / task_events
state/tmp/               # 临时文件（stdin/stdout/err、Claude 工作目录）
state/logs/              # worker 和 supervisor 日志
state/supervisor/        # supervisor 命令与状态文件

运行流程

1. build-buckets.ps1 从 butian-scope/scope-annotated.tsv 构建任务库
2. start-fleet.ps1 做启动校验，并拉起 supervisor
3. supervisor.ps1 按目标 worker 数启动 / 维护 worker 进程
4. worker.ps1 从 SQLite claim 任务，调用 Claude 执行 playbook
5. 结果写回数据库；命中 REPORT 时输出 Markdown 报告
6. dashboard/app.py 从数据库和 supervisor 状态文件读取运行态并展示

快速开始

1. 安装前先确认你有这些软件

你至少需要以下环境：

• Windows PowerShell
• Node.js（用于安装 Claude Code CLI）
• Python 3（用于 Dashboard）
• sqlite3.exe
• 已准备 butian-scope/scope-annotated.tsv

如果你还没装 Python，可以先检查：

python --version

如果能看到版本号，例如 Python 3.11.x，说明 Python 已安装。

2. 安装 Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude auth login

说明：

• npm install -g 会全局安装 Claude Code CLI
• claude auth login 会打开登录流程
• 现在这套脚本默认依赖 Claude CLI 已登录的 OAuth 状态

安装完成后可以检查：

claude --version
claude auth status

3. 安装 sqlite3

项目默认使用的 sqlite3 路径是：

C:\msys64\ucrt64\bin\sqlite3.exe

如果你的 sqlite3 不在这个位置，也没关系，后面可以在配置文件里改成你自己的路径。

安装后建议检查一下：

C:\msys64\ucrt64\bin\sqlite3.exe --version

4. 创建 Python 虚拟环境（用于 Dashboard）

如果你是新手，建议一定使用虚拟环境，这样不会把 Python 依赖装到系统全局环境里。

在项目根目录执行：

python -m venv .\dashboard\.venv

激活虚拟环境：

.\dashboard\.venv\Scripts\Activate.ps1

激活成功后，终端前面通常会出现 (.venv)。

然后安装 Dashboard 依赖：

pip install flask

如果后面补了 requirements.txt，也可以改成：

pip install -r .\dashboard\requirements.txt

退出虚拟环境：

deactivate

5. 配置项目

复制模板：

copy .\fleet-config.example.ps1 .\fleet-config.ps1

然后编辑 fleet-config.ps1。当前模板：

@{
  Model          = 'opus'
  WorkerCount    = 8
  MaxTurns       = 50
  MaxRetries     = 3
  TaskTimeoutSec = 1800
  DestBase       = 'C:\Users\NaClO3\Desktop\src-report'
  LeaseTtlSec    = 1800
  CbSkipMax      = 60
  CbSleep        = 60
  Sqlite3Bin     = 'C:\msys64\ucrt64\bin\sqlite3.exe'
  TempDir        = "$PSScriptRoot\state\tmp"
}

建议新手先只关注这几个字段：

• Model：使用哪个模型
• WorkerCount：并行 worker 数量
• MaxTurns：单任务最多允许多少轮
• DestBase：报告输出目录
• Sqlite3Bin：sqlite3 的实际路径

6. 构建任务库

.\build-buckets.ps1 -WorkerCount 8

脚本会从 butian-scope/scope-annotated.tsv 读取目标，为每个 (url × playbook) 组合创建任务。

如果这是你第一次跑，建议先把 WorkerCount 调小一点，比如 2 或 4，先确认流程能跑通。

7. 启动 fleet

.\start-fleet.ps1 -N 8

可选参数：

.\start-fleet.ps1 -N 8 -Model opus -MaxTurns 50
.\start-fleet.ps1 -OnlyWorker 3

启动阶段会校验：

• Claude 登录状态
• sqlite3.exe 是否存在
• butian-scope/scope-annotated.tsv 是否存在
• state/fleet.db 是否存在，不存在时自动调用 build-buckets.ps1

8. 停止 fleet

.\stop-fleet.ps1

该脚本会向 supervisor 发送停止命令，等待优雅退出；超时后再强制结束残留进程。

9. 查看结果

默认报告输出目录：

C:\Users\NaClO3\Desktop\src-report\<日期>\<公司>\<域名>\<playbook>.md

Dashboard

启动 Dashboard

先激活虚拟环境：

.\dashboard\.venv\Scripts\Activate.ps1

再启动：

python .\dashboard\app.py

Dashboard 能看到什么

当前后端提供的主要接口：

• /api/overview：任务总览
• /api/workers：worker 与 session 状态
• /api/reasons：SKIP 原因 / 失败类型统计
• /api/trend：完成趋势

如果 state/fleet.db 中仍有 running 任务，但 supervisor 已停止，Dashboard 会自动把这些孤儿任务重置回 pending。

常见问题

1. claude auth status 失败怎么办？

先重新执行：

claude auth login

确认登录成功后再启动 fleet。

2. sqlite3 not found 怎么办？

说明 fleet-config.ps1 里的 Sqlite3Bin 路径不对。把它改成你本机真实的 sqlite3.exe 路径即可。

3. Dashboard 启动失败怎么办？

先确认你已经：

1. 安装了 Python
2. 创建并激活了虚拟环境
3. 执行过 pip install flask

4. 第一次应该开多少个 worker？

建议先从 2 或 4 开始，确认数据库、Claude 登录和报告输出都正常，再增加到 8 或更高。

许可证与致谢

本项目采用 MIT 协议；同时部分内容参考了 src-hunter-skill，该项目也采用 MIT 协议。

• 本项目许可证：MIT
• 参考仓库：https://github.com/MyuriKanao/src-hunter-skill/
• 参考仓库许可协议：MIT

如后续继续合入更多外部内容，会在这里补充来源说明。

配置说明

参数	默认值	说明
Model	opus	默认模型标识
WorkerCount	8	默认并行 worker 数
MaxTurns	50	单任务最大对话轮数
MaxRetries	3	单任务最大重试次数
TaskTimeoutSec	1800	单任务超时秒数
DestBase	C:\Users\NaClO3\Desktop\src-report	报告输出根目录
LeaseTtlSec	1800	任务租约超时
CbSkipMax	60	熔断阈值：窗口期连续 SKIP 数
CbSleep	60	熔断休眠秒数
Sqlite3Bin	C:\msys64\ucrt64\bin\sqlite3.exe	sqlite3 可执行文件
TempDir	state\tmp	worker 临时目录

Playbook

当前 README 中已知 playbook：

playbook	说明
arbitrary-x-authz	越权 / 未授权访问
rce	远程代码执行
xss	跨站脚本
info-disclosure	信息泄露
oauth-saml-jwt	OAuth / SAML / JWT 认证问题

实际可用 playbook 以 prompts/ 与任务构建逻辑为准。

结果判定

模型任务结果使用 ===RESULT=== 分隔 JSON：

{"verdict": "REPORT", "reason": "", "md_report": "## 漏洞详情\n..."}
{"verdict": "SKIP",   "reason": "NO_FINDING", "md_report": ""}

状态语义：

• REPORT：写出 Markdown 报告
• SKIP：无有效发现，不产出报告
• failed：进程异常、解析失败、超时或达到重试上限

目录结构

src-fleet/
├── start-fleet.ps1
├── stop-fleet.ps1
├── supervisor.ps1
├── worker.ps1
├── build-buckets.ps1
├── prompt-builder.ps1
├── fleet-config.example.ps1
├── butian-rules.md
├── butian-scope/
├── prompts/
├── references/
├── dashboard/
└── state/                   # 运行时状态，通常不应入 git

注意事项

• state/ 是运行时目录，建议保持不入库
• 运行前先确认 Claude CLI 登录状态正常
• 报告目录默认写到桌面，可按需改到独立磁盘目录
• 大规模并发前建议先用少量 worker 验证配置与任务生成是否正常

许可

仅限授权的安全测试使用。