awoooi/docs/security/TELEGRAM-NOTIFICATION-EGRESS-INVENTORY.md

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 source 已讀回 0 個 direct Telegram Bot API sendMessage call site。這份清冊保留為防回歸 evidence：若 workflow、ops script 或 API path 再直接呼叫 Bot API，會被視為可能繞過 TelegramGateway formatter、dedup、outbound mirror、KM / PlayBook / Verifier 沉澱與 no-false-green gate 的治理 surface。

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

2. 固定數字

指標	數值	解讀
scanned_file_count	637	掃描 .gitea/workflows、scripts/ops、scripts/ci、apps/api/src
direct_bot_api_file_count	0	目前沒有檔案直接呼叫 Bot API
direct_bot_api_call_count	0	直接 sendMessage call site 總數
workflow_direct_bot_api_call_count	0	Gitea workflow 直送 Telegram
ops_script_direct_bot_api_call_count	0	ops script 直送 Telegram fallback
api_direct_bot_api_call_count	0	API direct path 直送 Telegram
gateway_normalized_callsite_count	57	已進入 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	0	無
Ops script	0	無
API direct path	0	無

若未來任何路徑直接呼叫 Bot API sendMessage，就必須被視為通知出口治理 surface：需有 owner、訊息形狀、redaction、formatter convergence、delivery receipt 與 no-false-green 驗收，並優先回到 AWOOI Alertmanager webhook 或 TelegramGateway final-exit formatter。

4. Owner 必填欄位

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

1. egress_surface_id
2. owner_role_or_team
3. routing_purpose
4. current_sender
5. target_chat_route
6. message_shape_contract
7. redaction_contract
8. formatter_convergence_plan
9. delivery_receipt_ref
10. dedup_or_fingerprint_plan
11. fallback_or_degraded_mode
12. migration_or_exception_reason
13. maintenance_window
14. rollback_owner
15. postcheck_evidence_ref
16. no_secret_value_attestation
17. no_raw_payload_attestation
18. 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. 下一步

1. 維持 no-new-bypass guard，確保 direct egress baseline 保持 0。
2. 把 TelegramGateway / AwoooP outbound receipt 接到 KM / PlayBook learning writeback readback。
3. 若未來新增 direct endpoint，必須先進 owner request、migration plan、acceptance ledger 與 post-check；不得用本清冊直接改 workflow 或送 Telegram。