Cloud Armor WAF Patrol MCP

cloudarmor-mcp

English | 日本語

用于巡查 Google Cloud Armor WAF 日志的 MCP 服务 — 按规则汇总拒绝请求、检查家乡地区的误报，以及审核预览（试运行）规则，直接读取 Cloud Logging。

专为每日“WAF 状态正常吗？”巡查而设计：调用一次 daily_brief，即可了解我们拦截了什么、有没有误拦截，以及预览规则是否已准备好晋级。

文档：https://shigechika.github.io/cloudarmor-mcp/

工具

工具	用途
daily_brief	一次调用生成晨间摘要：按规则优先级统计已执行的 DENY、检查家乡地区误报，以及统计预览 DENY
enforce_denies	按规则优先级统计已执行的 DENY 数量
home_region_denies	已执行的 DENY 中，源 IP 地理位置属于你家乡地区的记录 — 任何未标记为已知正常的记录都是潜在误报
preview_denies	预览（试运行）DENY 数量 — 没有请求的预览规则可作为晋级候选
health_check	版本、配置是否存在，以及 Cloud Logging 的最小探测

所有工具均为只读。计数设有硬上限（默认每次查询 2000 条），达到上限的结果会显示为 >= N (capped)，绝不会作为精确总数报告。

设置

1. 最小权限服务账号

创建一个仅具有 roles/logging.viewer 角色的服务账号，并下载密钥。与人工账号不同，服务账号不受组织重新身份验证策略限制，因此无人值守的巡查不会在毫无提示的情况下过期。

gcloud iam service-accounts create waf-log-viewer --project=YOUR_PROJECT
gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member=serviceAccount:waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com \
  --role=roles/logging.viewer
gcloud iam service-accounts keys create key.json \
  --iam-account=waf-log-viewer@YOUR_PROJECT.iam.gserviceaccount.com

2. 安装

pip install cloudarmor-mcp
# or
uv tool install cloudarmor-mcp

3. 环境变量

变量	必需	含义
CLOUDARMOR_PROJECT	是	接收负载均衡器日志的 GCP 项目 ID
GOOGLE_APPLICATION_CREDENTIALS	是	服务账号密钥文件的路径
CLOUDARMOR_BACKEND_SERVICES	否	用于筛选的后端服务名称，以逗号分隔（默认：全部）
CLOUDARMOR_HOME_REGION	否	视为家乡流量的 ISO 地区代码，例如 JP。启用误报检查
CLOUDARMOR_RULES_INI	否	规则 INI 文件的路径（标签和已知正常的优先级，见下文）
CLOUDARMOR_MAX_ENTRIES	否	每次查询获取的最大条目数（默认 2000）

4. 可选的规则 INI

将规则编号从提示词中移除，并为报告添加易于理解的标签：

[rules]
101 = block non-home deep-path crawlers
500 = AutoDiscover probe block
1002 = OWASP LFI protection

[home]
; home-region DENYs on these priorities are expected, not false positives
known_normal_priorities = 500, 600

5. Claude Code（插件）

此仓库同时也是一个单插件市场，因此 Claude Code 可以替你安装服务：

/plugin marketplace add shigechika/cloudarmor-mcp
/plugin install cloudarmor-mcp@cloudarmor-mcp

该插件会启动 uvx cloudarmor-mcp，并读取上文环境变量中介绍的相同变量；请在启动 Claude Code 之前导出这些变量。GOOGLE_APPLICATION_CREDENTIALS 仍须指向你自己机器上实际存在的服务账号密钥文件 — 插件无法随附或获取该文件，因此仅通过插件自身的设置无法完成此服务的全部配置。

运行 Claude Code 的进程的 PATH 中必须包含 uvx — 登录 shell 通常会包含它，但通过 GUI 启动的应用可能不会；如果插件无法启动，请在系统范围内安装 uv。

6. Claude Code（手动）

claude mcp add cloudarmor -- cloudarmor-mcp

并在服务的环境中设置上述环境变量。

7. Codex

codex mcp add cloudarmor -- cloudarmor-mcp

使用 --env KEY=VALUE 传入上述环境变量（放在 -- 之前）。

