TgWitness / 文档

已测试的内容 →

文档 / 02

Telegram · GitHub Actions 捕获

在临时 GitHub runner 上选择 Takeout、常规 API 导出或聊天日志.

完整引用

TgWitness / 文档 · 独立捕获

独立捕获

可从 main 预览。一个分支会从 phishdestroy/TgWitness。该工作流通过新创建的 Telegram 会话导出账户、选定的聊天记录或某条 聊天的事件日志,对证据 ZIP 文件或多部分清单进行认证,并仅上传 收件人加密的交接数据。常规管理面板不会对外公开。

选择 client=official_web 以运行带受保护的Telegram Web控件和视频功能的官方客户端见证程序。这需要您自己的上游代理,并仅监视一个已渲染的聊天窗口。默认情况下 client=api 保留了下文所述的完整账户导出模式。

验证器会根据 GitHub 证明、已批准的 工作流和收集器提交记录,以及已签名的日志和附件哈希值,对归档文件进行核对。 收集过程使用固定的上游代码和新的存储空间。审核员 可以检查该代码,并根据记录的运行情况对交付的归档文件进行验证。

本页内容

用户流程#

该辅助工具会讲解这五个阶段,并让您在示例数据上尝试消息或收集器 替换。点击开始捕获即可打开向导。

  1. 在项目主页、 工作区登录界面或导出→打开捕获助手中选择GitHub Actions 捕获(预览版)。您还可以 在现代浏览器中,从可信的代码检出中打开官方助手 或 tgwitness/static/capture.html。 该辅助程序在处理密钥或 文件时不会发起任何网络请求。该辅助程序支持本网站的界面语言; 临时收集面板支持英语和俄语,当浏览器语言为上述两种之一时, 面板将以该语言显示。
  2. 生成密钥并保存 sealed-key.json 文件。这是唯一的 私有解密密钥。复制单独的收件人公钥值。一旦丢失 私有密钥,将无法访问连接和归档文件。 请确认已保存该密钥,以便解锁下一步。如果您已有 交付文件,请加载已保存的密钥,并选择我已有归档文件。
  3. 分叉 TgWitness,在分叉中启用“操作”功能,并运行密封聊天捕获。 粘贴公开收件人,并选择 30、60 或 120 分钟。切勿在 工作流输入、提交、问题或日志中填写 电话号码、登录码、Telegram 密码、私钥或会话信息。
  4. 运行期间,请从“构建产物”中下载 sealed-connection 并解压。 在 connection.tgwsealed ,并使用已保存的私钥。 生成的链接在其 URL 片段中包含一个随机的访问密钥。 请妥善保管此链接。控制面板会移除该片段,并将密钥 保存在此标签页的会话存储中;该密钥不会被记录在 HTTP 访问日志中。
  5. 打开连接链接。使用二维码登录,或使用您的手机号码和 登录码登录。如果 Telegram 要求输入,请输入您的两步验证密码。默认情况下, 系统会使用内置的 API 凭据池,这与普通工作区一样。您 可以展开可选的自定义凭据部分,并输入以下两项 api_id 和 api_hash 来自 my.telegram.org/apps 的信息。若要使用内置凭据池,请将这两个 字段均留空;不完整或格式错误的凭据对将被拒绝。 不允许导入会话。请选择导出模式和范围。连接 链接中包含访问密钥:请务必保密。
  6. 选择Telegram Takeout、常规 Telegram API或聊天事件日志。 若要导出账户数据,请选择所有可访问的聊天记录,或加载并选择一个或多个 聊天记录,然后设置日期、聊天类型、账户类别和附件规则。 检查设置和大小,可选择将设置 JSON 保存供独立 审核人员查看,然后点击开始捕获。开始后设置即无法更改。 “恢复”功能仅在该运行器存在时有效;提前结束将保留已获取的 数据并记录缺失部分。开始后截止时间到期将生成一个明确的 部分存档;开始前到期或取消操作则不会生成任何存档。
  7. 等待密封结果,下载并解压,然后在 delivery.tgwsealed 。您将收到 delivery.zip,其中包含 evidence.zip, attestation.jsonl以及操作说明。浏览器解密 上限为256 MiB;更大的包请使用下方的本地流式解密命令。 大型结果还包含 delivery-NNNNNN.tgwsealed 多个部分;主 delivery.tgwsealed 文件中包含 evidence.parts.json 和证明。 请下载所有部分,并按照下文所述在本地进行组装。
  8. 如果撤销操作 未被确认,或者运行进程被终止,请在 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 凭据、登录码、双因素认证密码以及 已解密连接 URL。

