docs(security): add Telegram egress migration plan draft [skip ci]

This commit is contained in:
Your Name
2026-06-18 19:33:41 +08:00
parent 01bce6d815
commit a396f25b8f
11 changed files with 1649 additions and 4 deletions

View File

@@ -7,6 +7,7 @@
- 新增 `docs/security/telegram-notification-egress-inventory.snapshot.json``docs/security/TELEGRAM-NOTIFICATION-EGRESS-INVENTORY.md`
- `security-mirror-progress-guard.py` 已鎖住 Telegram egress snapshot`direct_bot_api_call_count=18``direct_bot_api_file_count=11`、workflow `13`、ops script `4`、API direct `1``gateway_normalized_callsite_count=56``gateway_final_exit_formatter_present_count=1`
- 新增 `scripts/security/telegram-notification-egress-owner-request-draft.py``docs/security/telegram-notification-egress-owner-request-draft.snapshot.json``docs/security/TELEGRAM-NOTIFICATION-EGRESS-OWNER-REQUEST-DRAFT.md`,把 11 個 direct egress 檔案聚成 11 份人工送件前 owner request 草稿workflow `6`、ops script `4`、API direct `1`
- 新增 `scripts/security/telegram-notification-egress-migration-plan-draft.py``docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json``docs/security/TELEGRAM-NOTIFICATION-EGRESS-MIGRATION-PLAN-DRAFT.md`,把 11 份草稿排成三個遷移波次workflow notification wrapper、ops notification wrapper、API sender gateway。
- direct egress 目前分布:
- Gitea workflow`.gitea/workflows/cd.yaml``cd-dev.yaml``code-review.yaml``deploy-alerts.yaml``e2e-health.yaml``run-migration.yml`
- Ops script`scripts/ops/docker-health-monitor.sh``pg-backup.sh``dr-drill.sh``backup-from-110.sh`
@@ -20,11 +21,13 @@
**驗證**
- `python3 scripts/security/telegram-notification-egress-inventory.py --root . --generated-at 2026-06-18T22:30:00+08:00 --output docs/security/telegram-notification-egress-inventory.snapshot.json``TELEGRAM_NOTIFICATION_EGRESS_INVENTORY_OK direct_calls=18 files=11 workflow=13 ops=4 api=1 runtime_gate=0`
- `python3 scripts/security/telegram-notification-egress-owner-request-draft.py --root . --generated-at 2026-06-18T22:45:00+08:00 --output docs/security/telegram-notification-egress-owner-request-draft.snapshot.json``TELEGRAM_NOTIFICATION_EGRESS_OWNER_REQUEST_DRAFT_OK drafts=11 workflow=6 ops=4 api=1 sent=0 runtime_gate=0`
- `python3 scripts/security/telegram-notification-egress-migration-plan-draft.py --root . --generated-at 2026-06-18T23:00:00+08:00 --output docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json``TELEGRAM_NOTIFICATION_EGRESS_MIGRATION_PLAN_DRAFT_OK candidates=11 waves=3 authorized=0 runtime_gate=0`
- `python3 -m json.tool docs/security/telegram-notification-egress-inventory.snapshot.json`:通過。
**完成度同步**
- Telegram notification egress inventory / guard`100%`
- Telegram notification egress owner request draft`100%`
- Telegram notification egress migration plan draft`100%`
- Direct Bot API formatter convergence`0%`,需 owner response / maintenance window 後分批處理。
- AI 自動化告警產品化通知出口治理從「API final-exit formatter」推進到「repo-wide egress inventory」下一步是 owner response package 與 migration plan。
- IwoooS headline 仍維持 `64%`active runtime gate 仍 `0`

View File

