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 內仍有 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 收斂前至少需要：

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