TgWitness / 文档

已测试的内容 →

参考 / 安全与项目

Telegram · 安全与数据处理

威胁模型、访问模型、静态机密、网络暴露、会话导入以及如何报告漏洞。

TgWitness / 文档 · 部署与恢复

部署与恢复

本页描述了在本地或服务器工作区中的访问、存储和网络保护机制。 若需在 GitHub Runner 或 Intel TDX 保密虚拟机中进行数据采集,请参阅 验证模式,该模式会增加对采集环境的检查。 账户连接、通知、时间戳、异地副本和见证人各有其独立的路由设置。

领域 简而言之
访问 管理员密钥加上对账户/聊天的范围限定访问权限,包含七项权限及可撤销的会话;默认使用 localhost
静态数据中的秘密 会话、API 对、签名密钥和代理设置均采用 Fernet 算法进行加密
消息和媒体文件 工作区中的文件受主机磁盘或卷加密以及文件权限的保护
完整性 每条记录均带有 SHA-256 哈希链和 Ed25519 签名
外部时间 RFC 3161 和 OpenTimestamps 收据、由 Telegram 标注日期的见证帖以及 GitHub 认证;保留的检查点、见证记录和 Intel TDX 测量数据均作为支持性验证依据。验证器将报告其满足哪些证据条件

有关漏洞报告,请参阅安全政策。

本页内容

访问模式#

主面板令牌授予完全控制权。其他人可获得各自的 范围限定访问权限:指定的工作区和聊天群组、权限、有效期、 IP 限制、登录限制以及可撤销的会话。受聊天群组限制的访问权限 即使其权限已勾选,也无法执行整个工作区的操作。 每个工作区在同一个进程内拥有独立的日志、存储库和签名密钥; 主机上不同用户之间的隔离由操作系统账户实现。

该面板默认监听 localhost。通过浏览器登录会将访问 令牌兑换为会话凭证;浏览器将其作为承载令牌发送。该凭证存储 在 sessionStorage 中,而非身份验证 Cookie 中。锁定/注销会清除 浏览器会话。关闭浏览器或结束会话不会停止数据收集。

已签发的令牌和会话凭据以哈希值的形式保存在加密保险库中。 撤销操作将终止相关会话;权限变更将影响后续 请求。已下载的文件无法被召回。管理员也可以限制其 自身的浏览器会话,但直接使用主面板令牌的脚本仍可保留 完全访问权限,并绕过这些浏览器会话限制。

身份验证失败将根据客户端地址进行速率限制。IP 限制基于 应用程序所识别的地址;在依赖该机制之前,请先检查 反向代理的行为。Witness 凭据仍为独立的只读检查点/健康状态凭据。

演示访问#

/api/demo-access 是一个经过刻意设计的、无需身份验证的引导程序,用于明确 启动的、隔离的合成演示。它仅颁发一个独立于进程生命周期的权限, 绝不会颁发真实的面板令牌或 TGWITNESS_TOKEN 覆盖令牌。 其签发和使用需要 一个回环对等方和主机,不允许转发标头,也不允许跨源请求。额外的 工作区或授权会话将禁用此路径。实时工作区绝不会签发 该权限。该演示无法关联账户或更改收集设置。

面板内容与导出功能#

该面板不使用任何外部字体、分析工具、CDN资源或嵌入的远程媒体。 来自Telegram的文本以纯文本形式插入,而非HTML格式。下载的附件以 二进制附件形式提供。JSONL导出保留原始字符串;HTML导出则对 这些字符串进行转义;可能包含公式的CSV单元格会在前面添加一个撇号。

导出文件不包含身份验证和签名密钥,但会刻意保留 收集到的源元数据、标识符,以及可能包含的个人或敏感内容。 原始源元数据中可能包含 Telegram 访问哈希值和文件引用。

静态数据中的秘密#

Telegram API 凭据、会话密钥和签名密钥均采用 Fernet 算法进行加密。 对于本地消息和媒体文件,加密由主机磁盘或卷提供; 工作区用于存储普通文件。导出文件可采用密码保护的 AES-256 ZIP 格式, 异地副本则采用 AES-256-GCM 加密。

保险库密钥默认位于受保护的数据目录中。请使用下方的外部主密钥文件 将其单独存储。在 Unix 系统上,新的私钥文件使用权限模式 0600,新的数据 目录使用 0700;在 Windows 系统上,请为服务账户和 授权管理员设置目录访问控制列表 (ACL)。现有目录权限将予以保留。

外部主密钥#

对于新的数据目录,TGWITNESS_VAULT_KEY_FILE 可提供外部随机 主密钥。HKDF-SHA256 结合独立的随机盐值,为每个工作区生成不同的 Fernet 密钥 。为确保恢复功能,必须保留 vault.external.json 文件。若主密钥缺失或 错误,将导致操作失败。现有本地保险库不会被自动迁移。 该面板显示所选的密钥存储模式。无论采用哪种模式,磁盘加密都会保护本地 消息和媒体文件;有关设置的详细信息,请参阅 连接和数据保护。

代理服务器与网络路由#

代理配置在保险库中经过加密存储。密码和 MTProxy 密钥 不会通过 API 返回,也不会写入证据记录。每个工作区可自行选择 Telegram 路由和 IP 模式。

“隐藏地址”模式会拒绝直接使用 Telegram 备用连接,并要求通过代理处理外部 HTTP 请求。“显式选择的备用模式”允许在延迟后直接访问 Telegram; “隧道/VPN 模式”则允许直接连接。选择“隧道” 模式不会安装或验证 VPN。这些设置不会控制所有设备 流量、浏览器、软件包管理器或本地代理主机的 DNS 解析。

