pingback-sh/pbscan
GitHub: pingback-sh/pbscan
一款与 PingBack.sh OAST 平台原生集成的自动化盲 SSRF 扫描器，通过精确的注入关联机制实现无回显漏洞的发现与证据捕获。
Stars: 5 | Forks: 0
# pbscan
`pbscan` is an automatic, correlated SSRF/OAST scanner for **authorized security testing**. It uses the https://PingBack.sh API v1 to create a listener, register every injection attempt, obtain the official protocol payload, poll captured evidence, and map each callback back to the exact parameter, body field, or header that caused it.
正常的工作流程**不需要**监听器主机名、监听器仪表盘 token、回调模板或 feed URL。
## 30 秒设置
在 **https://PingBack.sh → My listeners** 中创建一个可撤销的 Pro API token，然后进行一次性配置：
```
pbscan auth --token pba_your_revocable_token --accept-authorized-use
```
之后，扫描只需要一个输入文件：
```
pbscan urls.txt
```
等效形式：
```
pbscan -l urls.txt
cat urls.txt | pbscan
pbscan 'https://target.example/fetch?url=https://example.org'
```
## 自动执行的操作
对于每次扫描，pbscan 会：
1. 验证并解析提供的 URL 或原始请求；
2. 创建一个专用的、可重用的 PingBack 监听器；
3. 通过 `/api/v1/injections.php` 为每个变异创建一条关联的注入记录；
4. 将选定的输入替换为返回的 `payloads.http` 值；
5. 根据并发和速率限制分发目标请求；
6. 使用 `listener_id`、`since_id` 和分页轮询 `/api/v1/hits.php`；
7. 通过 `correlation_id` 匹配每个 hit；
8. 将可恢复的会话、证据、发现和摘要保存在本地。
```
urls.txt
│
▼
mutation engine
│
├── create listener ─────────────► PingBack API v1
│
├── register exact attempt ──────► correlation_id + HTTP/DNS/SMTP/XSS payloads
│
├── send returned HTTP payload ──► authorized target
│
└── poll hits.php ◄────────────── DNS / HTTP / HTTPS callback evidence
│
▼
exact parameter + request + evidence
```
## 功能
- 每次扫描自动创建 PingBack 监听器。
- 通过 PingBack API v1 自动进行关联。
- 查询字符串变异，包括重复的参数。
- 使用 JSON Pointer 路径进行嵌套的 JSON 字符串字段变异。
- `application/x-www-form-urlencoded` 变异。
- 可选的保守路由/header 检查。
- 导入原始 HTTP 请求，并在本地保留 cookie 和授权信息。
- 默认情况下，远程关联记录中的敏感 header 会被脱敏。
- 支持 URL 文件、位置 URL、重复的 `-u` 以及 stdin 管道。
- 并发目标 worker、速率限制、重试、超时、重定向控制和 TLS 控制。
- 为单次注入保留多个回调事件，例如 DNS 后跟 HTTPS。
- 原子化的可恢复会话和延迟回调监控。
- JSONL 证据、按时间顺序的活动日志和机器可读的摘要。
- 用于非 PingBack 或旧部署的传统监听器/feed 模式。
- 无第三方 Go 依赖。
## 安装
### 预编译二进制文件
从 GitHub release 下载适用于 Linux、Windows 或 macOS 的二进制文件，并将其放在您的 `PATH` 中。
### Go install
```
go install github.com/pingback-sh/pbscan/cmd/pbscan@latest
```
### 从源码构建
```
git clone https://github.com/pingback-sh/pbscan.git
cd pbscan
go build -o pbscan ./cmd/pbscan
```
## 认证
API token 存储在：
```
~/.config/pbscan/config.json
```
配置目录以 `0700` 模式创建，文件以 `0600` 模式创建。
验证已保存的连接：
```
pbscan doctor
```
删除本地存储的 token：
```
pbscan logout
```
也支持环境变量模式：
```
export PINGBACK_API_TOKEN='pba_your_token'
export PBSCAN_AUTHORIZED=1
pbscan urls.txt
```
`PBSCAN_CONFIG` 可以指向不同的配置文件。
## 输入模式
### 文件
```
pbscan urls.txt
```
空行和以 `#` 开头的行将被忽略。
### 一个或多个 URL
```
pbscan \
-u 'https://one.example/fetch?url=x' \
-u 'https://two.example/proxy?destination=x'
```
单个 URL 可以是位置参数：
```
pbscan 'https://target.example/fetch?url=x'
```
### Stdin
```
cat urls.txt | pbscan
```
授权的侦察管道：
```
katana -u https://target.example -silent \
| gf ssrf \
| pbscan
```
### 原始 HTTP 请求
```
pbscan --request request.txt
```
对于没有可用 `Host` header 的相对请求目标：
```
pbscan --request request.txt --base-url https://target.example
```
## 变异覆盖范围
### 查询参数
```
GET /fetch?url=one&id=two
```
为 `url` 生成一条关联尝试，并为 `id` 生成另一条。重复的键表示为 `key[0]`、`key[1]` 等。
### JSON body
```
{
"image": {"url": "https://example.org/image.png"},
"webhooks": ["https://example.org/hook"]
}
```
生成如下点：
```
/image/url
/webhooks/0
```
仅对 JSON 字符串值进行变异。
### Form body
```
url=https%3A%2F%2Fexample.org&name=test
```
每个 form 值都会被独立测试。
### Header
Header 检查是可选的（需主动开启）：
```
pbscan urls.txt --headers
```
默认的保守列表：
```
Referer
Origin
X-Forwarded-Host
X-Original-URL
X-Rewrite-URL
Forwarded
Base-URL
```
添加一个明确的 header：
```
pbscan urls.txt --headers --header X-Custom-Callback
```
`Host` 和 `Content-Length` 永远不会被 header 引擎变异。
## 常用选项
```
--label TEXT custom label for the automatically created listener
--threads 10 concurrent target workers, maximum 100
--rate 10 target requests per second
--timeout 12s target request timeout
--retries 1 network retries, maximum 5
--wait 20s continue polling after dispatch
--follow-redirects follow target redirects
--insecure skip target TLS certificate validation
--headers enable header mutation
--header NAME add a header mutation, repeatable
--no-query disable query mutation
--no-body disable JSON/form mutation
--max-attempts 500 safety/API-budget limit; 0 disables it
--dry-run build local attempts without API or target requests
--include-request-secrets include Cookie/Authorization in PingBack correlation evidence
--json JSON-line terminal events
--silent suppress progress output
--fail-on-findings return a non-zero exit code after confirmed callbacks
```
默认的 `500` 次尝试上限为监听器创建和 hit 轮询留出了低于 PingBack 文档记录的默认 API 配额的空间。当您的 API 配额允许时，可以拆分较大的任务或有意提高此限制。
## 请求证据与机密信息
在分发之前，pbscan 会注册一个响应式请求，其中在测试位置包含一个稳定的标记：
```
{{PINGBACK_HTTP_PAYLOAD}}
```
默认情况下，这些 header 在发送到 PingBack 的副本中会被脱敏：
```
Authorization
Proxy-Authorization
Cookie
Set-Cookie
X-API-Key
API-Key
```
真实值仅在本地的尝试/会话文件中可用。仅当您有意希望将这些值与远程关联记录一起存储时，才使用 `--include-request-secrets`。
## 输出
每次扫描会创建：
```
output/pbs-
/
├── activity.log
├── attempts.jsonl
├── results.jsonl
├── findings.jsonl
├── summary.json
└── session.json
```
一次尝试包括本地 ID 和 PingBack 关联 ID：
```
{
"id": "pba-local-scan-00001-random",
"correlation_id": "inj-a1b2c3",
"vector": "query",
"injection_point": "url",
"callback_url": "https://listener.pingback.sh/cb?cid=inj-a1b2c3"
}
```
`200 OK` 的目标响应不算是一个发现。只有当 PingBack 返回带有预期 `correlation_id` 的匹配 hit 时，发现才会被确认。
## 延迟回调
监听器和关联记录在目标请求完成后仍会保留在 PingBack 中。稍后可以通过以下方式恢复轮询：
```
pbscan watch output/pbs-xxxx/session.json
```
自定义持续时间：
```
pbscan watch output/pbs-xxxx/session.json --duration 24h --interval 5s
```
会话会存储最后处理的 hit ID，并使用 `since_id` 恢复，而不是下载完整的历史记录。
## 传统模式
对于旧部署和通用 OAST 服务，手动监听器/feed 配置仍然可用：
```
pbscan urls.txt \
--legacy \
--listener https://abc12345.pingback.sh \
--feed-url 'https://legacy.example/feed'
```
这不是推荐的 PingBack.sh 工作流程。只要存在已保存的 API token 且未提供传统 flag，就会自动选择 API v1 模式。
## 本地测试
```
go test ./...
go test -race ./...
go vet ./...
```
构建所有支持的平台：
```
make cross
```
## 安全与贡献
在贡献扫描器行为或 payload 之前，请阅读 [SECURITY.md](SECURITY.md)、[CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)。
## 许可证
MIT标签：CISA项目, EVTX分析, OAST, SSRF检测, 安全测试, 攻击性安全, 日志审计