该工作流会发布一天内的加密连接/结果工件。 请及时下载这两项内容;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 摘要、内部日志和 附件的完整性、最新的 account-key 来源,以及预期的收集器提交。 它会显示历史记录和媒体结果,而非默认所有数据均已保存。 若“已批准发布”列表为空,则验证失败。更新策略是一项明确的 信任决策;切勿自动接受归档文件自身提出的策略。

若需离线使用,请提前从可信环境获取可信根证书:

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 在可重用工作流中 会检出调用者,且该操作是故意不被使用的。

该工作流不会恢复调用者的缓存、消耗调用者的构建产物、执行 调用者的文件,也不会接受源/镜像 URL、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 的数据流,并在 安装请求的输出前进行认证;它拒绝覆盖现有目标。 这是一个围绕标准密码学原语构建的项目专用封装: RSA-OAEP 结合 SHA-256 和 AES-256-GCM,可在 OpenSSL 及所有主流 密码学库中使用。

在将证据和 认证信息放入加密的外层包之前,会对原始证据字节进行认证。这样可以避免 归档文件的哈希值与其自身包含的证书之间产生循环依赖。 对于公共仓库,认证元数据(仓库、工作流、提交、 工件名称和摘要)是公开的。切勿在公共元数据中包含聊天名称。

范围与验证#

此模式使用带签名的日志和账户导出引擎。秘密聊天、 收集前的已删除历史记录以及账户无法访问的数据均 被排除在外。若已选中,私有云聊天也符合条件。聊天选择器 上限为 20,000 个对话;账户导出功能会自动检测其库存。缺失的数据、失败的文件和未完成的 任务都会被记录下来。附件限制以及运行程序的磁盘/时间限制仍然适用。 大文件传输使用加密分段传输,而非固定的 4 GiB 传输上限。 “完成”指已冻结的选定任务已完成,并不意味着所有历史 Telegram 记录都存在于存档中。聊天日志也可观察实时 更新;这两种模式均非原子快照。生成的截图和屏幕 录像不属于此模式的范围。

测试内容涵盖合成新登录、作用域隔离、媒体、取消操作、 部分截止时间完成、注销失败、受限的 API 路径和字段、 预加载工作区拒绝、密钥错误和篡改拒绝、必需的验证器 标志,以及浏览器/Python 加密互操作性。浏览器验收 测试使用了一个明确标记的模拟证明;这不是真正的 Sigstore 测试。 真实的托管运行器、Docker、GitHub 证明以及实时 Telegram 验收 测试的结果必须与本地合成测试的结果分开报告。

GitHub Actions 条款 规定托管运行器的使用仅限于软件项目的生命周期内。分叉操作 不会解除这些限制;不得将此预览版宣传为无限制的 免费生产环境托管服务。Cloudflare Quick Tunnels 同样仅适用于测试和开发。helper/workflows 适合 用于评估此功能;生产环境的适用性仍是另一项 部署要求。

维护者发布顺序#

  1. 提交并审查收集器、监督器、容器定义和测试。
  2. 将该收集器提交固定在 sealed-collector.yml,然后提交/审查该 可重用工作流。切勿默认从调用者的 SHA 值推导出检出版本。
  3. 将可重用工作流的提交固定在 sealed-witness.yml ,并将它的 workflow/collector SHA 对添加到 sealed_policy.json 可信发布中。
  4. 发布所有被引用的提交以及辅助程序,然后测试一个独立的分支 以及真正的 GitHub 证书。除非重新生成并再次发布这些引用,否则请勿将 这些引用的提交合并掉。

有关调用者存储库与上游签名者之间的区别,请参阅可重用工作流和确认声明 。