文件說明 / 02
Telegram · GitHub Actions 擷取
在臨時 GitHub runner 上選擇 Takeout、一般 API 匯出或聊天日誌.
完整參考資料
可從 main 預覽。分叉會從
phishdestroy/TgWitness。該工作流程會透過新建立的 Telegram 連線,匯出一個帳戶、選定的聊天紀錄或單一
聊天紀錄的事件日誌,對證據
ZIP 檔案或多部分清單進行驗證,並僅上傳
收件者加密的交接資料。一般管理面板不會對外公開。
選擇 client=official_web 以帶有受保護的 Telegram Web 控制項及影片功能的官方客戶端見證模式運作。此模式需您自行設置上游代理伺服器,並僅監控一個已渲染的聊天視窗。預設 client=api 將保留下文所述的完整帳戶匯出模式。
驗證者會將存檔與其 GitHub 證明、已核准的 工作流程及收集器提交記錄,以及已簽署的日誌和附件雜湊值進行比對。 收集過程採用固定化的上游程式碼和全新的儲存空間。審查者 可以檢視該程式碼,並根據記錄的執行過程,對交付的存檔進行驗證。
使用者流程#
此輔助程式會說明這五個階段,並讓您在範例資料上嘗試訊息或收集器 的替換功能。「開始擷取」會開啟精靈。
- 請在專案首頁、
工作區登入畫面,或透過「匯出」→「開啟擷取輔助程式」選擇 GitHub Actions 擷取(預覽版)。您也可以
在現代瀏覽器中,從可信賴的檢出版本開啟官方輔助程式
或
tgwitness/static/capture.html。 此輔助程式在處理金鑰或 檔案時不會發出任何網路請求。此輔助程式支援該網站的介面語言; 臨時收集面板支援英文和俄文,若瀏覽器的語言為上述兩種之一, 則會以該語言開啟。 - 產生一組金鑰並儲存 sealed-key.json 檔案。這是唯一的 私密解密金鑰。請複製獨立的公開收件者值。若遺失 私密金鑰,將無法存取連線及存檔。 請確認已將其儲存,以便解鎖下一步驟。若您已有 傳送檔案,請載入已儲存的金鑰,並選擇「我已有存檔」。
- 分叉 TgWitness,在分叉中啟用「動作」,並執行「密封聊天記錄擷取」。 貼上公開收件者,並選擇 30、60 或 120 分鐘。切勿將 電話號碼、登入代碼、Telegram 密碼、私鑰或會話內容 放入工作流程輸入、提交、問題或日誌中。
- 執行期間,請從 Artifacts 下載 sealed-connection 並解壓縮。
在輔助程式中載入
connection.tgwsealed,並使用已儲存的私密金鑰。 生成的連結其 URL 片段中包含一個隨機存取密鑰。 請將此連結保密。控制面板會移除該片段,並將密鑰 儲存於此分頁的會話儲存中;該密鑰不會被記錄在 HTTP 存取日誌中。 - 開啟連線連結。透過 QR 碼,或使用您的電話號碼與
登入碼進行登入。若 Telegram 要求,請輸入您的兩步驟驗證密碼。預設情況下,
系統會使用內建的 API 憑證池,這與一般工作區相同。您
可展開「自訂憑證」選項區塊,並同時輸入
api_id和api_hash來自 my.telegram.org/apps 的資訊。若要使用內建憑證池,請將 兩個欄位均留空;若憑證組合不完整或格式錯誤,系統將予以拒絕。 不允許匯入會話。請選擇匯出模式與範圍。連線 連結中包含存取密鑰:請務必保密。 - 選擇「Telegram Takeout」、「標準 Telegram API」或「聊天事件日誌」。 若要匯出帳戶資料,請選擇所有可存取的聊天室,或載入並選取一個或多個 聊天室,接著設定日期、聊天類型、帳戶類別及附件規則。 檢查設定與檔案大小,可選擇將設定 JSON 儲存供獨立 審核者查閱,然後按下「開始擷取」。開始後設定即無法變更。 「繼續」功能僅在該執行程序存在時有效;若提前結束,系統會保留已擷取的 資料並記錄資料缺口。開始後若超過截止期限,將產生明確標示為 「不完整」的存檔;開始前超過截止期限或取消操作,則不會產生任何存檔。
- 請等待密封結果,下載並解壓縮,然後在輔助程式中
delivery.tgwsealed。您將收到delivery.zip,其中包含evidence.zip,attestation.jsonl,以及操作說明。瀏覽器解密功能 上限為 256 MiB;較大的封包請使用下方的「streaming local」命令。 大型結果還包含delivery-NNNNNN.tgwsealed多個部分;主delivery.tgwsealed檔案中則包含evidence.parts.json以及驗證資訊。 請下載每個部分,並依照以下說明在本地端進行組裝。 - 若撤銷權限未獲確認,或執行程序已被終止,請在 Telegram 的「設定」→「裝置」中結束該臨時會話。正常完成時會要求登出,且 執行記錄會標記撤銷權限是否已獲確認。
該儲存庫必須包含已發佈的「固定來源」及「可重複使用工作流程」 提交。僅有本機分支是無法被其他 GitHub 儲存庫調用的。
會議時間預算#
在收取之前, 計算時間與大小 根據訊息數量及有限樣本,估算所選歷史紀錄與檔案 所需的時間。顯示內容包含已花費的登入時間、 預估的收集時間,以及打包所需的預留時間。針對檔案,初始估算 採用 1 MiB/s 的速率及兩倍的時間餘裕;進度顯示會以實際測得的 速率取代該假設。使用 僅限訊息 或者,當預估時間超過剩餘時間時,請選擇較少的聊天記錄。
Telegram 所報告的「Takeout」等待時間已納入預算。當剩餘時間需用於封裝時,收集器會停止收集, 保留已收集的資料,並標記為部分 結果。因此,一個 120 分鐘的會話會利用其剩餘的收集時段,而非 等到截止時間才開始準備歸檔。顯示畫面會標示出 那些無法完整採樣其全尺寸的選項。
選擇此模式或一個持久性工作區#
| 擷取模式 | 可設定的範圍 | 差異 |
|---|---|---|
| Telegram Takeout,預設選項 | 所有可存取的雲端聊天記錄或選定的聊天記錄、日期、帳戶類別、媒體政策以及 JSON/HTML 檢視模式 | 使用 Telegram 的官方匯出機制;可能需要經核准或等待。在 Telegram 允許的情況下,Takeout 可列出剩餘的頻道/群組,並請求額外的個人資料。 |
| 標準 Telegram API | 帳戶範圍與輸出選項與一般 API 所提供的相同,但須受限於該 API 可用的方法 | 無法初始化 Takeout;無法列舉左通道/超級群組,亦無法擷取僅限 Takeout 的個人資料。聯絡人範圍僅涵蓋 Telegram 用戶,而非完整的儲存電話聯絡人清單。速率限制依然適用。 |
| 聊天活動日誌 | 一則選定的聊天記錄、附件政策及可選的頭像 | 記錄本次執行過程中觀察到的歷史資料與變更。帳戶類別、日期篩選器及與桌面版相容的檢視方式均不適用。 |
這三種模式均採用相同的 GitHub 驗證機制與加密傳輸方式。Takeout 會選取資料擷取方式,且絕不會在未經通知的情況下被一般 API 存取所取代。 TgWitness 會根據擷取的記錄產生 JSON/HTML 檢視頁面,並在匯出時保留 所選的資料擷取方式。請參閱 官方 Takeout API。
預設會使用「Takeout」功能,涵蓋所有可存取的聊天類型(包括已歸檔的聊天記錄)、所有 日期、帳戶個人資料與聯絡人、相容的 JSON 和 HTML 格式,以及檔案下載。 初始媒體配額為 4 GiB,並會顯示各類型的檔案限制;若檔案較大 或下載配額已用盡,系統將在可行情況下使用伺服器雜湊值。請在開始匯出前檢視這些 限制。雜湊值無法還原原始檔案。可選的照片、 限時動態、會話元資料及額外個人資料仍屬獨立選項。
在已建立的 Telegram 會話中,提取操作可能需要經過批准。Telegram 會設定 延遲時間;新的登入或執行程序無法繞過此延遲。最大擷取時段 為 120 分鐘(包含登入與批准時間),因此大型帳戶或需長時間等待批准 的情況可能無法完成。透過持續性本地匯出可恢復同一會話,但 不會繼承 GitHub 驗證。
同意並確認設定#
檢查設定與大小後,請使用「儲存設定」進行驗證。在
收集前,須與審核員就 sealed-export-settings.json 與審查員達成共識後,方可進行收集。
任何變更都會使已儲存的評估失效。收集者會對有效的
設定及其 SHA-256 簽署,而帳戶匯出收據則將相同選項綁定。
驗證者會回報實際模式、選項及完整性,並拒絕
期刊與嵌套帳戶匯出之間存在不一致的情況。
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --expected-selection sealed-export-settings.json --require-complete
--expected-selection 拒絕其他傳輸方式、聊天範圍、篩選器或
附件政策。 --require-complete 僅接受已標記為「完成」的帳戶匯出檔及
聊天記錄。若未設定這些標誌,驗證程序仍會檢查來源與
完整性,同時回報已記錄的設定及缺漏處。請在執行前確認預期的
選取範圍,並將其與存檔分開存放。範圍與擷取間隔用以識別執行期間
所擷取的內容;比較先前版本時,請使用保留的早期觀察結果。
| 需求 | 模式 |
|---|---|
| 在有限的會話期間內,匯出可存取的帳戶資料或選定的聊天紀錄,並向審查人員提供經外部認證的存檔 | GitHub Actions 擷取 (預覽版) |
| 持續監看多個聊天室、管理帳號、搜尋並閱讀日益增多的聊天紀錄 | 本機或 Docker 工作區 |
這會以新的登入帳戶啟動一項獨立的擷取作業。此操作不會上傳您現有的 本地日誌、匯出目前開啟的工作區,也不會重複使用其 Telegram 連線。 未完成的雲端擷取作業在執行程式被終止後無法繼續進行;新的 工作流程會啟動一項新的擷取作業。
工作區的「匯出 → 開啟擷取輔助工具」會於面板內開啟完整的精靈 。獨立頁面使用相同的精靈、控制項和主題。 兩者皆將金鑰與解密過程保留在您的瀏覽器中。GitHub 工作流程的啟動以及 臨時 Telegram 面板會分別在不同分頁中開啟;精靈會告知您何時 需要返回。鎖定工作區會清除精靈在記憶體中的金鑰。您儲存的金鑰 檔案仍會保留在您的裝置上。
什麼該公開,什麼必須保密#
收集程序在由 GitHub 託管的標準執行器上運行。GitHub(經核准的收集器) 及其依賴項、輔助頁面、瀏覽器以及 HTTPS 隧道,皆為此設定中 值得信賴的組件。臨時主機負責處理 Telegram 會話及 明文訊息;傳送出的建構產出會針對收件者進行加密。
透過分叉將專案程式碼複製到您的儲存庫中。這會 不是 匯出您的
Telegram 帳戶。收件者的工作流程輸入為公開加密金鑰。
保留 sealed-key.json, 從提交紀錄、工作流程輸入資料及公開日誌中提取 Telegram 憑證、登入代碼、雙因素驗證 (2FA) 密碼以及
已解密連線網址。
此工作流程會發布為期一天的加密連線/結果產出。 請及時下載兩者;此處適用 GitHub Actions 的可用性、帳戶限制及計費 規定。公開分叉並不代表可享有無限量的免費運算資源。此輔助程式不會 要求輸入任何付款資訊或 GitHub 存取憑證。
私有解密金鑰會保留在您的瀏覽器/檔案中。Telegram 會話資料 與明文記錄必然存在於臨時儲存區內。 GitHub 和 HTTPS 隧道仍屬可信基礎設施。驗證過程可能會 將檔案摘要及工作流程身分公開;但檔案內容並不會 包含在驗證中。驗證時間戳記並非訊息時間戳記。
疑難排解#
| 症狀 | 下一步 |
|---|---|
| 「不執行」工作流程按鈕 | 建立您自己的分支,啟用「動作」,並與上游同步 main。請勿編輯已獲批准的上游引腳以繞過失敗。 |
否 sealed-connection 任何遺物 |
請檢查該工作是否已啟動,並完成其啟動/上傳步驟。若發生佇列、執行器、映像檔下載、隧道或儲存庫政策等問題,都可能導致啟動失敗。 |
| 無法建立連線 | 載入本次執行所儲存的金鑰,解壓縮下載的建構產出,並選取 connection.tgwsealed。執行器必須仍處於活躍狀態。 |
| 歷史暫停了 | 請檢查控制面板的狀態,並在工作階段仍處於活躍狀態時使用「繼續」功能,或直接以已收集的資料結束操作。Telegram 的限制及無法存取的內容可能會造成資料缺漏。 |
不 sealed-result |
若在開始收集前取消或到期,則不會產生存檔;該執行程序將以「無存檔」的提示結束。收集、認證或封裝步驟若發生失敗,亦會導致無法交付;失敗的步驟會列出主管的理由,且不包含任何私人資料。無需登入憑證即可檢視該資訊。 |
| 瀏覽器無法解密大型壓縮檔 | 若套件大小超過 256 MiB,請使用以下串流 CLI。若私密金鑰錯誤或遺失,將無法解密結果。 |
| 驗證結果顯示簽署人未通過驗證 | 請使用可信賴且最新的 TgWitness 安裝版本,並使用完全相同的呼叫者 OWNER/REPOSITORY。請勿接受壓縮檔中隨附的替代政策。 |
| Telegram 仍顯示該臨時會話 | 請在「設定」→「裝置」中結束此程序。登出操作可能會失敗,而強制終止的工作流程可能不會執行清理程序。 |
在依賴此預覽版本之前,請先進行一次您能掌控的小規模測試:建立一則訊息 及附件,將其彙整,解密結果,執行驗證程式,檢查 覆蓋範圍/媒體結果,並確認 Telegram 會話已撤銷。自動化 檢查採用合成 Telegram 客戶端,並搭配獨立的真實 GitHub 憑證 測試;目前版本尚未記錄任何使用真實帳戶的執行紀錄。
本地解密與驗證#
請使用來自獨立可信來源的安裝程式中的工具,而非 由來源不明的證據檔案庫提供的可執行檔:
python -m tgwitness.sealed_crypto decrypt delivery.tgwsealed --key sealed-key.json --out delivery.zip
# Unzip delivery.zip using your archive manager, then:
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness
若為多部分傳輸,請先解密主封包,並將其解壓縮後的 清單檔放置於每個加密部分旁,然後執行:
python -m tgwitness.sealed_parts evidence.parts.json --key sealed-key.json --out evidence.zip
python -m tgwitness.sealed_verify evidence.parts.json --assembled evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness
清單是經過驗證的主體,並將所有部分與組裝好的 ZIP 檔案綁定在一起。
請使用 --max-gib 來為
大型壓縮檔設定適當的解壓縮驗證上限;預設值為 4 GiB。預期選取範圍與完整範圍檢查
同樣適用於多部分傳輸。
Python 3.11 以上版本、該專案的依賴項,以及支援
--signer-digest 以及 --deny-self-hosted-runners 。此外,亦提供一個 CLI 金鑰產生器
: python -m tgwitness.sealed_crypto keygen sealed-key.json.
驗證器會使用 tgwitness/sealed_policy.json 來自受信任的安裝來源。
它會檢查呼叫方儲存庫、上游簽署者工作流程、經核准簽署者的
提交、託管執行器需求、完整的 ZIP 摘要、內部日誌及
附件完整性、最新的帳戶金鑰來源,以及預期的收集器提交。
它會顯示歷史紀錄與媒體結果,而非暗示所有資料均已儲存。
若「已核准發行清單」為空,則會判定為失敗。更新政策是一項明確的
信任決策;切勿自動接受存檔自身所提出的政策。
若要離線使用,請事先從可信環境中取得可信根憑證:
gh attestation trusted-root > trusted_root.jsonl
python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --trusted-root trusted_root.jsonl
該證明的時間戳記僅涉及存檔方的承諾。它並不會 驗證訊息的時間戳記或收集器的實時鐘。請參閱 GitHub 的驗證選項。
如何將分叉維持在擷取程序之外#
呼叫方包含對上游可重複使用工作流程的
工作層級參照,該參照以完整的提交 SHA 為依據。該工作流程會明確地檢出 上游儲存庫
在固定的收集器 SHA 處. 預設值 actions/checkout 在可重複使用的流程中
會檢查呼叫者,並刻意不加以使用。
此工作流程不會還原呼叫者的快取、消耗呼叫者的構建產出、執行 呼叫者的檔案,也不會接受來源/映像檔網址、shell 指令、預先準備的 ZIP 檔案, 或待簽署的雜湊值。它僅接受有限定的公開收件者及會話持續時間。 動作、Python 基礎映像檔以及 cloudflared 皆透過不可變摘要進行固定; Python 依賴項則使用現有的哈希鎖定需求。該映像檔 由可信來源建置,且不使用快取。
該收集器以非 root 使用者身分執行,使用唯讀映像檔,已移除 Linux 權能、設定資源限制,且未設定 Docker 套接字或 GitHub 憑證環境。 其僅掛載新的設定、工作區及輸出目錄。 此受限的 FastAPI 應用程式提供登入、對話、可配置的帳戶或聊天記錄收集、 狀態、恢復、結束及取消等功能。其中不包含明文下載路徑、 一般管理路徑、匯入路徑或簽名端點。
監督者會在驗證操作
讀取最終修正版本之前,先停止對外連線的容器 evidence.zip 或 evidence.parts.json。打包容器不具備網路連線能力。
上傳步驟僅命名為 connection.tgwsealed 和 delivery*.tgwsealed;
既不會上傳明文證據,也不會將 Telegram 憑證作為建構產出上傳。
清理程序會移除私有目錄和容器,而 GitHub 會在任務完成後
丟棄託管執行器虛擬機器。建構產出保留期限為一天;請於到期前下載。
分支擁有者可以替換呼叫者,或建立另一個簽署檔案。 嚴格的驗證器必須拒絕由此產生的、簽署者不同的工作流程/摘要。 此機制仍取決於已核准程式碼中不存在可被利用的漏洞, 以及 GitHub 執行器與簽署基礎架構的完整性。
加密交接#
每個接收端金鑰皆為 RSA-3072(亦接受 RSA-4096 匯入),指數為 65537。 每個封套皆使用全新的隨機 AES-256 金鑰及 96 位元非重複數。 採用 SHA-256/MGF1-SHA256 的 RSA-OAEP 對 AES 金鑰進行封裝。採用 128 位元標籤的 AES-GCM 對 完整的前綴和有效載荷進行驗證。收件人的公開金鑰為 base64 編碼的 DER SPKI 格式; 私鑰檔案則包含 base64 編碼的 DER PKCS8 格式。
封套位元組包含 TGWSEAL1\n,包含一個大端序的 uint32 型別 JSON 標頭長度、
標頭、密文,以及一個 16 位元組的 GCM 標籤。標頭的長度精確為 algorithm,
key,以及 nonce;演算法為 RSA-OAEP-256+A256GCM。從前綴
到標頭的完整區段均為 GCM 額外認證資料。標頭大小上限
為 8192 位元組。CLI 可傳輸最大 8 GiB 的資料,並會在
安裝所請求的輸出前進行認證;它會拒絕覆寫現有的目標位置。
這是一種圍繞標準加密原語的專案特定封裝:
採用 SHA-256 和 AES-256-GCM 的 RSA-OAEP,可在 OpenSSL 及所有主要
加密函式庫中取得。
原始憑證位元組會在將憑證及其 驗證資訊放入加密的外層封裝之前完成驗證。此舉可避免存檔的雜湊值與 該存檔內包含的憑證之間產生循環依賴關係。 對於公開儲存庫,驗證元資料(儲存庫、工作流程、提交、 工件名稱及摘要)均為公開資訊。切勿在公開元資料中放入聊天名稱。
範圍與驗證#
此模式使用帶簽名的日誌和帳戶匯出引擎。秘密聊天、 收集前已刪除的歷史紀錄,以及帳戶無法存取的資料均 不包含在內。若已選取,私有雲端聊天亦符合資格。聊天選取器的 上限為 20,000 個對話;帳戶匯出功能會自行偵測其內容清單。遺漏的資料、失敗的檔案及未完成的 任務均會被記錄。附件限制以及執行程式的磁碟空間/時間限制仍適用。 大容量傳輸會使用加密分段,而非固定的 4 GiB 傳輸上限。 「完成」意指已凍結的選定任務已處理完畢,並非表示所有歷史 Telegram 記錄皆存在於歸檔中。聊天日誌亦可觀察即時 更新;這兩種模式均非原子快照。生成的螢幕截圖與螢幕 錄影不屬於此模式的範疇。
測試範圍涵蓋模擬首次登入、範圍隔離、媒體、取消操作、 部分截止時間完成、登出失敗、禁止的 API 路徑與欄位、 預載工作區遭拒、密鑰錯誤與篡改遭拒、必備驗證器 標誌,以及瀏覽器與 Python 加密之間的互通性。瀏覽器驗收 測試使用標示明確的模擬證明;這並非真正的 Sigstore 測試。 真正的託管執行器、Docker、GitHub 證明以及 Telegram 即時驗收測試 必須與本機模擬檢查分開報告。
GitHub Actions 條款 規定託管執行器的使用範圍僅限於軟體專案的生命週期。分叉 並不會解除這些限制;此預覽版不得宣傳為無限制的 免費生產環境託管服務。Cloudflare Quick Tunnels 亦僅供測試與開發使用。helper/workflows 適合 用於評估此功能;生產環境服務的適用資格仍屬另一項 部署要求。
維護者發行順序#
- 將收集器、監督程式、容器定義及測試提交並進行審查。
- 將該收集器提交固定在
sealed-collector.yml,然後提交/審查該 可重複使用的流程。切勿在未經通知的情況下,直接從呼叫者的 SHA 衍生出檢出版本。 - 將可重複使用的流程提交釘選至
sealed-witness.yml,並將其 workflow/collector SHA 對加入sealed_policy.json至可信發行版本中。 - 發佈所有被引用的提交及輔助程式,然後測試一個獨立的分支 以及真正的 GitHub 憑證。除非重新產生並再次發佈這些引用,否則請勿將 這些固定點所引用的提交合併掉。
請參閱可重複使用的流程與聲明 ,以了解呼叫方儲存庫與上游簽署者之間的區別。