awoooi/docs/security/PORT-FIREWALL-CHANGE-EVIDENCE-ACCEPTANCE.md

# IwoooS 端口 / 防火牆變更證據驗收

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-15 |
| 狀態 | `change_evidence_acceptance_ready_no_runtime_action` |
| 工具 | `scripts/security/port-firewall-change-evidence-acceptance.py` |
| Snapshot | `docs/security/port-firewall-change-evidence-acceptance.snapshot.json` |
| Source acceptance | `docs/security/ssh-network-owner-response-acceptance.snapshot.json` |
| runtime gate | `0` |

## 1. 目的

本文件承接 SSH / Firewall / Network Access owner response acceptance，把端口關閉、端口開放、防火牆規則、NodePort、NetworkPolicy、WireGuard 與 host access 類變更轉成 evidence acceptance 只讀帳本。

這層專門補上事故型控管缺口：未來若發生端口被關閉、agent route 斷線、公開入口不可達、monitoring exporter 不通或 NodePort / firewall policy 被改動，必須先收集「誰改、為什麼、影響哪裡、怎麼回復、怎麼驗證、是否已同步其他產品」的脫敏證據，不能只靠 UI 卡片或口頭說明。

這不是 SSH 授權、不是 live firewall read、不是 firewall change、不是 port close / open、不是 route smoke、不是 host restart，也不是 runtime gate。

## 2. 摘要

| 指標 | 目前值 | 說明 |
|------|--------|------|
| source acceptance candidate | `16` | 來源為既有 SSH / network owner response acceptance |
| change evidence candidate | `14` | 聚焦端口、防火牆、NodePort、NetworkPolicy、WireGuard、deploy SSH 與 sudo / alert action surface |
| write-capable change evidence candidate | `6` | CI deploy SSH、monitoring deploy、sudoers、alert action catalog |
| policy / exposure candidate | `5` | NetworkPolicy、NodePort、WireGuard exposure 相關候選 |
| change evidence field | `40` | evidence 欄位總數，已包含事故嚴重度、恢復時間、服務健康影響與通知 refs |
| required evidence field | `21` | change / incident evidence 必填欄位 |
| reviewer check | `21` | actor、scope、before/after、impact、health、notification、rollback、post-check 與 no-runtime 檢查 |
| outcome lane | `9` | waiting、quarantine、reject、supplement、review、incident backfill、emergency backfill、ledger-only、runtime gate |
| blocked action | `28` | SSH、firewall、port、NodePort、NetworkPolicy、WireGuard、route smoke、reload、restart、secret、runtime gate 與事故誤收斂等 |
| change evidence received / accepted | `0 / 0` | 尚未收到或驗收 |
| firewall / port change authorized | `0 / 0` | 不改防火牆，不開關端口 |
| runtime gate / action button | `0 / 0` | 不提供操作入口 |

## 3. Evidence Candidate 範圍

| Candidate | 類型 | 範圍 | 驗收焦點 |
|-----------|------|------|----------|
| `port_firewall_change_evidence:ansible_inventory_ssh_targets` | SSH target inventory | `110_111_112_120_121_188` | host access 變更、端口影響、維護窗口、rollback |
| `port_firewall_change_evidence:gitea_cd_deploy_ssh` | CI deploy SSH | `k8s_ssh_host` | deploy access 斷線、回滾 owner、post-check |
| `port_firewall_change_evidence:gitea_cd_dev_ssh` | CI deploy SSH | `192.168.0.120` | dev/prod 邊界、端口 policy、host access impact |
| `port_firewall_change_evidence:deploy_alerts_ssh_path` | CI deploy SSH | `192.168.0.110` | alert deploy path、port close impact、通知鏈路 |
| `port_firewall_change_evidence:monitoring_discover_docker_ssh` | SSH discovery script | `110_188_docker_hosts` | monitoring discovery 可達性、read-only window |
| `port_firewall_change_evidence:monitoring_exporter_deploy_ssh` | monitoring SSH deploy | `192.168.0.188` | exporter deploy access、firewall owner、post-check |
| `port_firewall_change_evidence:backup_config_ssh_capture` | SSH backup capture | `110_188_120_121_cluster` | backup access、restore validation、service dependency |
| `port_firewall_change_evidence:host_ops_sudoers_wrapper` | sudoers policy | `host_ops_minimal_sudo` | sudo 授權邊界、firewall recovery 權限、break-glass |
| `port_firewall_change_evidence:k8s_prod_network_policy` | K8s NetworkPolicy | `awoooi_prod_namespace` | ingress / egress policy、route smoke plan |
| `port_firewall_change_evidence:argocd_metrics_network_policy` | K8s NetworkPolicy | `argocd_namespace` | metrics scrape、NodePort exposure、source whitelist |
| `port_firewall_change_evidence:argocd_metrics_nodeport` | K8s NodePort | `argocd_nodeport_30882_30883` | NodePort exposure、firewall owner、rollback |
| `port_firewall_change_evidence:velero_metrics_nodeport` | K8s NodePort | `velero_nodeport_30885` | backup metrics exposure、access policy |
| `port_firewall_change_evidence:wireguard_mesh_runbook` | WireGuard runbook | `110_111_120_121_gcp_a_gcp_b` | mesh cutover、firewall rule owner、canary / rollback |
| `port_firewall_change_evidence:alert_rules_ssh_actions` | alert SSH action rules | `ssh_mcp_action_catalog` | alert action catalog、read/write/admin 分級、cooldown |