@@ -87,6 +87,7 @@ Host / runner 資源告警的第一版落地:
- `docs/security/telegram-notification-egress-inventory.snapshot.json` 目前固定 repo 內 `18` 個 direct Bot API `sendMessage`,分布為 Gitea workflow `13`、ops script `4`、API direct path `1`
- `docs/security/telegram-notification-egress-owner-request-draft.snapshot.json` 已將上述 direct egress 檔案聚成 `11` 份人工送件前草稿request sent 仍為 `0`
- `docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json` 已將 11 份草稿排成 workflow、ops script、API sender 三個遷移波次migration authorized 仍為 `0`
- 這些 direct egress 可能繞過 TelegramGateway formatter、dedup、outbound mirror、KM / PlayBook / Verifier 與 no-false-green gate因此只能視為已知待治理 surface不能視為已完成收斂。
- 清冊階段只允許保存 path、line、redacted excerpt、owner 欄位與 reviewer gate不送 Telegram、不讀 Bot token、不保存 chat secret、不改 workflow / script、不開 runtime gate。
- 後續每個 direct egress 要收斂前,都必須補 owner route、message shape、redaction contract、formatter convergence plan、delivery receipt、fallback mode、rollback owner 與 post-check evidence。

View File

@@ -52,6 +52,8 @@
同日再新增 `docs/security/TELEGRAM-NOTIFICATION-EGRESS-OWNER-REQUEST-DRAFT.md``docs/security/telegram-notification-egress-owner-request-draft.snapshot.json`,將 11 個 direct egress 檔案轉成人工送件前草稿。固定 `request_draft_count=11`、workflow `6`、ops script `4`、API direct `1``required_owner_field_count=19``preflight_check_count=16``outcome_lane_count=9``forbidden_payload_count=14``blocked_action_count=26`request sent、recipient confirmed、owner response accepted、formatter convergence accepted、Telegram send、Bot API call、workflow / script modification、API sender refactor、secret collection、production write、runtime gate 與 action button 仍全部為 `0 / false`
同日再新增 `docs/security/TELEGRAM-NOTIFICATION-EGRESS-MIGRATION-PLAN-DRAFT.md``docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json`,將 11 份草稿排成三個 no-runtime 遷移波次。固定 `migration_candidate_count=11`、workflow `6`、ops script `4`、API direct `1``proposed_wave_count=3``reviewer_check_count=15``blocked_action_count=21`owner response、migration authorized、workflow / script modification、API sender refactor、Telegram send、Bot API call、secret collection、production write、runtime gate 與 action button 仍全部為 `0 / false`
## 1.2c 2026-06-18 Backup / Restore / Escrow 事故後回讀計畫
已新增 `docs/security/BACKUP-RESTORE-POST-INCIDENT-READBACK-PLAN.md``docs/security/backup-restore-post-incident-readback-plan.snapshot.json`,將 38 個 backup / restore / escrow / retention surface 轉成事故後回讀計畫。固定 `readback_candidate_count=38``write_capable_readback_candidate_count=27``live_evidence_required_readback_candidate_count=38``restore_drill_readback_required_candidate_count=38``offsite_or_escrow_readback_required_candidate_count=20``retention_or_remote_delete_readback_required_candidate_count=17``required_readback_field_count=34``reviewer_check_count=32``outcome_lane_count=11``blocked_action_count=51`,讓 `backup_restore_credential``64%` 推進到 `66%`,高價值配置平均維持 `71%`,需 live evidence 類別仍為 `9`

View File

