manage-firewall

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js"——如果输出消息，请先向用户展示，然后再继续。

管理 Web 应用程序防火墙

为 Power Pages 生产站点配置防火墙。防火墙仅适用于生产站点和受支持的区域——脚本会检测并报告资格问题。规则更改后，边缘传播最多需要一小时。

初始请求： $ARGUMENTS

注意事项

• 网站记录 ID 与门户 ID。 .powerpages-site/website.yml 存储的是网站记录 ID，而不是门户 ID。每个脚本都需要 --portalId。在准备步骤中通过 website.js --websiteId 解析一次。
• 绝不按名称解析。 站点名称可能重复；只有网站记录 ID 是安全的。
• 异步操作。 enable.js 和 disable.js 会轮询，直到状态达到目标值（或超时）。delete-rules.js 会立即返回（202）——通过 get-rules.js 验证。
• 并发操作保护。 B003 表示有另一个启用／禁用操作正在进行。轮询状态，直到操作结束，然后重试。
• 误报的托管规则： 通过规则覆盖项禁用（在 RuleGroupOverrides 中设置 EnabledState: "Disabled"——托管规则字段使用 PascalCase）。
• 优先匹配。 规则按优先级顺序评估。先允许特定地理区域、再默认拒绝的模式，需要在允许规则之后明确添加默认拒绝规则。
• 自定义规则优先级范围：11–65000。 1–10 保留给平台托管规则。
• set-rules.js 仅用于添加／更新。 只发送要创建或修改的规则。服务会合并这些规则；负载中未包含的现有规则不受影响。
• 使用 delete-rules.js 删除规则。 set-rules.js 无法删除规则。始终使用 delete-rules.js --names。
• WAF 状态含义——Created 是唯一表示“已启用”的状态。 防火墙已启用且正在主动过滤时，get-status.js 会返回 value: "Created"（这有悖直觉——API 不会使用 "Enabled"）。其他任何值（Disabled、None、Enabling、Disabling、Failed）都表示不存在生效的策略。必须先调用 get-status.js，只有当 value 为 Created 时才调用 get-rules.js——否则规则端点会返回 500，导致报告中整个防火墙部分被跳过。

工作流

1. 准备工作——定位项目、确认登录状态、识别站点、检查资格
2. 检查防火墙状态——获取状态和规则
3. 选择操作——根据上下文提出建议或提问
4. 应用更改——运行相应脚本并验证
5. 总结并说明后续步骤——展示结果、记录使用情况、提供后续选项

任务跟踪

创建三个分组的任务。开始时将每项标记为 in_progress，完成后标记为 completed。

分组	创建时机	任务
1	开始时	检查准备事项
2	准备工作通过后	检查防火墙状态 · 选择操作（审查模式下跳过）
3	用户确认操作后	应用更改（审查模式下跳过，或未选择更改操作时跳过）· 总结并说明后续步骤（始终执行）

---

1. 准备工作

1.1 定位项目并检测审查模式

使用 Glob 查找 **/powerpages.config.json。如果 $ARGUMENTS 包含 --review <out-dir>，记下输出目录——跳过步骤 3–4，步骤 5 仅写入 JSON。

1.2 解析站点标识符

读取 .powerpages-site/website.yml → 提取 id 字段 → 即为 <WEBSITE_ID>。

如果缺少该字段，说明站点尚未部署。告知用户并建议使用 /deploy-site。停止。不要按名称或 URL 解析。

解析为 portalId：

node "${PLUGIN_ROOT}/scripts/website.js" --websiteId "<WEBSITE_ID>"

记录 Id（portalId）、Type、Name、WebsiteUrl。如果退出代码为 2 → 需要登录（pac auth create 或 az login）。如果为 null → 在此环境中找不到站点。两种情况都应停止。

1.3 资格检查

查看 Type 字段和脚本响应，判断是否符合资格。对于不符合资格的站点（非生产环境、不支持的区域、功能受限），脚本会返回特定错误代码。完整列表请参阅 references/commands.md §“常见错误目录”和 §“区域可用性”。

如果站点不符合资格，请用通俗易懂的语言向用户说明限制，并停止。

---

2. 检查防火墙状态

2.1 获取状态（始终先运行）

node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/get-status.js" --portalId "<PORTAL_ID>"

响应格式为 { "status": "ok", "value": "<state>" }。

• Created — WAF 已启用并正在过滤。继续执行 2.2 以获取规则。
• 任何其他值（Disabled、None、Enabling、Disabling、Failed 等）——WAF 未启用。不得调用 get-rules.js——由于没有可读取的有效策略，规则端点会返回 500。跳过 2.2，并将规则载荷视为空：{ "status": "ok", "body": { "CustomRules": [], "ManagedRules": [] } }。

如果状态响应为 "status": "unsupported"，请告知用户防火墙不可用，并停止。

2.2 获取规则（仅在 WAF 已启用时）

node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/get-rules.js" --portalId "<PORTAL_ID>"

两个脚本都会将完整响应以 JSON 格式输出到 stdout。如果 get-rules.js 返回 "status": "unsupported"，请告知用户防火墙不可用，并停止。

