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。