awoooi/docs/security/TELEGRAM-NOTIFICATION-EGRESS-NO-NEW-BYPASS-GUARD.md

Telegram 通知出口 No-New-Bypass Guard

項目	內容
日期	2026-06-19
狀態	pass_no_new_bypass
工具	scripts/security/telegram-notification-egress-no-new-bypass-guard.py
Snapshot	docs/security/telegram-notification-egress-no-new-bypass-guard.snapshot.json
Source snapshot	docs/security/telegram-notification-egress-inventory.snapshot.json
模式	repo source scan；不讀 secret、不送 Telegram、不修改 workflow / script / API sender
runtime gate	0

1. 目的

telegram_notification_egress_no_new_bypass_guard_v1 用 committed inventory 當 baseline，掃描 repo source 是否新增未登記的 Telegram Bot API direct endpoint。目前 committed inventory 已讀回 0 個 direct sendMessage call site；本 guard 的目的改為維持 0 旁路，防止新 direct Bot API 在治理收斂後重新出現。

2. 掃描範圍

範圍	說明
.gitea/workflows	Gitea Actions workflow 中的 direct Bot API
scripts/ops	主機 / 備份 / DR 類 ops script
scripts/ci	CI helper script
apps/api/src	API sender 與 notification 相關 source

Guard 目前保護的方法包含 sendMessage、sendDocument、sendPhoto、sendMediaGroup、editMessageText、sendAnimation、sendVideo、sendAudio、sendVoice。

3. 固定數字

指標	數值	解讀
source_direct_bot_api_call_count	0	committed inventory 的 direct call baseline
source_direct_bot_api_file_count	0	committed inventory 的 direct file baseline
baseline_signature_count	0	baseline signature 數
current_direct_bot_api_call_count	0	目前掃描到的 direct call 數
current_direct_bot_api_file_count	0	目前掃描到的 direct file 數
guarded_method_count	9	受保護 Bot API method 數
sendMessage_call_count	0	目前沒有 direct sendMessage
sendDocument_call_count	0	不允許新增附件型 direct send
sendPhoto_call_count	0	不允許新增圖片型 direct send
sendMediaGroup_call_count	0	不允許新增 media group direct send
editMessageText_call_count	0	不允許新增 edit direct call
new_bypass_count	0	新增未登記旁路必須維持 0
removed_baseline_call_count	0	baseline 移除需另外走 migration evidence
runtime_gate_count	0	不提供 runtime 執行授權

4. 判讀規則

• new_bypass_count=0 才代表沒有新增未登記 direct Bot API 旁路。
• 既有 direct sendMessage 已收斂到 0；任何新增 direct endpoint 都必須視為 regression。
• 若新增 sendDocument、sendPhoto、sendMediaGroup 等附件型出口，guard 會阻擋，必須先進 inventory、owner request、migration plan 與 acceptance ledger。
• 若未來出現 removed / added baseline 差異，不能只靠 guard 結果宣稱完成；仍需 migration evidence、delivery receipt 與 postcheck。

5. 禁止事項

本 guard 不得被解讀成以下授權：

• 送 Telegram 或呼叫 Bot API。
• 修改 workflow、ops script、API sender、chat route 或 Bot token。
• 讀 secret store、收 secret value / hash / partial token。
• 保存 raw payload、raw log 或未脫敏截圖。
• 開 runtime gate 或新增 action button。

6. 驗證指令

python3 scripts/security/telegram-notification-egress-no-new-bypass-guard.py --root .
python3 -m json.tool docs/security/telegram-notification-egress-no-new-bypass-guard.snapshot.json >/dev/null
python3 -m py_compile scripts/security/telegram-notification-egress-no-new-bypass-guard.py
python3 scripts/security/security-mirror-progress-guard.py --root .

7. 完成度

項目	完成度	邊界
No-new-bypass source guard	100%	目前 new_bypass_count=0
Existing direct Bot API convergence	100%	repo source 已讀回 direct send 0
Runtime execution	0%	不送 Telegram、不呼叫 Bot API、不改 live route