本文说明 OpenClass-Box 的攻击面、已实现的安全控制,以及针对常见质疑的逐条核对结论。 它是给使用者、审核方(如代码签名服务商)与后续维护者看的。
一句话立场:这是一个装在教室一体机上的工具,它自己必须比它管理的机器更难被利用。 因此凡是"对外开端口"的能力(手机控制台、机房协同、临时传输、远程管理、内网穿透) 都按"可能暴露在教室网络甚至公网"来设计,而不是假设它们只在可信网络里。
| 资产 | 说明 | 泄露/被滥用的后果 |
|---|---|---|
| 配置与运行时数据 | data/ 下的配置、安全事件、收发文件 |
泄露学校网络结构;被篡改导致行为异常 |
| 访问码 / 配对码 / 密码 | 手机控制台、机房配对、远程管理、页面锁 | 被他人接管机房管理能力 |
| 机房控制权 | 下发指令、电源控制、文件下发 | 影响整间教室的教学秩序 |
| 教师机的文件 | 临时传输、远程文件收发 | 文档与个人文件泄露 |
对手类型(按现实概率排序):
- 同网段的学生机(最常见):能访问到 A 端暴露的端口,会尝试猜码、扫端口;
- 好奇的旁观者:看到"访问码 6 位"就想试;
- 公网扫描器(启用内网穿透后):无差别扫端口、试常见路径;
- 恶意插件包:伪装成插件,试图写出目录或塞入可执行文件。
不在威胁模型内:已经拿到管理员权限的本地攻击者、物理拆机、供应链攻击
(后者由签名与校验缓解,见 SIGNING.md)。
| 面 | 监听 | 鉴权 | 来源限制 | 能做什么 |
|---|---|---|---|---|
手机 Web 控制台 webconsole.py |
局域网端口 38610 | 6 位访问码 → 内存 token | 仅私有/回环地址(公网 403) | 只读状态 + 白名单修复动作 |
机房协同 net/server.py |
局域网端口 38900 | 配对码 → 节点令牌 | 无 IP 限制(需跨网段) | 白名单远程指令 |
临时传输 chat.py |
局域网端口 38620 | 房间码 + 可选密码 | 仅私有/回环地址 | 房间内消息与文件 |
远程管理 remote_admin.py |
端口 38630 | ≥8 位自设访问码 → token | 默认仅私有/回环,公网需显式开启 | 设备管理 + 白名单指令 + 电源(二次确认) |
内网穿透 tunnel.py |
不监听 | —— | —— | 把上面某个端口映射出去(由用户自备工具与凭据) |
所有"能做什么"都是枚举出来的动作,没有一个接口接受 shell 字符串。
机房指令来自 net/proto.py 的 ACTIONS;电源模式来自 power.py 的 ACTIONS;
修复动作来自 repair.py 的已定义项。想加新动作必须改代码 —— 这是刻意的。
- 访问码 / 密码只存 PBKDF2-HMAC-SHA256 散列 + 随机盐(20 万次迭代),不存明文
- 远程管理访问码强制 ≥8 位,不提供默认码(杜绝"忘了改"
- 手机控制台访问码 6 位(局域网内可接受),关闭开关即全部失效
- 会话 token 只在内存,程序重启即失效;改码会清空所有会话
- 失败锁定:手机控制台同 IP 连错 5 次锁 60 秒;远程管理连错 5 次锁 5 分钟
- 电源控制:默认关闭(需被控端显式开启);必须带确认字段;默认延迟 60 秒执行(留撤销窗口);全程审计
- A 端永不执行电源动作,只下发给 B 端
- 环境变量
OPENCLASS_SAFE_TEST=1可让电源动作只记录、不执行(演示与培训用) - 系统级修改(hosts、启动项、USB 策略、弹窗拦截)统一走
guard.py:改前快照 → 可还原 → 留痕 - 提权动作(结束进程、网络重置、创建还原点)经 UAC 显式确认,失败时给出可读原因
- 收到/下发的文件名一律清洗(去路径与非法字符),防止写穿目录
- 插件包解压:逐条校验路径(防目录穿越)+ 解压总量上限(防 zip 炸弹)+ 只允许 https + sha256 校验
- 卸载插件只删
tools/下带tool.json的目录
- 所有数据写在程序目录(或用户目录)的
data/下,不上传任何服务器 - 运行日志只记程序自身的操作与异常,不记访问码、密码、配对码
- 诊断包导出前做脱敏:用户目录 →
%USERPROFILE%,路径中的用户名 →<用户>; 包内附「隐私说明.txt」写清含什么、不含什么
| # | 审查项 | 结论 | 依据 |
|---|---|---|---|
| 1 | remote_admin.py / webconsole.py 不能执行任意命令 |
通过 | 动作全部来自白名单枚举(net/proto.ACTIONS、power.ACTIONS、repair 已定义项);无任何接口接收命令字符串。测试见 tests/test_remote_admin.py |
| 2 | 需要 UAC 的操作都有二次确认 | 通过 | 前端对清理/还原/电源/结束进程等均有确认;远程电源另有确认字段 + 延迟 + 审计 |
| 3 | 诊断包导出过滤用户名 / 路径 / 文件名 | 本次修复后通过 | 新增 logs._scrub():替换用户目录与路径中的用户名;事件日志同样处理;包内附隐私说明。原先未做脱敏,这是本轮修掉的真实问题 |
| 4 | 日志不记录访问码、密码等敏感信息 | 通过 | applog 无凭据写入点;远程管理只记录"登录成功/访问码错误"这类事件,不含码本身 |
| 5 | 局域网功能只接受 LAN 来源 | 部分按设计放宽 | 手机控制台、临时传输:严格限私有/回环;机房协同不限(需支持跨网段),改以"配对码 + 节点令牌"为边界;远程管理默认限内网,公网需显式开关并提示风险 |
| 6 | API 响应超过 1 秒有警告日志 | 本次补齐后通过 | 新增 api.timed() 装饰器,阈值 1.0 秒,超时写 WARN 到运行日志;已标注体检、诊断包、硬件详情、清理分析、课堂检测等 5 个耗时接口 |
| 7 | 是否测试过 Windows 10 LTSC / Windows 11 | 未完成 | 开发环境为 Windows 10 专业版;LTSC(无应用商店 / 精简组件)与 Win11 24H2+ 需实机验证,列入待办 |
- 机房协同不做 IP 限制:教室 A/B 端可能不在同一网段(跨 VLAN、经映射), 强制内网会直接让功能不可用。安全边界改为配对码 + 令牌;请在不需要时停止服务。
- 公网访问是显式风险:远程管理的「允许公网来源」必须手动打开, 界面会同时提示风险。请配合足够长的访问码使用;不需要时及时关闭。
- tunnel 拉起的是第三方工具:命令构造与执行分离、参数存本地, 但穿透链路本身的安全性取决于所选服务(cloudflared 自带 HTTPS;frp 需自备服务器)。
- 本机渲染偶发黑屏用"关 GPU 合成"兜底:这是兼容性取舍,不是安全问题; 现在可以在「设置 → 系统集成 → 渲染模式」里切回性能优先。
- Windows 10 LTSC / Windows 11 实机兼容性验证(尤其 WebView2 与托盘)
- 插件协议版本化(
manifestVersion/permissions/publisher)与安装前权限展示 - 插件市场索引签名与版本回滚
- 为
chat.py/net/server.py补针对非法请求、超时、重复节点的测试 - 定时任务的"运行权限选择"(普通 / 管理员)—— 当前统一按当前用户权限执行
请通过仓库 Issues 反馈,不要在公开 Issue 里贴出访问码、配对码或内网地址。 涉及具体教室环境的截图,请先打码主机名与 IP。