b191f8e9fe
Some checks failed
CD Pipeline / workflow-shape (push) Successful in 0s
CD Pipeline / cancel-stale-cd (push) Has been skipped
CD Pipeline / tests (push) Failing after 2m6s
CD Pipeline / build-and-deploy (push) Has been skipped
CD Pipeline / post-deploy-checks (push) Has been skipped
80 lines
4.0 KiB
Markdown
80 lines
4.0 KiB
Markdown
# 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. 驗證指令
|
||
|
||
```bash
|
||
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 |
|