# 安全与数据处理

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

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

TgWitness 可在您的计算机或服务器上运行。账户连接、公共代理列表维护以及可选的外部服务均设有 明确的路由策略。通知、时间戳、异地副本和见证人 均可单独配置。本页面列出了受保护的内容、保护方式以及 由操作员自行决定的事项。

| 领域 | 简而言之 |
| --- | --- |
| 访问 | 管理员密钥加上对账户/聊天的范围限定访问权限，包含七项权限及可撤销的会话；默认使用 localhost |
| 静态数据中的秘密 | 会话、API 对、签名密钥和代理设置均采用 Fernet 算法进行加密 |
| 消息和媒体文件 | 数据以明文形式存储：请使用磁盘加密并设置严格的权限 |
| 完整性 | 每条记录均带有 SHA-256 哈希链和 Ed25519 签名 |
| 未涵盖 | 机器管理员、泄露的控制面板令牌、捕获的完整性 |

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

## 访问模式

主面板令牌授予完全控制权。其他用户可获得各自的 [范围限定访问权限](https://phishdestroy.github.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 凭据、StringSession 以及 Ed25519 私钥均使用 Fernet 进行加密。默认情况下，其密钥存储在同一受保护的数据目录中。 这可减少明文意外泄露的风险；但无法防范能够读取整个目录的攻击者。 TgWitness 不会对消息内容和媒体文件进行**加密** 。请使用磁盘加密并设置严格的操作系统权限。Unix 私钥 文件创建时采用 0600 权限模式；新创建的数据目录采用 0700 权限模式。 现有目录的权限不会被更改。Windows 会继承目录的访问控制列表 (ACL)：请将其 限制为服务账户和授权管理员。

### 外部主密钥

对于新的数据目录，TGWITNESS_VAULT_KEY_FILE 可提供一个外部随机 主密钥。 系统会通过 HKDF-SHA256 及独立的随机盐值，为每个工作区生成不同的 Fernet 密钥。 为确保恢复功能，必须保留 vault.external.json 文件。若主密钥缺失或 错误，系统将无法启动。现有本地保险库不会被自动迁移。 运行中的进程可以访问该密钥；这并非 HSM 隔离。控制面板会报告 所选模式，并明确说明消息/媒体存储不会由应用程序 进行加密。有关完整的威胁模型，请参阅[“连接”、“代理”和“数据保护”部分](https://phishdestroy.github.io/TgWitness/zh/docs/reference/connection/) 。

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

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

“隐藏 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 授权成功后，这些凭据将保存在加密保险库中。 请保护原始文件和转换后的文件，并避免多个客户端同时克隆同一授权。

数据处理过程会验证容器校验和、本地解密哈希值以及结构 长度。系统会临时使用用户提供的 Desktop 本地密码，且不会将其存储。 此有限解析器无法保证所有 Desktop 版本均兼容。 QR 图像在本地生成，包含短效的 Telegram 登录令牌，且 绝不会发送至外部渲染服务。锁屏、切换工作区、新登录 以及路由变更都会取消待处理的 QR 尝试。刷新或关闭标签页可能会导致 尝试处于待处理状态直至过期。成功的 QR 登录仍会强制执行账户绑定。 普通 API 请求主体仍限制为 16 KiB；经过身份验证的导入路径接受 最多 12 MiB 的编码 JSON，并单独执行较小的解码文件大小限制。

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

## 日志与传输

默认的 API 验证响应已被替换，因此不会回显凭据 值。应用程序访问日志功能已禁用。请勿配置反向代理 以记录 Authorization 头或请求正文。HTTP 以明文形式传输令牌和登录 密钥：只要连接离开 localhost，请务必使用 HTTPS 或 SSH 隧道。

## 完整性限制

哈希链、数据库触发器和签名可检测到某些修改； 但无法阻止本地管理员重写日志并重新签名。 请将已签名的检查点和公钥指纹保存在独立系统中。 证据模式和异地副本（默认均处于关闭状态）会将检查点哈希值发送至 时间戳服务，并将加密副本发送至兼容 S3 的存储；请参阅 [证据格式](https://phishdestroy.github.io/TgWitness/zh/docs/reference/evidence/)。透明度日志、基于 HSM 的签名以及正式的 证据链认证尚未实现。

## 如果您怀疑存在问题

请保留原始数据目录，并使用另一份副本进行分析。请勿 在公开问题中包含私人的 Telegram 数据或凭据。本工具不 声称拥有任何独立的安全认证。