MTProxy 仅传输 Telegram 流量。外部请求可使用独立的 SOCKS5/HTTP 代理、工作区的 SOCKS5/HTTP 路由,或允许的直连路由; 也可将其禁用。独立见证器拥有自己的传输设置。 普通 SOCKS5/HTTP CONNECT 身份验证不会由这些代理 协议本身进行加密。伪 TLS MTProxy 密钥目前仍不支持。

登录与会话导入#

转换后的 .tgwitness-session 文件在 加载并存储到保险库之前,其中包含明文授权密钥。离线命令行界面支持经过审核的 Telethon 模式。 面板导入功能还支持 Pyrogram SQLite、现代单账户 TData ZIP 以及文档中记载的 JSON 输入格式。该功能需经过身份验证,限制为 4 个文件 / 8 MiB, 并在内存中处理上传内容,无需解压归档或保存原始文件。 规范化的凭据仅返回给请求的已认证浏览器; 在 Telegram 授权成功后,这些凭据将保存在加密保险库中。 请保护原始文件和转换后的文件,并避免多个客户端同时克隆同一授权。

TData 处理会验证容器校验和、本地解密哈希值以及结构 长度。提供的桌面端本地通行码仅临时使用,不会被存储。 受限解析器支持其验证的桌面端格式,并拒绝其他格式。 二维码在本地生成,包含短效的 Telegram 登录令牌,且 绝不会发送至外部渲染服务。锁屏、切换工作区、新登录 以及路由变更都会取消待处理的二维码尝试。 重新加载或关闭标签页可能会导致 尝试处于待处理状态直至过期。成功的 QR 登录仍会强制执行账户绑定。 普通 API 请求体仍限制为 16 KiB;经过身份验证的导入路径接受 最多 12 MiB 的编码 JSON,并单独强制执行较小的解码文件限制。

登录码和 Telegram 两步验证密码不会被持久化存储。手机号码/验证码哈希状态在 授权过程中仅保存在内存中。Telegram 会话授予账户访问权限;切勿 将数据目录、会话、令牌、保险库密钥或私有签名密钥上传至 GitHub。

日志与传输#

默认的 API 验证响应已被替换,因此不会回显凭据 值。应用程序访问日志记录已禁用。请勿配置反向代理 以记录 Authorization 头或请求正文。控制面板监听 localhost; 远程访问通过提供的 SSH 隧道、Cloudflare Tunnel 或 Caddy HTTPS 进行, 因此令牌和登录密钥在 SSH 或 TLS 内传输。

完整性与外部时间#

验证过程会将记录签名、哈希链、附件和导出清单 与收集器密钥进行比对。有效的签名表明,自 签名以来,这些字节内容未发生更改。每个工作区在首次启动时都会生成自己的签名密钥,并在面板以及每次导出中显示其 指纹。操作员通过单独的渠道将指纹提供给 接收方,并 --fingerprint 将密钥固定。

任何记录的修改、插入或删除都会破坏哈希链或签名, 验证器会报告此情况。外部时间戳和见证机制还会将日志固定在 工作区之外。SQLite 针对日志表设置的触发器仅能防止应用程序 误写或误删记录。 TGWITNESS_VAULT_KEY_FILE 将保险库 密钥排除在数据目录的副本之外。

RFC 3161 和 OpenTimestamps 收据,以及验证者从 Telegram 读取日期的见证帖, 将它们所涵盖的日志前缀与第三方设定的时间绑定在一起。 写入日志的 drand 轮次表明,其后的记录生成时间 不早于该轮次发布之时。 经过验证的 GitHub 证明也包含其签名的验证时间,这 将整个存档与外部时间绑定在一起。 检查点使用收集器密钥签名,并将截至该检查点的记录 与接收方通过其他渠道获取该检查点的时刻绑定。见证记录表明第二个 密钥保留了日志头;保管人的密钥控制记录则显示谁持有该 密钥。这两者都是辅助性验证;最低要求是第三方时间。 GitHub Actions 捕获 或者一个 英特尔 TDX 部署 添加工作流溯源信息或采集环境的硬件测量数据。

每个验证结果都会列出证据条件及其验证方式, 并按其在最小验证条件中的作用进行分组:

角色 条件
必填 完整性;使用--fingerprint固定签名者密钥;覆盖最后一条记录的外部时间戳(通过--tsa-ca验证RFC 3161收据,通过--check-bitcoin确认OpenTimestamps收据,通过--channel从t.me读取见证人帖子,见证人比特币印章或经验证的GitHub证明)
支持功能,不属于最低要求 拥有独立密钥的见证者;保留的检查点;经过认证的收集运行

作为证据的最低要求是,必须满足涵盖最后一条导出 记录的全部三个必要条件;经过验证并经认证的采集运行会添加 attested 配置文件。 最后一行给出结果,答案中列出了能够满足 缺失条件的选项。若无 --fingerprint ,则最后一行以 EVIDENCE: minimum not met · missing: confirmed signer key。 当经过验证的时间戳仅涵盖较早的记录时,答案会说明该最低条件 适用的截止记录。 --require evidence 或者 --require attested 当整个导出过程中未达到配置文件时,将以代码 2 退出; 若命令行请求的检查 无法运行,则会以相同代码报告为“未执行”。每份报告 均包含相同的条件、该副本中的状态以及用于检查 这些条件的命令。保证等级和 --strict 仍可使用; 证据格式列出了每种采集模式下的检查项。

如果您怀疑存在问题#

保留原始数据目录,并使用单独的副本进行分析。 通过 安全政策报告受影响的版本、操作及可重现步骤,同时确保账户数据和凭据的私密性。