Telegram 通知出口治理清冊

項目	內容
日期	2026-06-18
狀態	`inventory_ready_no_runtime_action`
工具	`scripts/security/telegram-notification-egress-inventory.py`
Snapshot	`docs/security/telegram-notification-egress-inventory.snapshot.json`
模式	repo-only scan；不讀 secret、不送 Telegram、不改 workflow / script
runtime gate	`0`

1. 目的

TelegramGateway 已經把 send_alert_notification()、send_text() 與 _send_request("sendMessage", ...) 收斂到最後出口 formatter，能把主機資源壓力、Wazuh、Kali、Nginx drift、Backup / Restore / Escrow、Provider freshness 與 supply-chain drift 轉成 ai_automation_alert_card_v1。

但 repo 內仍有 workflow、ops script 與一條 API path 直接呼叫 Telegram Bot API。這些路徑可能繞過 TelegramGateway 的 formatter、dedup、outbound mirror、KM / PlayBook / Verifier 沉澱與 no-false-green gate，因此必須先建清冊，再分批收斂。

此清冊只建立 metadata-only evidence，不代表允許 live Telegram send、workflow 修改、script 修改、secret 讀取或 production write。

2. 固定數字

指標	數值	解讀
`scanned_file_count`	`554`	掃描 `.gitea/workflows`、`scripts/ops`、`scripts/ci`、`apps/api/src`
`direct_bot_api_file_count`	`11`	仍有 11 個檔案直接呼叫 Bot API
`direct_bot_api_call_count`	`18`	直接 `sendMessage` call site 總數
`workflow_direct_bot_api_call_count`	`13`	Gitea workflow 直送 Telegram
`ops_script_direct_bot_api_call_count`	`4`	ops script 直送 Telegram fallback
`api_direct_bot_api_call_count`	`1`	API `channel_hub.py` interim path 直送 Telegram
`gateway_normalized_callsite_count`	`56`	已進入 TelegramGateway / final-exit formatter 的 call site
`gateway_final_exit_formatter_present_count`	`1`	`normalize_telegram_send_message_payload()` 已存在
`required_owner_field_count`	`18`	收斂前需要 owner 補齊的欄位
`reviewer_check_count`	`14`	reviewer 必檢規則
`outcome_lane_count`	`9`	收件結果分流
`blocked_action_count`	`22`	清冊階段明確禁止動作

所有 owner_response_received / accepted、formatter convergence accepted、delivery receipt accepted、Telegram send、Bot API call、workflow modification、script modification、secret collection、raw payload storage、production write、runtime gate 與 action button 都維持 0 / false。

3. 目前 direct Bot API surface

類別	Call count	代表路徑
Gitea workflow	`13`	`.gitea/workflows/cd.yaml`、`.gitea/workflows/cd-dev.yaml`、`.gitea/workflows/code-review.yaml`、`.gitea/workflows/deploy-alerts.yaml`、`.gitea/workflows/e2e-health.yaml`、`.gitea/workflows/run-migration.yml`
Ops script	`4`	`scripts/ops/docker-health-monitor.sh`、`scripts/ops/pg-backup.sh`、`scripts/ops/dr-drill.sh`、`scripts/ops/backup-from-110.sh`
API direct path	`1`	`apps/api/src/services/channel_hub.py`

上述路徑不一定全部錯誤；例如 ops script 可能是 API 離線 fallback。但只要它直接呼叫 Bot API sendMessage，就必須被視為通知出口治理 surface：需有 owner、訊息形狀、redaction、formatter convergence、delivery receipt 與 no-false-green 驗收。

4. Owner 必填欄位

每個 direct Bot API surface 收斂前至少需要：

egress_surface_id
owner_role_or_team
routing_purpose
current_sender
target_chat_route
message_shape_contract
redaction_contract
formatter_convergence_plan
delivery_receipt_ref
dedup_or_fingerprint_plan
fallback_or_degraded_mode
migration_or_exception_reason
maintenance_window
rollback_owner
postcheck_evidence_ref
no_secret_value_attestation
no_raw_payload_attestation
no_false_green_attestation

所有 evidence 只能是脫敏 ref、commit、run id、job id、artifact pointer 或收件編號；不得貼 Bot token、chat secret、secret hash、partial token、原始訊息 payload、未脫敏 workflow log 或工作視窗內容。

5. Reviewer checks

Reviewer 必須確認：

direct Bot API surface 已列入 snapshot，不能只靠 rg 手工看過。
owner role / target route / routing purpose 明確。
訊息形狀要收斂成 ai_automation_alert_card_v1 或有明確例外理由。
redaction contract、formatter convergence path 與 delivery receipt metadata 存在。
fallback mode 不會把 raw payload、完整路徑、內網 IP、secret、工作視窗內容或個人 namespace 送出去。
workflow / script / API 修改需另走 owner approval 與維護窗口。
清冊本身沒有送 Telegram、沒有 dispatch workflow、沒有讀 secret。
不把 route 200、CD success、UI 可見或 Telegram 送達當成 AI 自動化閉環完成。

6. Outcome lanes

Lane	說明
`waiting_owner_response`	尚未收到 owner 回覆；所有 accepted / runtime count 維持 0
`request_owner_route_supplement`	缺 owner、target route 或 routing purpose
`request_formatter_convergence_plan`	缺 formatter convergence 或例外理由
`request_redaction_contract`	缺 redaction / no-raw-payload attestation
`request_delivery_receipt_metadata`	缺 delivery receipt metadata 或 dedup / fingerprint plan
`quarantine_secret_or_raw_payload`	收到 secret value、raw payload、raw log 或未脫敏截圖時隔離
`reject_false_green_claim`	把 route 200、CD success、UI 可見或 Telegram 送達當驗收時拒收
`ready_for_notification_egress_review`	metadata 合格後進 reviewer review
`waiting_runtime_gate`	即使 reviewer accepted，runtime send / workflow modification 仍需獨立批准

7. 禁止動作

此清冊階段明確禁止 Telegram 實發、Bot API call、workflow 修改、未批准 script 修改、secret value / hash / partial token / chat id 收集、保存 raw message payload、保存未脫敏 workflow log、改 chat route、改 Bot token、rotate secret、workflow dispatch、production deploy、把 route 200 / CD success / UI 可見當通知驗收、跳過 formatter convergence、跳過 redaction review、開 runtime gate 或新增 action button。

8. 下一步

docs/security/TELEGRAM-NOTIFICATION-EGRESS-OWNER-REQUEST-DRAFT.md 已把 11 個 direct egress 檔案聚成 11 份人工送件前草稿；request sent 仍為 0。
先把 Gitea workflow 13 個 direct send 分成 CD / code-review / migration / health 類，決定哪些改走 AWOOI Alertmanager / TelegramGateway，哪些保留為 break-glass fallback。
scripts/ops/docker-health-monitor.sh、pg-backup.sh、dr-drill.sh、backup-from-110.sh 需要 owner 確認 API 離線 fallback 的訊息形狀與 redaction contract。
apps/api/src/services/channel_hub.py 的 interim Telegram path 需要評估是否改走 TelegramGateway 或至少套同一個 normalization / mirror / receipt 契約。
每個遷移都必須單獨做 owner approval、maintenance window、rollback owner、no-secret-value evidence 與 post-check；不得用本清冊直接改 workflow 或送 Telegram。

7.1 KiB Raw Permalink Blame History Unescape Escape