---

3. 选择操作

在审查模式下跳过。

与用户交流时只能使用通俗易懂的语言。绝不要使用 WAF、OWASP、ModSec、规则集、地理封锁、速率限制、ASN、SocketAddr 或规则优先级等词语。

每次 AskUserQuestion 调用都是一次单独调用。等待用户回答后再提出下一个问题。

默认方法

🚦 关卡（计划 · manage-firewall:3.action-choice）： 根据站点当前状态推荐操作，然后询问用户是接受还是另选操作。每次进入第 3 阶段时触发一次——如果用户希望在第 4 阶段应用首项更改后继续进行其他更改，则返回此处。

触发条件： 进入第 3 阶段（仅交互模式——审查模式下跳过）。 询问原因： 错误的防火墙更改会影响所有站点访客；未经用户同意就自动推荐操作，可能会禁用制作者有意添加的有效规则。 取消后果： 无——第 4 阶段尚未触发。

分析站点当前状态（防火墙状态、现有自定义规则、托管规则、区域资格），并推荐最相关的一项操作。通过 AskUserQuestion 呈现推荐：

• 防火墙已关闭 → 建议启用。
• 防火墙已开启，没有自定义规则 → 如果存在明显缺口（例如没有速率限制），建议添加规则。否则，概述当前状态并询问用户是否要添加规则。
• 防火墙已开启，且存在规则 → 概述已配置的内容，并询问用户想要执行什么操作。

如果站点当前状态不需要特定建议，就不要勉强推荐——直接询问用户想要执行什么操作。

不得主动提供会降低安全性的操作（关闭防火墙、移除托管规则、弱化现有规则）。如果用户需要这些操作，他们会主动提出。

选项规则

通过 AskUserQuestion 提供选项时：

• label 限制为 1–5 个词。每个选项都要包含 description。
• 仅当选项代表具体变更（创建、更新或删除规则）时，才包含 preview — 用它展示将应用的配置，以便用户在批准前审核。不要在导航或信息类选项中添加 preview。
• 只显示基于当前状态可执行的选项。省略网站无法使用的功能选项（参见 references/commands.md §「区域可用性」）。
• 仅在确实有基于上下文的理由时标注「（推荐）」。如果没有突出选项，则都不要标注。
• 如果提供的规则类型在网站上已存在，要在 description 中说明 — 包括数量并概述已配置的内容，以便用户决定是添加还是更新。
• 对于基于路径的规则，在已知时引用项目结构中的实际页面路径。仅在没有项目上下文时才使用通用表述。

规则类型后续提问

用户选择「添加规则」后，追问规则类型。遵循相同的选项规则。将回答转换为 set-rules.js 参数 — 不要让用户处理优先级编号和规则命名的细节。规则结构请参阅 references/rule-reference.md。

移除规则

列出当前自定义规则，说明每条规则的作用（通俗表述）、匹配的流量、是阻止还是允许，以及相对于其他规则的优先级。如果移除规则会破坏拒绝/允许模式，请在继续前警告用户。

计划-验证-执行

🚦 关卡（同意 · manage-firewall:3.execute-consent）： 执行任何破坏性 WAF 变更（启用/停用、添加/更新/删除规则）前的最终同意。回显拟议的 JSON 载荷和已显示的验证问题。每项变更都会单独触发 — 每次启用、停用、添加规则、更新规则和删除规则，都是独立的同意流程。

触发条件： 已选择第 3 阶段的操作，且已显示计划和验证结果。 询问原因： 防火墙变更影响环境级设置，并对所有网站访客可见；自动应用可能会阻止合法流量或削弱防护。 取消后果： 无 — API 调用尚未发出；计划和验证结果不会保留。

对于所有规则变更：

1. 计划 — 构建 JSON 载荷，其中仅包含要添加或更新的规则。
2. 验证 — 根据现有规则集检查计划，并显示：
   • 与现有规则的优先级冲突
   • 匹配条件重叠（相同的 matchVariable/operator，且 matchValue 重叠）— 通过先匹配先处理规则解释哪条规则生效
   • 允许规则与阻止规则之间的矛盾 — 标记并解释优先级影响
   • 冗余 — 建议更新现有规则，而不是添加重复规则
3. 执行 — 仅在用户通过 AskUserQuestion 批准后应用：

删除时，继续前显示规则名称以及每条规则当前的作用。

在审核模式下，完全跳过此步骤。

---

4. 应用更改

在审查模式下跳过。

操作	脚本
启用	enable.js --portalId <id>
禁用	disable.js --portalId <id>
添加 / 更新规则	set-rules.js --portalId <id> --data-inline '<json>'
移除规则	delete-rules.js --portalId <id> --names <comma-separated>

运行启用 / 禁用操作时，将 run_in_background: true（异步操作并内置轮询）。

应用之前，仅显示与当前操作相关的说明：