@@ -91,6 +91,8 @@
同日再新增 `telegram_notification_egress_owner_request_draft_v1`,將 11 個 direct egress 檔案轉成人工送件前 owner request 草稿。固定 `request_draft_count=11``workflow_request_draft_count=6``ops_script_request_draft_count=4``api_direct_request_draft_count=1``required_owner_field_count=19``preflight_check_count=16``outcome_lane_count=9``forbidden_payload_count=14``blocked_action_count=26`。request sent、recipient confirmed、audit event emitted、owner response accepted、formatter convergence accepted、break-glass fallback accepted、Telegram send、Bot API call、workflow / script modification、API sender refactor、secret collection、raw payload storage、production write、runtime gate 仍全部為 `0 / false`
同日再新增 `telegram_notification_egress_migration_plan_draft_v1`,將 11 份 owner request 草稿排成 workflow notification wrapper、ops notification wrapper、API sender gateway 三個遷移波次。固定 `migration_candidate_count=11``workflow_migration_candidate_count=6``ops_script_migration_candidate_count=4``api_direct_migration_candidate_count=1``proposed_wave_count=3``owner_response_required_count=11``maintenance_window_required_count=11``rollback_owner_required_count=11`。owner response、migration authorized、workflow / script modification、API sender refactor、Telegram send、Bot API call、secret collection、raw payload storage、production write、runtime gate 仍全部為 `0 / false`
### 0.3d 2026-06-15 Public / Admin / API runtime config 變更證據驗收
`public_runtime_config_change_evidence_acceptance_v1` 已把公開產品頁、AwoooP 後台、API / CORS、frontend env、Sentry tunnel、webhook / callback 與跨產品 runtime route 轉成 metadata-only 變更證據驗收只讀帳本。固定 `candidates=6``c0=5``c1=1``write_capable=6``source_refs=20``required_evidence_fields=21``reviewer_checks=21``outcome_lanes=8``blocked_actions=32`

View File

@@ -96,6 +96,8 @@
同日再新增 `telegram_notification_egress_owner_request_draft_v1`,把 11 個 direct egress 檔案轉成人工送件前草稿。固定 `request_draft_count=11`、workflow `6`、ops script `4`、API direct `1``required_owner_field_count=19``preflight_check_count=16``outcome_lane_count=9``forbidden_payload_count=14``blocked_action_count=26`。這是 handoff envelope不是 request sent、recipient confirmed、audit event emitted、owner response accepted、formatter convergence accepted、workflow / script modification、API sender refactor、Telegram send、Bot API call、secret collection、production write 或 runtime gate。
同日再新增 `telegram_notification_egress_migration_plan_draft_v1`,把 11 份草稿排成 workflow notification wrapper、ops notification wrapper、API sender gateway 三個 no-runtime 遷移波次。固定 `migration_candidate_count=11`、workflow `6`、ops script `4`、API direct `1``proposed_wave_count=3``owner_response_required_count=11``maintenance_window_required_count=11``rollback_owner_required_count=11``migration_authorized_count=0``runtime_gate_count=0`。這是遷移計畫草稿,不是 workflow / script / API sender 變更,也不是 Telegram send、Bot API call、secret collection 或 production write。
## 0.00aaa 2026-06-15 K8s / ArgoCD GitOps 變更證據驗收
本輪把 K8s / ArgoCD 從 owner response acceptance 推進到 GitOps 變更證據驗收只讀帳本:`k8s_argocd_change_evidence_acceptance_v1` 固定 `candidates=4``c0=3``write_capable=4``required_evidence_fields=18``reviewer_checks=18``outcome_lanes=8``blocked_actions=28`,並讓 `k8s_production_gitops` 只讀治理成熟度 `62% -> 64%`,高價值配置平均只讀成熟度仍維持 `68%`。這是 metadata-only 收件驗收,不是 change evidence received / accepted、runtime approval package、ArgoCD API read、ArgoCD sync、kubectl action、Helm upgrade、NetworkPolicy apply、NodePort change、RBAC change、live cluster read、production write 或 runtime gate。

View File

