doctena-org/octorules-google
GitHub: doctena-org/octorules-google
这是一个基于 YAML 的 Google Cloud Armor 策略管理工具，通过 octorules 框架实现 WAF 规则、速率限制及安全策略的自动化配置与校验。
Stars: 1 | Forks: 0
# octorules-google
[Octorules](https://github.com/doctena-org/octorules) 的 Google Cloud Armor 提供程序 — 以 YAML 格式管理 Cloud Armor 安全策略规则。
## 安装
```
pip install octorules-google
```
这将安装 octorules（核心）、octorules-google 和
[cel-python](https://pypi.org/project/cel-python/)，用于在 linter 中进行
CEL 表达式验证。该提供程序会被自动发现 — 配置中不需要 `class:`。
## 配置
```
providers:
google:
project: my-gcp-project
rules:
directory: ./rules
zones:
my-security-policy:
sources:
- rules
```
每个区域名称映射到一个 Cloud Armor 安全策略名称。提供程序
在运行时解析策略名称。
### 身份验证
身份验证使用
[Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
— 配置文件中不需要 token。常用选项：
- **`gcloud auth application-default login`** — 用于本地开发
- **Service account key**：将 `GOOGLE_APPLICATION_CREDENTIALS` 设置为 JSON 密钥路径
- **Workload Identity** (GKE, Cloud Run)：自动进行
所需的 IAM 权限：
- `compute.securityPolicies.get`, `compute.securityPolicies.update` — 用于规则操作
- `compute.securityPolicies.list` — 用于区域发现
- `compute.securityPolicies.addRule`, `compute.securityPolicies.removeRule` — 用于规则变更
### 提供程序设置
以下所有设置均位于提供程序部分下（例如 `providers.google`）。
| Key | Default | Description |
|-----|---------|-------------|
| `project` | `GCLOUD_PROJECT` env var | GCP project ID (required) |
| `timeout` | `30` | API timeout in seconds |
安全阈值在 `safety:` 下配置（由框架拥有，不转发给提供程序）：
| Key | Default | Description |
|-----|---------|-------------|
| `safety.delete_threshold` | `30.0` | Max % of rules that can be deleted |
| `safety.update_threshold` | `30.0` | Max % of rules that can be updated |
| `safety.min_existing` | `3` | Min rules before thresholds apply |
## 支持的功能
| Feature | Status | Notes |
|---------|--------|-------|
| Phase rules (4 phases) | Supported | Security policy rules |
| Policy settings | Supported | Adaptive protection, DDoS config, default rule action |
| Automatic tier detection | Supported | Detects `standard`, `plus`, or `enterprise` from policy config (no manual setting needed) |
| Custom rulesets | Not supported | — |
| Lists | Not supported | Use inline IP ranges in match config |
| Page Shield | Not supported | — |
| Zone discovery (`list_zones`) | Supported | Lists security policies |
| Account-level scopes | Not supported | — |
| Audit IP extraction (`octorules audit`) | Supported | `src_ip_ranges` + `inIpRange()` CEL |
## Phase 映射
| octorules phase | Cloud Armor concept |
|---|---|
| `gcloud_armor_custom_rules` | Custom rules (IP match, geo match, CEL expressions) |
| `gcloud_armor_rate_rules` | Rate-limiting rules (throttle / rate_based_ban) |
| `gcloud_armor_preconfigured_rules` | Preconfigured WAF rules (OWASP ModSecurity, etc.) |
| `gcloud_armor_redirect_rules` | Redirect rules (302 response) |
规则通过其整数 **priority**（在 octorules 中映射为 `ref`）进行标识。所有 phase 都需要显式指定 `action`（没有默认 action）。
## 规则格式
Cloud Armor 规则使用与其他提供程序不同的结构。`ref` 字段映射到规则的整数 priority：
```
# rules/my-security-policy.yaml
gcloud_armor_custom_rules:
- ref: "1000"
description: "Block known bad IPs"
action: deny(403)
match:
versioned_expr: SRC_IPS_V1
config:
src_ip_ranges:
- "1.2.3.4/32"
- "5.6.7.0/24"
- ref: "2000"
description: "Rate limit API endpoints"
action: throttle
match:
expr:
expression: "request.path.startsWith('/api/')"
rate_limit_options:
conform_action: allow
exceed_action: deny-429
rate_limit_threshold:
count: 100
interval_sec: 60
gcloud_armor_preconfigured_rules:
- ref: "3000"
description: "OWASP SQL injection protection"
action: deny(403)
match:
expr:
expression: "evaluatePreconfiguredWaf('sqli-v33-stable')"
```
### CEL 表达式
Cloud Armor 使用 [CEL (Common Expression Language)](https://cloud.google.com/armor/docs/rules-language-reference) 进行高级匹配表达式。示例：
```
# 基于 IP 的匹配
match:
expr:
expression: "inIpRange(origin.ip, '10.0.0.0/8')"
# 基于 Header 的匹配
match:
expr:
expression: "request.headers['user-agent'].contains('BadBot')"
# 基于地理位置的匹配
match:
expr:
expression: "origin.region_code == 'US'"
```
## Linting
77 条 Cloud Armor 专用 lint 规则（GA 前缀），涵盖结构、表达式、操作、速率限制、重定向、子结构验证和跨规则分析：
| Prefix | Category | Rules |
|--------|----------|-------|
| GA001-GA006, GA020 | Structure | 7 |
| GA100-GA108 | Priority / cross-rule | 7 |
| GA200-GA201 | Action | 2 |
| GA300-GA327 | Match / expression / CEL / sub-structure | 22 |
| GA400-GA433 | Rate limit / redirect / action params | 32 |
| GA500-GA503 | Best practice | 4 |
| GA600-GA602 | Preview / catch-all | 3 |
```
octorules lint --config config.yaml
```
安装 octorules-google 时会自动注册 lint 规则。CEL 表达式验证使用 [cel-python](https://pypi.org/project/cel-python/)。有关包含示例的完整规则参考，请参阅 [docs/lint.md](docs/lint.md)。
## 已知限制
- **非原子更新：** Cloud Armor 不支持原子批量规则替换。`put_phase_rules` 会就地修补现有规则，添加新规则，然后移除过时规则 — 因此策略中的规则绝不会*少于*预期数量。每次 API 调用都会针对瞬时错误使用指数退避进行重试。如果重试后操作失败，则会记录部分进度，下一次同步将进行协调。
- **策略创建/删除：** octorules-google 管理现有安全策略内的规则。创建或删除策略（以及将其附加到后端服务）应通过 `gcloud` 或 Terraform 完成。
- **策略设置需要扩展。** 策略级设置（`adaptive_protection_config`、`advanced_options_config`、`ddos_protection_config`、`default_rule_action`、`recaptcha_options_config`）通过 `gcloud_armor_policy_settings` 扩展进行管理。如果未启用扩展，这些设置应通过 `gcloud` 或 Terraform 进行管理。
## 开发
```
git clone git@github.com:doctena-org/octorules-google.git
cd octorules-google
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ln -sf ../../scripts/hooks/pre-commit .git/hooks/pre-commit
```
## 许可证
Apache License 2.0 — 请参阅 [LICENSE](LICENSE)。
标签：API集成, CEL, DevSecOps, GCP, Google Cloud Armor, IAM权限, Octorules, Python, WAF, Workload Identity, YAML, 上游代理, 可观测性, 安全库, 安全策略, 安全防护, 提示词设计, 无后门, 网络安全, 自动化运维, 规则管理, 逆向工具, 隐私保护