iceberg-deep/bb-sentinel
GitHub: iceberg-deep/bb-sentinel
面向漏洞赏金项目的持续攻击面监控与自动化侦察工具，将资产发现、优先级评分、深度检测和提交报告生成整合为一套完整流水线。
Stars: 0 | Forks: 0
# bb-sentinel
面向漏洞赏金项目的持续攻击面监控。bb-sentinel
可发现您所追踪项目的新子域名和存活主机，并按优先级对它们
进行评分，针对高价值目标运行深度影响探测 —— 在您休息时为您
呈现可直接提交的安全成果。
## 目录
- [功能介绍](#what-it-does)
- [处理流水线](#pipeline)
- [安装说明](#installation)
- [快速开始](#quick-start)
- [配置说明](#configuration)
- [优先级评分](#priority-scoring)
- [深挖探测 (深度扫描)](#rock-turning-deep-scanning)
- [报告编写](#report-writing)
- [带认证的探测](#authenticated-probing)
- [合规性预检](#compliance-pre-flight)
- [目标筛选](#target-curation)
- [CLI 参考](#cli-reference)
- [Webhook 负载](#webhook-payload)
- [运维说明](#operational-notes)
- [合法与合规使用](#legal--ethical-use)
## 功能介绍
- **发现攻击面** —— 协调调度 `subfinder`、`assetfinder`、`crt.sh`、`httpx` 和 `nuclei` 对您的项目域名进行扫描
- **基线差异比对** —— PostgreSQL/SQLite 状态追踪每一个资产，呈现新出现的攻击面
- **发现结果评分** —— 多层级乘数模型（URL 关键词、认证上下文、技术栈、端口、时效性），让高价值攻击面浮出水面
- **狩猎高影响漏洞** —— `rocks` 针对 URL 运行九项针对性探测，以发现暴露的 `.git`/`.env`/actuator/swagger，通过精选的 nuclei 模板发现 SQLi/LFI/RCE/SSRF，以及子域名接管、默认凭据、Tomcat 版本 CVE 匹配、CORS 错误配置等
- **撰写报告** —— `bb-sentinel report` 将扫描输出转换为可直接提交的 Markdown + PDF 文档。针对每个类别的 Jinja 模板会构建漏洞影响说明、列出分类验证步骤，并标记导致项目将漏洞降级为仅作记录的常见陷阱
- **尊重项目规则** —— 合规预检会读取每个项目的策略（包含针对 JS 页面的无头渲染回退机制），并拒绝扫描禁止自动化的项目；跨探测均遵守每个项目的速率限制
- **授权时携带凭据** —— auth 请求头贯穿每个活跃层，并受范围限制，确保 token 在 JS 挖掘期间不会泄露给第三方 CDN
- **影响告警** —— 支持严重性过滤的 webhook 推送；通过阈值控制告警噪音
## 处理流水线
```
┌─────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Target │ │ Compliance │ │ Discovery │
│ curation │───▶│ pre-flight │───▶│ (subfinder, │
│ (bounty-data) │ │ (rules text) │ │ crt.sh, …) │
└─────────────────┘ └────────────────┘ └────────┬───────┘
│
┌──────────────────┐ ┌────────────────┐ ┌▼───────────────┐
│ Webhook alerts │◀───│ Priority │◀───│ Scope filter │
│ (severity-gated)│ │ scoring │ │ (inscope) │
└──────────────────┘ └────────▲───────┘ └────────┬───────┘
│ │
│ ┌────────▼───────┐
│ │ httpx + nuclei│
│ │ (live probes) │
│ └────────┬───────┘
│ │
│ ┌────────▼───────┐
└────────────│ rocks │
│ (9 probes, │
│ OWASP class) │
└────────┬───────┘
│
┌────────▼───────┐
│ report writer │
│ (Markdown/PDF │
│ Jinja per │
│ finding class)│
└────────────────┘
```
## 安装说明
### Docker (推荐用于 VPS)
```
git clone https://github.com/iceberg-deep/bb-sentinel.git
cd bb-sentinel
cp config/programs.example.yaml config/programs.yaml
cp config/global.example.yaml config/global.yaml
./deploy.sh # builds image, brings up Postgres + Redis + sentinel
```
### 本地开发
```
git clone https://github.com/iceberg-deep/bb-sentinel.git
cd bb-sentinel
pip install -r requirements.txt
# PATH 上需要的外部工具：subfinder、assetfinder、httpx、nuclei、inscope
```
### 项目布局
```
bb-sentinel/
├── src/
│ ├── main.py monitor-loop entry point
│ ├── monitor.py per-program scanner + scheduler
│ ├── config.py YAML loader with env-var expansion
│ ├── database.py SQLAlchemy 2.0 async models
│ ├── compliance.py rules-text pre-flight (headless-rendered)
│ ├── scope.py wrapper around tomnomnom/inscope
│ ├── scoring.py priority-score multiplier model
│ ├── rocks.py 9-probe deep-scan toolkit
│ ├── report.py Markdown + PDF report generator (Jinja2)
│ ├── webhooks.py async webhook dispatch
│ ├── cli.py management CLI
│ └── discovery/ per-tool wrappers (subfinder, httpx, nuclei, …)
├── scripts/
│ ├── build_signal_list.py cross-platform target curation
│ └── batch_compliance.py bulk pre-flight checker
├── templates/
│ └── findings/ per-class Jinja2 report templates
├── config/ user config (gitignored)
├── data/ cache, dumps, baselines (gitignored)
└── docker-compose.yml postgres + redis + sentinel
```
## 快速开始
```
# 1. 筛选目标 — 拉取 Bugcrowd/Intigriti/YesWeHack 数据转储，进行排名
python3 scripts/build_signal_list.py
# → data/signal-build-targets.md (排名前 60)
# 2. 将程序添加到 programs.yaml (参见下方的配置)
# 3. 合规性预检 — 自动渲染 JS 页面
bb-sentinel compliance --program
# 4. 扫描 — 运行 discovery + scope-filter + httpx + nuclei tech-detect
bb-sentinel scan --force
# 5. 深度探测 — 对存活 URL 运行 9-probe rocks 工具包
bb-sentinel rocks --program --min-severity medium
# 6. 撰写报告 — 将 rocks JSONL 转换为 Markdown + PDF 文档
bb-sentinel report --program
# → data/-report.md (粘贴到 H1/Bugcrowd 提交表单)
# → data/-report.pdf (适用于接受 PDF 交付物的程序)
# 7. 持续监控
bb-sentinel run # background loop, alerts via webhook on new findings
```
## 配置说明
### `config/programs.yaml`
```
programs:
evilcorp:
enabled: true
domains:
- evilcorp.com
- evilcorp.io
# Scope filter (regex per line; ! prefix = exclude)
inscope_config: /app/config/evilcorp.scope
# Compliance pre-flight — either url OR pasted-rules file
rules_url: https://bugcrowd.com/engagements/evilcorp
# rules_text: /app/config/evilcorp.rules.txt
# Per-program outbound rate cap (matches program-published limits)
rate_limit_rps: 5
# Authenticated probing (env-expanded so secrets stay out of YAML)
auth_headers:
Authorization: "Bearer ${EVILCORP_API_TOKEN}"
Cookie: "session=${EVILCORP_SESSION}"
scan_frequency: 1h
webhooks:
- url: https://hooks.slack.com/services/...
priority_threshold: 10.0
```
### `config/global.yaml`
控制数据库 URL、日志级别、并发数和工具路径。支持
`${VAR}` 和 `${VAR:-default}` 环境变量扩展。
## 优先级评分
`score = base × multipliers`，上限为 **50**。每个信号最多
贡献一个乘数；乘数按固定顺序叠加到基础分数上。Token 集合
位于 [`src/scoring.py`](src/scoring.py)。
| 信号 | 乘数 |
|--------------------------------------------------------------|-----------:|
| **URL 关键词** (`admin`/`api`/`staging`/`dev`/`actuator`/…) | ×3.0 |
| **认证面** (`account`/`auth`/`sso`/`oauth`/`login`/…) | ×2.5 |
| **真实应用技术** (Spring/Django/Rails/Tomcat/Jenkins/…) | ×2.0 |
| **技术栈深度** (检测到 ≥2 个非噪音技术) | ×1.3 |
| **感兴趣端口** (`8080`/`9090`/`3000`/`5000`/`8443`/…) | ×2.5 |
| **时效性** (在最近 6 小时内发现) | ×2.0 |
基础分数为 `0.7`，如果探测返回 2xx/3xx 则 +0.3。
**计算示例：** 刚刚发现的 `api-staging.evilcorp.com`，运行着 Spring Boot +
MySQL，返回 200：
```
base 1.0 × 3.0 (api, staging) × 2.0 (spring)
× 1.3 (stack-depth) × 2.0 (recent)
= 15.60
```
为每个 webhook 设置 `priority_threshold` 以控制告警噪音。阈值
`10.0` 可捕获位于认证面的 dev/staging 环境；`15.0` 仅在
技术栈或多个信号叠加时才会触发捕获。
## 深挖探测 (深度扫描)
如果说启发式评分告诉你*该看哪里*，rocks 则告诉你*该报告什么*。
[`src/rocks.py`](src/rocks.py) 对 monitor 发现的 URL 运行九项针对性探测
并生成包含严重级别和可复制粘贴证据的
`DeepScanFinding` 记录。
| 探测 | 捕获内容 |
|-------|---------|
| **`path-sweep`** | 126 个高价值路径：`.git/HEAD`, `.env*`, `/actuator/heapdump`, `/actuator/env`, `/h2-console`, 暴露的 Swagger/OpenAPI/GraphQL, `/examples/` (Tomcat), 源代码控制目录, CMS 管理路径, 云 IaC 产物。将每个响应与学习到的 404 指纹进行比较，确保 SPA 包装器不会产生误报。 |
| **`backup-file`** | 对于每个存活的 200 URL，探测 `.bak` / `.old` / `~` / `.swp` / `.orig` / `.tmp` / `.backup` / `.save` / `.zip` / `.gz` 变体。捕获编辑器保存和原始备份泄露。 |
| **`method-enum`** | 对每个基础路径发送 `OPTIONS` / `PUT` / `DELETE` / `PATCH` / `TRACE` / `PROPFIND` / `CONNECT` / `DEBUG`。标记提供写方法的 `OPTIONS`、未经身份验证的 PUT/DELETE 写入、暴露的 WebDAV、TRACE-XST。 |
| **`bypass-403`** | 针对每个 403 响应使用头部技巧：`X-Forwarded-For: 127.0.0.1`, `X-Original-URL: /`, `X-HTTP-Method-Override: GET`。状态改变 → 发现漏洞。 |
| **`cors-reflect`** | 向每个 2xx 响应发送 `Origin: https://evil.example.com` 和 `Origin: null`；标记带凭据的反射 (高危) 和带凭据的通配符 (中危)。 |
| **`tomcat-fingerprint`** | 通过 `/docs/` 检测 Tomcat，提取版本，交叉引用 9.x CVE 波段表 (CVE-2025-24813 到 GhostCat)。非破坏性地测试 PUT 可写性 (sentinel-file PUT → GET 验证 → DELETE) —— 可写 + ≤9.0.98 满足 CVE-2025-24813 RCE 前置条件。 |
| **`wayback-historical`** | 从 `web.archive.org/cdx` 拉取历史 URL (查找期间对目标的流量为零)，针对存活主机重新探测感兴趣的路径 (`/admin`, `/api`, `/.git`, `/dump`, …)。呈现常规侦察会遗漏的被遗忘端点。 |
| **`js-secret-mine`** | 获取每个 200 HTML 页面，跟踪 `