@@ -0,0 +1,83 @@
# Telegram 通知出口遷移計畫草稿
| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-18 |
| 狀態 | `migration_plan_draft_ready_no_runtime_action` |
| 工具 | `scripts/security/telegram-notification-egress-migration-plan-draft.py` |
| Snapshot | `docs/security/telegram-notification-egress-migration-plan-draft.snapshot.json` |
| Source snapshot | `docs/security/telegram-notification-egress-owner-request-draft.snapshot.json` |
| 模式 | metadata-only不改 workflow、不改 script、不重構 API、不送 Telegram |
| runtime gate | `0` |
## 1. 目的
Telegram 通知出口目前已完成三層只讀治理:
1. Inventory固定 `18` 個 direct Bot API `sendMessage` call site。
2. Owner Request Draft把 direct egress 檔案聚成 `11` 份人工送件前草稿。
3. Migration Plan Draft`11` 份草稿排成三個遷移波次,定義 proposed target、owner response、maintenance window、rollback owner、delivery receipt 與 post-check。
這份文件只提供遷移計畫草稿,不代表可以直接修改 `.gitea/workflows``scripts/ops``apps/api/src/services/channel_hub.py`
## 2. 固定數字
| 指標 | 數值 | 解讀 |
|------|------|------|
| `source_request_draft_count` | `11` | 來源 owner request draft 數 |
| `source_direct_bot_api_call_count` | `18` | 來源 direct Bot API call site |
| `migration_candidate_count` | `11` | 每個 direct egress 檔案一個遷移候選 |
| `workflow_migration_candidate_count` | `6` | Gitea workflow 候選 |
| `ops_script_migration_candidate_count` | `4` | Ops script 候選 |
| `api_direct_migration_candidate_count` | `1` | API sender 候選 |
| `proposed_wave_count` | `3` | 三個建議波次 |
| `plan_field_count` | `17` | 每個 candidate 的計畫欄位 |
| `reviewer_check_count` | `15` | reviewer 必檢規則 |
| `outcome_lane_count` | `9` | 審查結果分流 |
| `blocked_action_count` | `21` | 草稿階段禁止動作 |
所有 owner response、migration authorized、workflow / script modification、API sender refactor、Telegram send、Bot API call、secret collection、raw payload storage、production write、runtime gate、action button 都維持 `0 / false`
## 3. 建議波次
| Wave | Scope | Proposed target | 邊界 |
|------|-------|-----------------|------|
| `wave_1_workflow_notification_wrapper` | 6 個 Gitea workflow 檔案、13 個 direct send | `scripts/ci/notify-awoooi-cicd.sh` 或 AWOOI Alertmanager webhook | 需 owner response、維護窗口、rollback owner、Gitea run / notification receipt post-check不得直接改 workflow |
| `wave_2_ops_notification_wrapper` | 4 個 ops script、4 個 direct send | `scripts/ops/notify-awoooi-ops.sh` 或 AWOOI Alertmanager webhook | 需保留 API 離線情境的 break-glass fallback 決策;不得直接改 host script |
| `wave_3_api_sender_gateway` | `apps/api/src/services/channel_hub.py` 1 個 direct send | TelegramGateway final-exit formatter | 需 API owner review、unit test、delivery receipt / mirror readback不得直接重構 API sender |
## 4. Reviewer checks
Reviewer 必須確認:
- source owner request draft 是目前版本。
- owner response、maintenance window、rollback owner、delivery receipt、post-check、redaction contract 與 no-false-green attestation 都存在。
- workflow change、script change、API sender refactor 都必須和本文件分離,另開 change evidence / runtime approval。
- 不收 secret value、hash、partial token、raw message payload 或未脫敏 log。
- 不把 CD success、route `200`、UI 可見或 Telegram 送達當成 AI 自動化閉環完成。
- runtime gate 維持 `0`,直到有獨立人工批准與 post-check。
## 5. Outcome lanes
| Lane | 說明 |
|------|------|
| `draft_waiting_owner_response` | 尚未收到 owner response |
| `ready_for_workflow_migration_review` | workflow 類 metadata 完整,可進 migration review |
| `ready_for_ops_script_migration_review` | ops script 類 metadata 完整,可進 migration review |
| `ready_for_api_sender_migration_review` | API sender 類 metadata 完整,可進 migration review |
| `request_missing_owner_response` | 缺 owner response |
| `request_missing_maintenance_or_rollback` | 缺維護窗口或 rollback owner |
| `reject_secret_or_raw_payload` | 收到 secret 或 raw payload 時拒收 |
| `reject_false_green_claim` | false-green claim 時拒收 |
| `waiting_runtime_gate` | metadata accepted 後仍等待 runtime gate |
## 6. 禁止動作
此草稿階段禁止改 workflow、改 ops script、重構 API sender、送 Telegram、呼叫 Bot API、dispatch workflow、觸發 CD、production deploy、讀 secret store、收 secret value / hash / partial token、保存 raw payload / 未脫敏 log、改 chat route、改 Bot token、rotate secret、把 CD success / route 200 當 delivery receipt、開 runtime gate 或新增 action button。
## 7. 下一步
1. 等 owner response 補齊 11 個 candidate 的 route、message shape、redaction、receipt、maintenance、rollback 與 post-check。
2. 先做 workflow 類 migration review但實作必須另開 change evidence / runtime approval不在本草稿內執行。
3. Ops script 需先確認 API offline fallback 是否仍保留;若保留,必須有明確 break-glass reason 與 redacted message shape。
4. API sender 需由 `channel_hub.py` owner review 是否改走 TelegramGateway並補 unit test / mirror readback。