• 启用： 受管规则集会立即生效；在审核之前，部分合法请求可能会被拦截。
• 禁用： 重新启用之前，网站将不受保护。
• 添加 / 更新规则： 传播最多需要一小时。如果规则使用 Allow，请说明即使适用拦截规则，它也会创建例外。
• 删除规则： 匹配的流量将不再被拦截（或允许）。如果该规则是拒绝模式中的 Allow 例外，请警告用户：此后流量将被拦截。
• 禁用受管规则： 将不再检查该攻击类别——请注明类别名称。

完成后，重新运行状态和规则调用，以验证新状态。

---

5. 总结和后续步骤

5.1 审查模式

按照 § 2 中相同的先检查状态、再检查规则的门控逻辑——仅当状态 value 为 Created 时，才能调用 get-rules.js。对于任何其他值，WAF 策略都不存在，规则端点会返回 500；编排器必须直接写入空规则负载，而不能调用脚本。

步骤 A——始终运行状态检查：

node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/get-status.js" --portalId "<PORTAL_ID>" > "<REVIEW_DIR>/firewall-status.json"

步骤 B——根据捕获的 value 进行分支处理：

• 如果 value 为 Created，则获取规则：

  node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/get-rules.js" --portalId "<PORTAL_ID>" > "<REVIEW_DIR>/firewall-rules.json"
  

• 否则（Disabled、None、Enabling、Disabling、Failed 或其他任何值），不要调用 get-rules.js。自行写入空规则负载：

  { "status": "ok", "body": { "CustomRules": [], "ManagedRules": [] } }
  

捕获原始输出后，读取这两个文件，并写入 <REVIEW_DIR>/firewall-annotations.json，用通俗语言描述状态和每条规则（转换脚本不再硬编码这些内容——由你提供）：

{
  "state": {
    "description": "Plain-language explanation of what \"<value>\" means — is the firewall actively filtering requests, or not?",
    "fix": "Optional — include only if the state genuinely needs action."
  },
  "rules": {
    "<RuleName>": { "description": "What this rule does, in plain language.", "fix": "Optional fix if the rule has a genuine issue." }
  }
}

Power Pages WAF 状态语义（编写状态说明时请按以下定义，不要自行杜撰含义）：

• Created — WAF 已启用。防火墙处于活动状态并正在过滤请求。
• Disabled — WAF 未启用，且不存在防火墙策略。网站不受保护。
• None — 从未预配过防火墙策略。面向用户的含义与 Disabled 相同。
• Enabling / Disabling — 操作正在进行；请等待。
• Failed — 上次启用 / 禁用操作失败。

然后运行转换脚本：

node "${PLUGIN_ROOT}/skills/manage-firewall/scripts/transform-firewall.js" \
  --statusFile "<REVIEW_DIR>/firewall-status.json" \
  --rulesFile  "<REVIEW_DIR>/firewall-rules.json" \
  --annotations "<REVIEW_DIR>/firewall-annotations.json"

将转换脚本的标准输出写入 <REVIEW_DIR>/manage-firewall.json 并停止。转换脚本会输出 { status, findings }；编排技能负责展示内容。

5.2 呈现摘要

以通俗语言总结：防火墙开启 / 关闭状态、规则数量、所做更改以及重要的安全缺口。

5.3 记录技能使用情况

参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

使用 --skillName "ManageFirewall"。

5.4 提供后续建议

如果根据网站经验证的操作后状态存在自然的后续操作，请提出建议。不要提出会降低安全性的操作。如果没有有意义的后续操作，请结束该技能——不要为了提问而提问。

约束

• 通俗易懂 — 不得对用户使用技术术语。使用日常语言；仅在用户询问时解释技术名称。
• 资格判定 — 对不符合资格的网站（非生产环境、地区不受支持）必须立即停止操作。脚本会检测这些情况 — 请阅读 references/commands.md 了解完整的错误目录。
• 后台操作 — 启用和停用必须通过 run_in_background 执行。
• 只发送变更内容 — set-rules.js 负载只能包含新增或修改的规则。
• 规则命名 — 使用 PascalCase，且只能包含字母和数字（例如，BlockCountries、AllowOfficeIP）。
• 不使用公司名称 — 规则示例中使用通用名称。
• 结合上下文进行交互 — 每个问题、选项、后续提问和说明都必须反映网站的当前状态：
  • 切勿提供不适用的选项（例如，没有规则时提供“移除规则”）。
  • 提供添加新规则的选项时，提及已有的同类型规则。
  • 如果项目中已知网站页面路径，描述中应引用实际路径。
  • 展示计划前，检查新规则是否与现有规则冲突、重叠、矛盾或重复。
  • 只展示与当前操作相关的说明。
  • 切勿主动建议降低防护级别。
• 预览仅用于审查变更 — 仅在代表用户需要批准的具体变更的选项中加入 preview。导航或信息类选项中不要加入。

参考资料

• references/commands.md — 脚本标志、响应格式、错误目录、地区可用性。脚本返回非零退出代码时，阅读“常见错误目录”一节。进行资格检查时，阅读“地区可用性”一节。
• references/rule-reference.md — 自定义规则的字段级架构、匹配条件、托管规则覆盖项、匹配变量、运算符和优先级区间。制定规则计划时阅读。