awoooi/docs/security/TELEGRAM-ALERT-READABILITY-GUARD.md

Telegram 告警可讀性防退化 Guard

項目	內容
日期	2026-06-19
狀態	telegram_alert_readability_guard_ready_no_runtime_action
工具	scripts/security/telegram-alert-readability-guard.py
Snapshot	docs/security/telegram-alert-readability-guard.snapshot.json
runtime gate	0

1. 目的

這個 guard 鎖住 Telegram 告警的最後出口格式，避免監控訊息又退回「整段 process list、raw JSON、內網 IP、完整路徑、URL、token 或外部掃描原文直接丟到群組」的狀態。

告警不是送出就算完成。IwoooS 的告警必須能讓值班者一眼看懂：

1. 事件嚴重度與 target。
2. AI 自動化 lane 與 gate。
3. top evidence 的脫敏摘要。
4. 建議下一步。
5. 禁止事項與 runtime_write_gate=0 邊界。

2. 固定合約

合約	固定值
source formatter markers	11
最後出口合約	3
測試合約	11
AIOps signal lanes	7
Host resource lanes	6
raw output 阻擋 marker	12
required output marker	6

目前 guard 會確認：

• TelegramGateway._send_request() 必須套用 normalize_telegram_send_message_payload()。
• send_alert_notification() 與 send_text() 必須先走 normalize_alert_notification_payload()。
• Host CPU / load / root Node.js / Prisma / Next build 只能轉成 主機資源壓力 AI 事件卡。
• Wazuh Dashboard / API 讀回退化、Wazuh 入侵訊號、Kali、Nginx drift、backup / restore、provider freshness、supply-chain 類訊號只能轉成 AIOps 候選事件卡。
• Wazuh Dashboard 顯示 agent 消失但 manager registry 尚未驗收時，必須轉成 wazuh_dashboard_api_readback_degraded，不得把它誤寫為 agent 全部消失或已恢復。
• 外部版本檢查 URL、套件樹路徑、workspace 路徑、runner toolcache 路徑、raw Wazuh path、raw Nginx path、內網 IP、token-like 字串、raw Prisma JSON 不得出現在格式化後訊息。

3. 驗收邊界

這是 repo-only guard，不是 Telegram 實發、不代表 delivery receipt、不是 owner response accepted，也不是 runtime 修復授權。

仍維持：

telegram_send_authorized=false
bot_api_call_authorized=false
direct_bot_api_migration_authorized=false
workflow_modification_authorized=false
ops_script_modification_authorized=false
api_sender_refactor_authorized=false
secret_value_collection_allowed=false
raw_payload_storage_allowed=false
host_write_authorized=false
production_write_authorized=false
runtime_execution_authorized=false
runtime_gate_open=false
action_buttons_allowed=false

4. 下一步

下一步不是直接實發測試訊息，而是把這個 guard 併入 IwoooS 例行 security progress guard，並在 owner response 之後分批收斂 direct Bot API 旁路與 delivery receipt。正式實發、Alertmanager route 變更、receiver reload、workflow/script/API sender 修改都仍需獨立批准、維護窗口、rollback owner 與 post-check。