View File

@@ -96,6 +96,7 @@ Owner 回覆只能提供 metadata / ref不得包含 Bot token、chat secret
## 7. 下一步
1. 人工確認送件對象與 route owner 後,才可把這 11 份草稿送出;送出本身需另有 audit event不由本 snapshot 代替
2. 收到 owner response 後,先做 intake preflight欄位完整、無 secret value、無 raw payload、無 false-green claim
3. 通過 reviewer 後,才可為每個 surface 建 migration planworkflow / script / API sender 修改仍需獨立維護窗口、rollback owner 與 production post-check。
1. `docs/security/TELEGRAM-NOTIFICATION-EGRESS-MIGRATION-PLAN-DRAFT.md` 已把 11 份草稿排成三個遷移波次migration authorized 仍為 `0`
2. 人工確認送件對象與 route owner 後,才可把這 11 份草稿送出;送出本身需另有 audit event不由本 snapshot 代替
3. 收到 owner response 後,先做 intake preflight欄位完整、無 secret value、無 raw payload、無 false-green claim。
4. 通過 reviewer 後,才可為每個 surface 進實作workflow / script / API sender 修改仍需獨立維護窗口、rollback owner 與 production post-check。

File diff suppressed because it is too large Load Diff

View File

@@ -82,7 +82,7 @@
| P0-3 | AwoooP 同步封包 | 100% | 已送至 AwoooP 平行工作 thread `019e9154-7d5e-7b72-85be-c9d97e43ecc9`;後續仍需每次推版前重新 fetch / fast-forward | 本文件、thread send readback、mirror checklist readback |
| P0-4 | production live sanity 節點 | 100% | desktop / mobile / 展開區塊 / overflow / action href 檢查已完成 | Playwright production sanity 通過 |
| P0-5 | LOGBOOK 與完成度更新 | 100% | D2 comments-only、D2 AIOps sample、D2 Code Review 候選分類與 D2 AwoooP Runs fallback 皆已回填;可見 / bundle 變更皆已補 local / production desktop + mobile smoke | `docs/LOGBOOK.md` readback |
| P0-6 | Telegram 監控告警 / 通知出口治理 | outbound 主鏈路 100%;靜音 / recurrence slice 88%;通知出口清冊 100%owner request draft 100%direct Bot API convergence 0% | Alertmanager 缺 project context、既有 approval 收斂告警靜音、AI 分析中重複告警靜音皆已修復並正式 smoke`TelegramGateway` final-exit formatter 已完成 host / multi-signal 卡片化;本輪新增 direct Bot API egress inventory固定 workflow 13、ops script 4、API direct 1並聚成 11 份 owner request 草稿;後續需 owner response 後分批收斂,不得把 API formatter 完成誤判成全域完成 | API health、Telegram health、API pod Alertmanager smoke、production logs `converged_alert_recurrence_sent``telegram-notification-egress-inventory.snapshot.json``telegram-notification-egress-owner-request-draft.snapshot.json` |
| P0-6 | Telegram 監控告警 / 通知出口治理 | outbound 主鏈路 100%;靜音 / recurrence slice 88%;通知出口清冊 100%owner request draft 100%migration plan draft 100%direct Bot API convergence 0% | Alertmanager 缺 project context、既有 approval 收斂告警靜音、AI 分析中重複告警靜音皆已修復並正式 smoke`TelegramGateway` final-exit formatter 已完成 host / multi-signal 卡片化;本輪新增 direct Bot API egress inventory固定 workflow 13、ops script 4、API direct 1並聚成 11 份 owner request 草稿與 3 個遷移波次;後續需 owner response 後分批收斂,不得把 API formatter 完成誤判成全域完成 | API health、Telegram health、API pod Alertmanager smoke、production logs `converged_alert_recurrence_sent``telegram-notification-egress-inventory.snapshot.json``telegram-notification-egress-owner-request-draft.snapshot.json``telegram-notification-egress-migration-plan-draft.snapshot.json` |
| P0-7 | Telegram 批准後執行真相鏈止血 | 100% | no-action approval 不再顯示批准 / 執行中;可執行修復 approval 會寫入 `auto_repair_executions`、KM 與 verifier下一步補 MCP evidence / PlayBook trust 產生真正修復候選 | 目標 pytest `125 passed`、py_compile、guard、production health、API / worker rollout、production pod classifier readback |
| P0-8 | Telegram no-action 人工處置包與操作入口 | 100% | no-action 卡片已新增人工處置包、證據補齊清單、AwoooP 修復候選建立步驟、verifier / KM / PlayBook 回寫提醒,並改成 `處置包``重診``歷史``靜默``真相鏈``Runs` 鍵盤;舊訊息不 retroactive 改寫 | 目標 pytest `64 passed + 44 passed`、py_compile、guard、production health、API / worker rollout、production pod render / keyboard smoke |
| P0-9 | MCP evidence -> PlayBook 修復候選產生 | D5 `88%`Approvals ledger `100%`Runs ledger desktop `100%`Alerts ledger desktop / mobile `100%` | 已補 webhook fallback 先建立 incident再收 MCP evidence、查 approved PlayBook、檢查 trust / command safety、產生 medium approval candidate 與 verifier planD1 追加通用兜底 PlayBook / 診斷型命令不可誤當修復、阻擋理由繁中化D2 在缺候選時產生 `repair_candidate_draft_package_v1``playbook_draft_required`、下一步與必填欄位D3 新增 `awooop_repair_candidate_draft_work_item_v1` read-only projection 與 Telegram `工作項目` deeplinkD4 讓 AwoooP Work Items 詳細呈現 PlayBook 草案處置板、必填欄位、阻擋原因、下一步、Runs / 審批連結D5 新增 `repair_candidate_coverage_gap_v1`,讓 blocked result 帶出 coverage key、target kind、blocking stage、必收 MCP evidence refs、PlayBook template fields 與 runtime 0 / false 邊界Approvals / Runs / Alerts 已新增 `資產沉澱` 欄或焦點矩陣,可直接看到 KM / PlayBook / 腳本 / 排程 / Verifier 的完成與卡點;下一步要補 Runs mobile smoke並把同一總帳接到正式 Telegram 告警卡、Observability 與 Tenants用真實告警驗證 approval -> execution -> verifier -> KM / PlayBook 回寫 | Approvals code `dafe5342` 已隨 deploy marker `42c08ece` 正式站 desktop / mobile smokeRuns code `11c2b5d4` 已隨 deploy marker `8b6ab87c` 正式站 desktop DOM smokeAlerts code `10cd6167` 已隨 deploy marker `d36d764a` 正式站 desktop / mobile DOM smokeP2-407 API production readback `overall_completion_percent=100`status-chain 後續仍必須看到 tool call、PlayBook id、risk gate、repair candidate、verifier plan |