# Telegram · 安全与数据处理

Canonical page: https://phishdestroy.io/tgwitness/zh/docs/reference/security/

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

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/zh/llms.txt)

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

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [文档](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [部署与恢复](https://phishdestroy.io/tgwitness/zh/docs/reference/deployment/)

![部署与恢复](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f)

本页描述了在本地或服务器工作区中的访问、存储和网络保护机制。 若需在 GitHub Runner 或 Intel TDX 保密虚拟机中进行数据采集，请参阅 [验证模式](https://phishdestroy.io/tgwitness/zh/docs/reference/evidence/#verification-scope)，该模式会增加对采集环境的检查。 账户连接、通知、时间戳、异地副本和见证人各有其独立的路由设置。

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

有关漏洞报告，请参阅[安全政策](https://github.com/phishdestroy/TgWitness/blob/main/.github/SECURITY.md)。

**本页内容**

- [访问模型](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#access-model)
- [面板内容与导出](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#panel-content-and-exports)
- [静态机密](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#secrets-at-rest)
- [代理和网络路由](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#proxies-and-network-routes)
- [登录与会话导入](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#sign-in-and-session-imports)
- [日志与传输](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#logs-and-transport)
- [完整性与外部时间](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#integrity-and-external-time)
- [如果您怀疑存在问题](https://phishdestroy.io/tgwitness/zh/docs/reference/security/#if-you-suspect-a-problem)

## 访问模式

主面板令牌授予完全控制权。其他人可获得各自的 [范围限定访问权限](https://phishdestroy.io/tgwitness/zh/docs/reference/access/)：指定的工作区和聊天群组、权限、有效期、 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 文件。若主密钥缺失或 错误，将导致操作失败。现有本地保险库不会被自动迁移。 该面板显示所选的密钥存储模式。无论采用哪种模式，磁盘加密都会保护本地 消息和媒体文件；有关设置的详细信息，请参阅 [连接和数据保护](https://phishdestroy.io/tgwitness/zh/docs/reference/connection/)。

## 代理服务器与网络路由

代理配置在保险库中经过加密存储。密码和 MTProxy 密钥 不会通过 API 返回，也不会写入证据记录。每个工作区可自行选择 Telegram 路由和 [IP 模式](https://phishdestroy.io/tgwitness/zh/docs/reference/connection/#ip-modes)。

**“隐藏地址”模式会**拒绝直接使用 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 捕获](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) 或者一个 [英特尔 TDX 部署](https://phishdestroy.io/tgwitness/zh/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-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` 仍可使用； [证据格式](https://phishdestroy.io/tgwitness/zh/docs/reference/evidence/#verification-scope)列出了每种采集模式下的检查项。

## 如果您怀疑存在问题

保留原始数据目录，并使用单独的副本进行分析。 通过 [安全政策](https://github.com/phishdestroy/TgWitness/blob/main/.github/SECURITY.md)报告受影响的版本、操作及可重现步骤，同时确保账户数据和凭据的私密性。
