Skip to content

Security: mico-v/usts-cli

Security

docs/security.md

安全基线

凭证与会话

  • 会话默认保存到操作系统用户状态目录,而不是当前项目目录。
  • Linux 默认:~/.local/state/usts-cli/session.json
  • 状态目录权限为 0700,会话文件权限为 0600,使用临时文件和原子重命名保存。
  • 会话文件必须带 origin 且与当前 USTS_BASE_URL 一致才会被加载,否则直接忽略。
  • 旧版 cwd .session.jsonADR-0004不再读取,仅在启动时提示清理。
  • 会话文件里是明文 bearer tokenJSESSIONID/rememberMe),其效力等同于密码:拿到它就能取全部数据,无需密码与二次验证。0600 只挡其他用户,不挡以同一用户身份运行的进程,也不挡家目录被备份、同步或打快照。当前未接系统凭证管理器(libsecret / Keychain / DPAPI),文件加密也不在计划内 —— 请按与密码同等的敏感度对待。
  • usts logout 只做本地失效(删除会话文件 + 清空内存 Cookie,不发网络请求),服务端会话在其有效期内仍然可用;需要真正失效只能在浏览器中退出登录。不再使用的会话应及时 usts logout,不要留在磁盘上。
  • CLI 自身不写入账号密码;密码只来自配置文件(用户配置目录下的 .env)或交互输入。注意自动重新登录依赖配置里的 USTS_PASSWORD,因此配置后它会长期留在磁盘上(这是可用性与本地秘密存放之间的取舍)。
  • 配置文件若允许组用户/其他用户读取,启动时发出警告。

网络信任边界

  • 默认只向 jwgl.usts.edu.cn 的 HTTPS 地址发送凭证。
  • 自定义主机必须设置 USTS_ALLOW_CUSTOM_HOST=1
  • 明文 HTTP 还必须额外设置 USTS_ALLOW_INSECURE_HTTP=1,仅供本地测试。
  • 这两个开关只认真实进程环境变量:写在配置文件里会被忽略并告警。它们的作用是放宽信任边界,而配置文件比 shell 环境更容易被复制、同步、随项目分发,不能让它解除自己的限制(ADR-0005)。
  • 配置文件(.env)只从用户配置目录读取,不读当前工作目录——否则 cd 进一个带 .env 的目录就等于让该目录决定凭据发往哪台主机(ADR-0005)。
  • 服务端返回的下载 URL 必须与配置的教务系统同源,跨源地址不携带 Cookie并直接拒绝。
  • 保持 TLS 证书验证开启,不固定 CDN IP,不绕过 SNI/DNS 调度。

输出与抓包

  • 人类可读终端输出移除 ANSI、C0/C1 控制字符与 Unicode 双向/零宽格式符(后者能在终端里伪造出不存在的文本)。覆盖 cli/render/* 与交互式菜单(学院/专业/班级名同样来自远端)。
  • 日志不得记录 Cookie、Set-Cookie、密码、csrftoken、bearer token(JSESSIONID / rememberMe) 或完整学号。脱敏由 shared/sanitize.tsredactSecret 统一完成,所有可能夹带这些内容的输出口(命令层、交互层、顶层异常)都必须过它。
  • captures/ 及其中 Cookie、HTML、HAR、JSONL 均按敏感数据处理,目录 0700、文件 0600
  • 原始抓包不进入 Git 或 npm 包。

请求安全

  • 只读、认证、下载、写操作具有不同重试策略。
  • 写操作默认不重试。
  • HTTP 响应和请求体设置大小上限,避免异常响应耗尽内存。
  • 触发 WAF 后应进入冷却,不通过增加并发规避限制。

只读边界

CLI 只实现查询。以下远端写操作有意不实现,即使它们与已实现的查询共用同一个页面或模块:

  • 学生缴费:支付、释放缴费中订单、生成订单、退费申请(paycenter_* 的写接口)。
  • 各类申请与报名的提交:学籍异动、辅修/重修报名、学生证补办、转专业、成绩与学分认定、退书等。
  • 学生评价(评教)的保存与提交、个人信息维护的申请/修改/删除、毕业照片确认。
  • 自主选课的选课与退课。

理由:这些操作要么涉及金钱,要么不可逆,要么会产生真实教务流程副作用(例如评教未完成会被限制登录)。 只读 CLI 提供不了「幂等语义 + 可撤销 + 二次确认」这层安全网,因此不做;effect: 'mutation' 的重试与会话重放策略(见 接口契约)也就没有实际使用者。

There aren't any published security advisories