redhoundinfosec/scopecheck
GitHub: redhoundinfosec/scopecheck
一款跨平台CLI工具，用于在授权安全评估前验证目标IP和域名是否在授权范围内，生成审计追踪记录以确保合规。
Stars: 0 | Forks: 0
# scopecheck
**在任何攻击行动之前，根据授权的参与范围验证目标。**
```
scopecheck validate 192.168.1.50 10.20.30.40 mail.acme.com
✓ 192.168.1.50 IN SCOPE (matches 192.168.1.0/24)
✗ 10.20.30.40 OUT OF SCOPE
✗ mail.acme.com EXCLUDED (excluded: mail.acme.com)
```
## 功能介绍
scopecheck 是一个跨平台的 CLI 工具，用于检查目标（IP、CIDR、域名）是否属于您授权的参与范围内。它读取 YAML 范围定义文件并据此验证目标，生成清晰的通过/失败输出及审计跟踪记录。
## 适用人群
- 渗透测试人员
- 红队操作员
- 紫队成员
- 安全顾问
- 漏洞赏金猎人
- 任何进行授权安全评估的人员
## 授权使用声明
此工具专为支持**合法、授权的安全测试**而设计。它是一种帮助操作员保持在授权边界内的安全工具。在进行任何安全评估之前，请务必确保您拥有书面授权。
## 不适用的场景
- **不**扫描、探测或与任何目标系统交互
- **不**解析 DNS 名称（纯粹的字符串/CIDR 匹配）
- **不**解析范围文档（PDF、电子邮件、合同）
- **不**替代法律审查或授权流程
- **不**提供 GUI 或 Web 界面
## 安装说明
### 预编译二进制文件
从 [Releases](https://github.com/redhoundinfosec/scopecheck/releases) 下载。
### 从源代码构建
```
git clone https://github.com/redhoundinfosec/scopecheck.git
cd scopecheck
go build -o scopecheck ./cmd/scopecheck/
```
### 交叉编译
```
# Linux
GOOS=linux GOARCH=amd64 go build -o scopecheck-linux-amd64 ./cmd/scopecheck/
# Windows
GOOS=windows GOARCH=amd64 go build -o scopecheck-windows-amd64.exe ./cmd/scopecheck/
# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o scopecheck-darwin-arm64 ./cmd/scopecheck/
```
## 快速开始
```
# 1. 创建 scope 文件
scopecheck init
# 2. 使用您的 engagement 详情编辑 scope.yaml
# 3. 验证 targets
scopecheck validate 192.168.1.50
scopecheck validate --file targets.txt
cat targets.txt | scopecheck validate --stdin
```
## 范围文件格式
```
version: 1
engagement:
name: "Acme Corp Pentest Q1 2026"
id: "RT-2026-001"
start: "2026-01-15"
end: "2026-02-15"
scope:
include:
- "192.168.1.0/24"
- "10.0.0.50"
- "2001:db8::/32"
- "*.acme.com"
- "portal.acme.com"
exclude:
- "192.168.1.1"
- "192.168.1.2"
- "mail.acme.com"
notes: "Authorized window: weekdays 22:00-06:00 EST only"
```
### 支持的目标类型
| 类型 | 示例 | 描述 |
|------|---------|-------------|
| IPv4 地址 | `10.0.0.50` | 单个主机 |
| IPv4 CIDR | `192.168.1.0/24` | 子网范围 |
| IPv6 地址 | `2001:db8::1` | 单个主机 |
| IPv6 CIDR | `2001:db8::/32` | 子网范围 |
| 域名（精确） | `portal.acme.com` | 精确匹配 |
| 域名（通配符） | `*.acme.com` | 所有子域名 |
### 关键规则
- **排除规则始终优先于包含规则**
- 通配符 `*.example.com` 匹配 `sub.example.com`，但**不**匹配 `example.com`
- 域名匹配不区分大小写
- 目标文件中的注释（以 `#` 开头的行）和空行将被忽略
## 命令
### `scopecheck init`
生成范围模板文件。
```
scopecheck init # Creates scope.yaml
scopecheck init --scope engagement.yaml # Custom filename
```
### `scopecheck validate`
根据范围检查目标。
```
# 单个 target
scopecheck validate 192.168.1.50
# 多个内联 targets
scopecheck validate 192.168.1.50 10.0.0.1 app.acme.com
# 来自文件
scopecheck validate --file targets.txt
# 来自 stdin (从其他工具 pipe)
nmap -sL -n 192.168.1.0/24 | awk '/report/{print $5}' | scopecheck validate --stdin
# 用于自动化的 JSON output
scopecheck validate --file targets.txt --format json
# CSV output
scopecheck validate --file targets.txt --format csv
# Verbose (显示 match 详情)
scopecheck validate -v --file targets.txt
# Quiet 模式 (仅 exit code)
scopecheck validate -q --file targets.txt
```
### `scopecheck audit`
查看范围检查的审计跟踪记录。
```
scopecheck audit # Show all entries
scopecheck audit --last 20 # Last 20 entries
scopecheck audit -f json # JSON format
scopecheck audit --clear # Clear audit log
```
## 输出格式
### 文本（默认）
```
scopecheck — Acme Corp Pentest Q1 2026
✓ 192.168.1.50 IN SCOPE (matches 192.168.1.0/24)
✗ 192.168.1.1 EXCLUDED (matches 192.168.1.1)
✗ 10.20.30.40 OUT OF SCOPE
✓ app.acme.com IN SCOPE (matches *.acme.com)
Summary: 2 in scope, 1 excluded, 1 out of scope (4 total)
```
### JSON
```
{
"engagement": "Acme Corp Pentest Q1 2026",
"results": [
{"target": "192.168.1.50", "status": "in_scope", "matched_by": "192.168.1.0/24"},
{"target": "192.168.1.1", "status": "excluded", "matched_by": "192.168.1.1"},
{"target": "10.20.30.40", "status": "out_of_scope", "matched_by": ""}
],
"summary": {"in_scope": 1, "excluded": 1, "out_of_scope": 1, "total": 3}
}
```
### CSV
```
target,status,matched_by
192.168.1.50,in_scope,192.168.1.0/24
192.168.1.1,excluded,192.168.1.1
10.20.30.40,out_of_scope,
```
## 退出代码
| 代码 | 含义 |
|------|---------|
| 0 | 所有目标均在范围内 |
| 1 | 一个或多个目标超出范围或被排除 |
| 2 | 错误（输入无效、文件缺失等） |
## 示例工作流
### 扫描前验证
```
# 从 nmap discovery 生成 target 列表，然后在 full scan 前进行 validate
nmap -sL -n 10.0.0.0/24 | awk '/report/{print $5}' > discovered.txt
scopecheck validate --file discovered.txt || echo "STOP: Out-of-scope targets found"
```
### 自动化测试的 CI/CD 门禁
```
scopecheck validate -q --file targets.txt --format json
if [ $? -ne 0 ]; then
echo "Scope validation failed. Aborting."
exit 1
fi
```
### 参与报告的审计跟踪
```
# Engagement 结束后，导出 audit log 用于 report
scopecheck audit --format json > scope-audit-$(date +%Y%m%d).json
```
## 全局标志
| 标志 | 简写 | 描述 |
|------|-------|-------------|
| `--scope ` | `-s` | 范围文件路径（默认：`scope.yaml`） |
| `--format ` | `-f` | 输出格式：`text`、`json`、`csv` |
| `--quiet` | `-q` | 抑制非必要输出 |
| `--verbose` | `-v` | 显示详细匹配信息 |
| `--no-color` | | 禁用彩色输出 |
| `--no-audit` | | 禁用审计日志记录 |
## 审计日志
默认情况下，每次范围检查都会追加到当前目录下的 `.scopecheck-audit.jsonl` 文件中。每条记录包含：
- 时间戳 (UTC)
- 参与项目名称
- 检查的目标
- 结果 (in_scope, excluded, out_of_scope)
- 匹配的规则
- 使用的范围文件
审计日志使用 JSONL 格式（每行一个 JSON 对象），文件权限设置为 `0600`。
## 限制
- 无 DNS 解析 —— 目标按原样与范围定义进行匹配
- 通配符匹配仅为单级（`*.example.com` 不匹配 `example.com` 本身）
- 不解析范围文档（PDF、DOCX） —— 您必须手动将范围转录为 YAML
- IPv4 映射的 IPv6 地址（例如 `::ffff:192.168.1.1`）不会自动标准化
- v1 版本不支持端口级别的范围限制
## 平台支持
| 平台 | 状态 |
|----------|--------|
| Linux (amd64, arm64) | 支持 |
| Windows (amd64) | 支持 |
| macOS (amd64, arm64) | 支持 |
## 路线图
请参阅 [ROADMAP.md](ROADMAP.md) 查看计划中的功能。
## 安全提示
- 此工具从不接触网络。它是一个纯粹的验证/匹配工具。
- 将其作为接收范围授权和执行工具之间的**检查点**。
- 它不能替代法律审查、合同或授权文档。
- 审计日志提供了检查范围的证据，但并非防篡改的。
## 许可证
MIT 许可证。请参阅 [LICENSE](LICENSE)。
## 贡献指南
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全策略
请参阅 [SECURITY.md](SECURITY.md)。
标签：Bug Bounty, CIDR计算, EVTX分析, Go语言, IP验证, Linux安全, YAML配置, 可自定义解析器, 域名匹配, 安全测试辅助, 文档结构分析, 日志审计, 白名单, 目标确认, 程序破解, 紫队, 网络安全, 范围验证, 防御性安全, 隐私保护