black0405/gcp_validator_prowler
GitHub: black0405/gcp_validator_prowler
一款通过五种独立方法交叉验证 Prowler GCP 安全扫描结果以有效甄别误报并生成可视化审计证据的验证工具。
Stars: 0 | Forks: 0
# gcp_validator — 交叉验证 Prowler GCP 扫描结果
一个验证工具套件，通过**独立证据**重新检查 Prowler 的 GCP 扫描结果，从而帮助你区分真实问题与误报。对于每一项 Prowler 检查，它最多会运行五种方法，并排报告每项检查的判定结果，同时提供共识结论以及误报/漏报标志。
## 五种验证方法
| # | 方法 | 功能说明 |
|---|--------|--------------|
| 1 | **API** | 对确切属性进行直接的单一资源读取（如 `instances.get()`），获取权威的实时状态。 |
| 2 | **Prowler 副本** | 重新实现 Prowler 确切的通过/失败规则，并链接到该检查的 [Prowler Hub](https://hub.prowler.com/) 页面。即使没有 Prowler 文件，它也能告诉你 Prowler *应该*得出的结论。 |
| 3 | **Logs** | 通过 **Cloud Audit Logs** 进行佐证——例如，最后一次设置数据库标志的配置更改记录。 |
| 4 | **Alternate** | 提供*不同*的信号或 API 路径（例如，使用 `backupRuns.list()` 而不是备份设置；使用分配的 IP 而不是 `ipv4Enabled` 标志）。两个视角之间的差异本身就是一个发现。 |
| 5 | **Exposure** | 仅用于公共暴露检查：实际尝试从互联网访问资源（TCP/TLS 探测）。成功连接即是有力的确认。 |
并非每种方法都适用于所有检查。不适用的方法会返回**带有原因的 N/A**，而不是捏造判定结果。
### 判定结果是如何形成的
- 每种适用的方法都会返回 `PASS` / `FAIL` / `N/A` / `MANUAL` / `ERROR`。
- **Consensus** = *确定性*方法的组合（方法 2 被排除在外，因为它只是镜像 Prowler，会导致比较产生偏差）。混合信号会倾向于保守处理（确认的问题优先于正常的读取结果）。
- **Agreement** 将共识与 Prowler 的发现进行比较：
- `AGREE` — 判定结果一致。
- `LIKELY_FALSE_POSITIVE` — Prowler 判定为 FAIL，而我们的证据显示为 PASS。**← 这正是你要寻找的主要目标。**
- `LIKELY_FALSE_NEGATIVE` — Prowler 判定为 PASS，而我们的证据显示为 FAIL。
- `INCONCLUSIVE` / `NO_PROWLER_FINDING` — 信号不足 / 没有可比较的内容。
## 安装
```
cd gcp_validator
python -m venv .venv && . .venv/bin/activate # (Windows: .venv\Scripts\activate)
pip install -r requirements.txt
```
## 身份验证
该工具只需要**只读**访问权限，并支持三种方式提供凭据
（按优先级匹配第一种）：
```
# 直接传递 service-account JSON 密钥：
python run_all.py --key-file /path/to/sa-key.json --prowler out.ocsf.json
# (如果省略 --project，project 默认为密钥自身的 project_id)
# 或者通过标准 env var：
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
# 或者来自 gcloud 的用户凭据：
gcloud auth application-default login
```
推荐使用的只读角色：`roles/cloudsql.viewer`、`roles/logging.viewer`
（添加 `roles/viewer` 以涵盖未来上线的其他服务）。
## 用法
```
# 所有已实现的检查，与 Prowler OCSF 或 CSV 导出进行比较：
python run_all.py --project MY_PROJECT --prowler prowler-output.ocsf.json -o report.xlsx
# 仅限 Cloud SQL：
python run_all.py -p MY_PROJECT --service cloudsql --prowler out.ocsf.json
# 开启 method-5 internet probe（会建立真实的出站连接）：
python run_all.py -p MY_PROJECT --service cloudsql --enable-exposure-probe
# 列出已实现的内容：
python run_all.py --list
# 单独运行 ONE control（从 gcp_validator 目录）：
python -m checks.cloudsql.cloudsql_instance_public_access -p MY_PROJECT --prowler out.ocsf.json
```
`--prowler` 接受 Prowler 的 **OCSF JSON** (`*.ocsf.json`) 或 **CSV** 导出文件。如果不提供此参数，该工具仍会验证实时的 GCP 状态，并报告每种方法的判定结果（agreement 列将显示 `NO_PROWLER_FINDING`）。
## 输出
生成一个 `.xlsx` 文件，包含一个 **Validation** 工作表（每个资源的每项检查占一行）和一个 **Summary** 工作表。列包括：检查 ID / 服务 / 严重程度 / 标题 / Hub 链接、资源标识、Prowler 状态 + 详情、每种方法的判定结果 + 详情、共识，以及 agreement 标志（带有颜色区分）。`LIKELY_FALSE_POSITIVE` 所在的行会以琥珀色高亮显示。
## 审计证据（截图）
添加 `--evidence-dir DIR`（别名 `--screenshots DIR`）可以写入**针对每个发现的 PNG 证据卡片**——包含检查项、资源、每种方法的 PASS/FAIL、从 API 读取的实际配置值、UTC 捕获时间戳，以及 Cloud Console 的直达链接。Excel 文件也会增加一个带有超链接的 **Console Link** 列。
```
python run_all.py -p MY_PROJECT --prowler out.ocsf.json --evidence-dir ./evidence
# 仅限值得附加到 findings 的例外：
python run_all.py -p MY_PROJECT --prowler out.ocsf.json --evidence-dir ./evidence --evidence-findings-only
```
图像是通过无头模式（Pillow）从工具已收集的数据中生成的，因此它们包含适合作为审计证据的来源信息（API 源 + 时间戳）；如果审查人员需要，该直达链接还可以让你获取实时的控制台截图。
## 覆盖范围
**已实现跨 16 个服务的全部 109 项 GCP 检查**，并接入到同一框架中：
| 服务 | 检查项 | 服务 | 检查项 |
|---------|-------:|---------|-------:|
| compute | 31 | cloudsql | 24 |
| iam | 12 | cloudstorage | 10 |
| logging | 10 | apikeys | 4 |
| dns | 3 | bigquery | 3 |
| kms | 3 | cloudfunction | 2 |
| secretmanager | 2 | dataproc | 1 |
| artifacts | 1 | gemini | 1 |
| gke | 1 | gcr | 1 |
### 需要额外输入或属于尽力而为的检查
有少数控制项无法纯粹通过项目级别、只读的 API 调用来验证。这些控制项的实现非常诚实——它们会运行力所能及的检查，并将其余部分标记为 `MANUAL` / `N/A` 并附带原因，而不是盲目猜测：
- **`compute_public_address_shodan`** — 方法 1/2 需要 `SHODAN_API_KEY`；方法 5 仍会直接探测端口。
- **`cloudstorage_uses_vpc_service_controls`**、**`iam_organization_essential_contacts_configured`**
— VPC-SC 边界和 Essential Contacts 处于组织级别；项目凭据只能看到部分情况（报告为 `MANUAL` / 尽力而为的代理）。
- **`iam_service_account_unused`**、**`iam_sa_user_managed_key_unused`** — “unused”（未使用）需要最后认证的数据，因此方法 3（Cloud Audit Logs）才是真正的信号；方法 1 报告 `MANUAL`。
- **`logging_log_metric_filter_and_alert_*`** — 通过基于日志的指标和 Monitoring 告警策略进行过滤子字符串启发式匹配；如果结果看起来有偏差，请根据你的命名规则验证匹配模式。
- **`gemini_api_disabled`** 及其他服务启用状态检查 — 通过 Service Usage API 进行断言；请根据你的 Prowler 版本在 Hub 页面上确认通过的判定方向。
针对特定方法的说明和确切的断言逻辑位于各个检查文件的 docstring 中，并附带了相应的 Prowler Hub 链接。
## 添加检查
1. 创建 `checks//.py`。
2. 继承 `gcpval.base_check.BaseCheck`（或特定服务的基础类，如
`checks.cloudsql._base.CloudSqlCheck`），设置 `check_id`，实现
`discover_resources()` 以及适用的 `api_check` / `prowler_replica_check`
/ `logs_check` / `alternate_check` / `exposure_check` 方法。
3. 完成了 — `run_all.py` 会自动发现它，并且
`python -m checks..` 可以独立运行它。
标签：GCP, Maven, Prowler, 漏洞验证, 自动化报告, 逆向工具