doctena-org/octorules-aws
GitHub: doctena-org/octorules-aws
这是一个基于 YAML 配置文件管理 AWS WAF v2 Web ACL 规则、规则组及 IP 集的 Python 提供程序。
Stars: 1 | Forks: 0
# octorules-aws
[octorules](https://github.com/doctena-org/octorules) 的 AWS WAF v2 提供程序 — 以 YAML 格式管理 AWS WAF Web ACL 规则、规则组和 IP 集。
## 安装
```
pip install octorules-aws
```
这将安装 octorules（核心）和 octorules-aws。提供程序会被自动发现 — 配置中不需要 `class:`。
## 配置
```
providers:
aws:
region: us-east-1
waf_scope: REGIONAL
rules:
directory: ./rules
zones:
my-web-acl:
sources:
- rules
```
每个区域名称映射到一个 AWS WAF Web ACL 名称。提供程序在运行时将 Web ACL 名称解析为 ID。
### 身份验证
AWS 凭证通过标准的
[boto3 凭证链](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html)
进行解析 — 配置文件中不需要 token。常用选项：
- **环境变量**：`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
- **共享凭证文件**：`~/.aws/credentials`
- **IAM 角色**（EC2、ECS、Lambda）：自动
所需的 IAM 权限：
- `wafv2:GetWebACL`、`wafv2:UpdateWebACL` — 用于阶段规则操作
- `wafv2:ListWebACLs` — 用于区域 ID 解析和区域发现
- `wafv2:GetRuleGroup`、`wafv2:UpdateRuleGroup`、`wafv2:ListRuleGroups` — 用于自定义规则集（规则组）
- `wafv2:GetIPSet`、`wafv2:UpdateIPSet`、`wafv2:CreateIPSet`、`wafv2:DeleteIPSet`、`wafv2:ListIPSets` — 用于列表（IP 集）
### 提供程序设置
以下所有设置均位于提供程序部分下（例如 `providers.aws`）。
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `region` | `AWS_DEFAULT_REGION` 或 `us-east-1` | AWS 区域 |
| `waf_scope` | `AWS_WAF_SCOPE` 或 `REGIONAL` | `REGIONAL` 或 `CLOUDFRONT` |
| `max_retries` | `2` | API 重试次数 |
| `timeout` | `30` | API 超时时间（秒） |
| `wcu_limit` | `1500` | 用于 WA340 lint 检查的 Web ACL WCU 容量。对于具有自定义限制的账户（最高 5,000），请覆盖此值。 |
安全阈值在 `safety:` 下配置（由框架拥有，不转发给提供程序）：
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `safety.delete_threshold` | `30.0` | 可删除的规则最大百分比 |
| `safety.update_threshold` | `30.0` | 可更新的规则最大百分比 |
| `safety.min_existing` | `3` | 阈值生效前的最小规则数 |
## 支持的功能
| 功能 | 状态 | AWS 概念 |
|---------|--------|-------------|
| 阶段规则（4 个阶段） | 支持 | Web ACL 规则 |
| 自定义规则集 | 支持 | 规则组 |
| 列表（IP） | 支持 | IP 集 |
| 列表（regex） | 支持 | Regex 模式集 |
| Web ACL 设置 | 支持 | DefaultAction、ChallengeConfig、CaptchaConfig、TokenDomains、AssociationConfig、CustomResponseBodies |
| Page Shield | 不支持 | — |
| 区域发现 (`list_zones`) | 支持 | 列出 Web ACL |
| 账户级范围 | 不支持 | — |
| 审计 IP 提取 (`octorules audit`) | 支持 | IPSet 引用解析 |
## 阶段映射
| octorules 阶段 | AWS WAF 概念 |
|---|---|
| `aws_waf_custom_rules` | 自定义规则（IP 匹配、地理位置匹配、字节匹配等） |
| `aws_waf_rate_rules` | 基于速率的规则 |
| `aws_waf_managed_rules` | 托管规则组引用 |
| `aws_waf_rule_group_rules` | 规则组引用 |
所有阶段都需要显式指定 `action`（没有默认操作）。
## 自定义规则集（规则组）
AWS WAF 规则组映射到 octorules 自定义规则集。octorules 管理完整的
生命周期：创建、更新规则和删除。
### 管理现有规则组
```
# rules/my-web-acl.yaml
custom_rulesets:
- id: abcd1234-5678-9012-3456-789012345678
name: My Rule Group
phase: aws_waf_custom
rules:
- ref: block-bad-ips
action:
Block: {}
Statement:
IPSetReferenceStatement:
ARN: arn:aws:wafv2:us-east-1:123456789012:regional/ipset/blocked/efgh5678
VisibilityConfig:
SampledRequestsEnabled: true
CloudWatchMetricsEnabled: true
MetricName: BlockBadIPs
```
### 创建新规则组
省略 `id` 字段并添加 `capacity` 以创建新规则组：
```
custom_rulesets:
- name: Block Bad Actors
capacity: 100
phase: aws_waf_custom
rules:
- ref: block-scanner
action:
Block: {}
Statement:
ByteMatchStatement:
SearchString: "BadBot"
FieldToMatch:
SingleHeader:
Name: user-agent
PositionalConstraint: CONTAINS
TextTransformations:
- Priority: 0
Type: LOWERCASE
VisibilityConfig:
SampledRequestsEnabled: true
CloudWatchMetricsEnabled: true
MetricName: BlockScanner
```
`capacity` 是一个 AWS WAF 概念 — 一个不可变的预算（1-5000），用于限制规则组
内的规则复杂度。创建后无法更改。如果需要
更多容量，请删除并使用更高的值重新创建规则组。
**工作原理：**
- `name` 字段是身份键。规则组通过名称在 YAML 和 AWS 之间进行匹配。
- 存在 `custom_rulesets:` 键意味着所有规则组均受管理 — AWS 中存在但 YAML 中不存在的规则组将被计划删除。
- 如果缺少 `custom_rulesets:` 键，则完全忽略规则组。
- `id` 是可选的：现有规则组存在，新规则组不存在。
- 创建后，使用 `octorules dump` 将分配的 `id` 导出回 YAML。
## 列表（IP 集和 Regex 模式集）
AWS WAF IP 集和 Regex 模式集映射到 octorules 列表。在规则文件中添加 `lists` 部分：
```
# rules/my-web-acl.yaml
lists:
- name: blocked-ips
kind: ip
description: "Known bad IPs"
items:
- ip: "1.2.3.4/32"
- ip: "10.0.0.0/8"
- name: bad-ua-patterns
kind: regex
description: "Bad user-agent patterns"
items:
- pattern: "BadBot.*"
- pattern: "EvilCrawler/\\d+"
```
IP 列表（`kind: ip`）映射到 AWS WAF IP 集。Regex 列表（`kind: regex`）映射到 AWS WAF Regex 模式集，并通过 `RegexPatternSetReferenceStatement` 引用。
## Linting
80 条 AWS 特定的 lint 规则（WA 前缀），涵盖结构、操作、语句和跨规则分析：
| 前缀 | 类别 | 规则 |
|--------|----------|-------|
| WA001-WA005, WA010, WA020-WA024, WA154 | 结构与 YAML | 12 |
| WA100-WA102 | 优先级 | 3 |
| WA200-WA201 | 操作类型 | 2 |
| WA156-WA161, WA300-WA343 | 语句深度验证 | 42 |
| WA350-WA357 | 操作参数 | 8 |
| WA400-WA402 | VisibilityConfig | 3 |
| WA158, WA326-WA327, WA340, WA500-WA501, WA520 | 跨规则 | 7 |
| WA600-WA602 | 最佳实践 | 3 |
```
octorules lint --config config.yaml
```
安装 octorules-aws 时会自动注册 lint 规则。有关包含示例的完整规则参考，请参阅 [docs/lint.md](docs/lint.md)。
## 已知限制
- **Web ACL 创建/删除**：octorules-aws 管理现有 Web ACL 内的规则和规则组。创建或删除 Web ACL 必须通过 AWS 控制台、CLI 或 Terraform 完成。
- **并发更新**：规则更新使用 AWS WAF 乐观锁定（LockToken）。过期的锁错误会自动重试（最多 3 次，线性退避）。如果同一个 Web ACL 被多个针对**同一阶段**的写入者同时更新，则最后一个写入者获胜。
- **规则组容量不可变**：AWS WAF 在创建时设置规则组容量。要更改容量，请删除并使用新值重新创建规则组。
## 开发
```
git clone git@github.com:doctena-org/octorules-aws.git
cd octorules-aws
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)。
标签：AWS, AWS WAF, boto3, CloudFront, DevSecOps, DPI, IP集合, octorules, Python, WAF v2, Web ACL, Web防火墙, YAML, 上游代理, 区域资源, 安全库, 安全策略, 安全规则管理, 提示词设计, 无后门, 网络安全, 自动化运维, 规则组, 逆向工具, 隐私保护