69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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。
|