## 4. 必填 Evidence 欄位

1. `change_or_incident_ref`
2. `actor_role_or_team`
3. `decision`
4. `decision_reason`
5. `affected_scope`
6. `affected_ports_or_paths_ref`
7. `before_state_ref`
8. `after_state_ref`
9. `service_dependency_ref`
10. `customer_impact_ref`
11. `incident_severity`
12. `restoration_time_ref`
13. `service_health_impact_refs`
14. `operator_notification_refs`
15. `incident_commander_or_owner`
16. `maintenance_window`
17. `rollback_owner`
18. `rollback_plan_ref`
19. `validation_plan`
20. `postcheck_evidence_refs`
21. `cross_project_sync_ref`

## 5. Reviewer Checks

1. `change_ref_present`
2. `actor_role_traceable`
3. `decision_reason_present`
4. `affected_scope_matches_surface`
5. `ports_or_paths_redacted`
6. `before_after_state_refs`
7. `firewall_diff_metadata_only`
8. `dependency_impact_present`
9. `customer_impact_review`
10. `cross_project_sync_present`
11. `incident_severity_present`
12. `service_health_impact_present`
13. `restoration_time_present`
14. `operator_notification_present`
15. `break_glass_classification_present`
16. `maintenance_window_present`
17. `rollback_owner_present`
18. `postcheck_evidence_present`
19. `secret_or_key_value_absent`
20. `no_runtime_authorization`
21. `counts_transition_safe`

## 6. Outcome Lanes

| Lane | 說明 |
|------|------|
| `waiting_change_evidence` | 尚未收到端口 / 防火牆變更證據；所有 accepted / runtime count 維持 0 |
| `quarantine_raw_firewall_dump` | 收到 raw firewall dump、secret 或 key material 時只能隔離 |
| `reject_unattributed_change` | 無 actor、無 owner、無 affected scope 或無 rollback 的變更不得驗收 |
| `request_impact_supplement` | 缺 before/after、impact、dependency、post-check 或 cross-project sync 時要求補件 |
| `ready_for_network_review` | metadata 合格後，只能進 network / firewall reviewer review |
| `incident_backfill_only` | 事故回補只能更新只讀 ledger，不得反向視為已批准操作 |
| `emergency_change_backfill_required` | 緊急端口 / 防火牆變更需補 actor、severity、health impact、通知、恢復與 rollback evidence |
| `owner_review_only_update` | 只允許更新 reviewer ledger，不改 firewall、port、route 或 host |
| `waiting_runtime_gate` | 即使證據 accepted，runtime gate 仍需獨立人工批准 |

## 7. 禁止動作

1. `ssh_read`
2. `ssh_write`
3. `live_firewall_read`
4. `firewall_change`
5. `port_change`
6. `port_close`
7. `port_open`
8. `network_policy_apply`
9. `nodeport_change`
10. `wireguard_change`
11. `sudo_action`
12. `deploy_ssh_action`
13. `route_smoke`
14. `public_gateway_reload`
15. `nginx_reload`
16. `host_restart`
17. `secret_value_collection`
18. `ssh_key_collection`
19. `raw_firewall_dump_storage`
20. `raw_key_material_storage`
21. `mark_change_evidence_accepted_without_reviewer_record`
22. `mark_incident_resolved_without_health_evidence`
23. `hide_cross_project_impact`
24. `close_management_port_without_owner`
25. `treat_break_glass_as_approval`
26. `open_runtime_gate`
27. `add_action_button`
28. `production_write`

## 8. 指令

產生 committed snapshot：

```bash
python3 scripts/security/port-firewall-change-evidence-acceptance.py \
  --root . \
  --source-acceptance-report docs/security/ssh-network-owner-response-acceptance.snapshot.json \
  --output docs/security/port-firewall-change-evidence-acceptance.snapshot.json \
  --generated-at 2026-06-15T00:36:00+08:00
```

驗證 guard：

```bash
python3 scripts/security/security-mirror-progress-guard.py --root .
```

## 9. 完成度

| 工作 | 完成度 | 說明 |
|------|--------|------|
| port / firewall change evidence acceptance ledger artifact | `100%` | 14 份候選、snapshot、文件與 guard 已固定；事故型欄位已納入 health impact、notification、restoration、severity 與 break-glass backfill |
| change evidence received / accepted | `0%` | 尚未收到或驗收 |
| actor / impact / before-after evidence | `0%` | 尚未收到 owner-provided evidence |
| cross-project sync evidence | `0%` | 尚未收到同步證據 |
| firewall / port / NetworkPolicy / NodePort / WireGuard change | `0%` | 未授權且未執行 |
| runtime gate / production write | `0%` | 未授權且未執行 |