# 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 修復授權。

仍維持：

```text
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。