其他任何能够启动 stdio 服务的 MCP 客户端也可采用相同方式：将 cloudarmor-mcp 设为命令，并在其环境中设置上述环境变量。

命令行

cloudarmor-mcp --version   # print version
cloudarmor-mcp --check     # config + API probe (exit 0 when healthy)
cloudarmor-mcp --brief     # print daily_brief to stdout (cron / smoke tests)

导出单日 DENY 条目（批量）

cloudarmor-mcp deny-export --date 2026-09-22 --tz Asia/Tokyo > out.tmp && mv out.tmp 2026-09-22.json

向 stdout 写入一个 JSON 文档，其中每条 DENY 日志对应一条记录，范围为该日的 日历时间（--tz 指定的 [00:00, 24:00)，默认使用 UTC）：强制执行和预览 策略的判定结果（policy、priority、action、outcome、rule_ids）、源 IP、 Cloud Armor 日志记录的区域代码和 ASN、方法、主机、路径（丢弃查询字符串——仅保留其长度）、状态码、User-Agent（200 个字符）和后端。 --kind both（默认）会通过单次查询获取任一策略判定为 DENY 的条目，因此，同时匹配预览规则 且被拒绝的请求只会出现一次，并包含两个部分的数据。--backend a,b 会覆盖 CLOUDARMOR_BACKEND_SERVICES。

这是本软件包中仅有的两个包含逐请求日志数据的输出之一，另一个是下面的 traffic-export；它面向在同一主机上自行汇总当日数据的操作员批处理任务。文档末尾包含 count、fetched、malformed 和 capped：当 capped 为 true 时，导出在达到 --max-entries 时停止（默认值为 200000；不适用 CLOUDARMOR_MAX_ENTRIES），且只包含当天的前缀数据，按时间从早到晚排列。记录采用流式传输，因此内存用量不会随当日数据量增长；为满足 Cloud Logging 读取配额（每分钟 60 个请求），每次获取页面的间隔至少为 1.2 秒，因此包含 200,000 条记录的一天需要几分钟。尚未结束的日期会被拒绝。请在当地午夜后几分钟运行——Cloud Logging 条目会延迟到达——并先写入临时文件：查询失败时，退出代码为 1，stdout 可能会留下未终止的文档。

导出单日抽样的所有请求（批量）

cloudarmor-mcp traffic-export --date 2026-09-22 --tz Asia/Tokyo --sample 0.01 > out.tmp && mv out.tmp 2026-09-22.json

文档布局和记录字段与 deny-export 相同，但涵盖当天的每个负载均衡器请求——包括允许、拒绝和由 CDN 缓存提供的请求——并通过 Cloud Logging 的 sample(insertId, RATE) 进行抽样（--sample，默认值为 0.01）。抽样依据每条记录的 insertId 进行哈希，因此会均匀分布在全天；每次运行使用相同的采样率都会选中相同的条目。将计数乘以 1 / sample，即可估算当天总量——但 capped 为 true 时除外：条目按时间从早到晚读取，因此达到上限的导出只涵盖当天较早的部分（应降低 --sample 或提高 --max-entries）。每条记录都会增加 cache_hit。如果某个请求未经过后端安全策略评估（例如 CDN 缓存命中），则其 enforced: null，且没有区域代码或 ASN；请使用 cache_hit 而非 enforced 来区分缓存命中。 标头包含 sample，而不是 kind。可用它了解访问者类型——浏览器、爬虫、AI Agent——这些无法通过 DENY 日志查看。deny-export 关于逐请求数据的注意事项同样适用：记录包含合法访问者的地址。

阅读报告

• 按规则统计的强制执行 DENY — 这是常规拦截量。占比出现突然变化时值得留意。
• 本地区域 DENY — 来自您所在国家／地区且被拦截的请求。被拒绝的合法用户和爬虫会显示在这里；恰好来自本地的扫描流量也会显示在这里，因此 known_normal_priorities 列表会将预期规则（例如 AutoDiscover 拦截）排除在可疑列表之外。
• 预览 DENY — 处于试运行模式的规则。随着时间推移，若某条预览规则始终没有本地区域命中，就可以考虑将其提升为强制执行。

许可证

MIT