nex_squid/docs/SECURITY.md

65 lines
5.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 安全说明
squid 是一个「以删除为职责、以不删错为底线」的工具。它拥有当前用户的完整文件权限,因此威胁模型与普通的 CLI 不同:**最大的风险不是被攻击,而是它自己删错东西。**
## 权限边界
- squid 以当前用户身份运行,**不需要** root,也不安装任何 launch agent / 服务 / 内核扩展。
- 非 root 时 `SafetyPolicy::user_only()` 生效,家目录之外的路径一律不删除;只有显式用管理员权限运行时才切换到 `SafetyPolicy::system()`。
- 需要管理员权限的规则(`needs_admin`)在普通权限下只报告、不执行;`squid clean --user-only` 可以彻底跳过它们。
- 不联网:`Cargo.toml` 的依赖树里没有 HTTP 客户端,squid 不上传任何遥测、路径或文件名。
## Full Disk Access(macOS)
`~/Library/Safari`、`~/Library/Mail`、`~/Library/Messages` 等目录受 TCC 保护。终端未授权时,squid 只会读不到、跳过它们,不会报错崩溃。`squid doctor` 会列出被拒绝的目录。若希望这些规则真正命中,请在 系统设置 → 隐私与安全性 → 完整磁盘访问权限 中勾选你运行 squid 的终端。
注意:**授权 Full Disk Access 增加的是读取能力,不是删除范围**——上面那张安全表(`HARD_DENY`/`DENY_EXACT`/锚点)在任何权限级别下都同样生效。
## 删除的多重防线
1. 默认 `Trash`:删除等于 `rename` 到回收站,`squid undo` 可以还原。
2. `--dry-run`:所有破坏性命令都支持。
3. 非交互确认:stdin 不是 TTY 且没有 `-y/--yes` 时直接拒绝执行删除(保护 CI 与 `curl | sh` 式误用)。
4. 删除时二次校验:不复用扫描结论,逐条重新检查锁、白名单、安全策略与锚点。
5. 永不跟随符号链接:`walkdir::follow_links(false)` + `symlink_metadata` 判定类型,避免把「指向 `~/Documents` 的软链接」当成缓存删掉。
6. 账本:每次真实删除写一个会话文件(含每条的原始路径与废纸篓目标),`history_keep` 控制保留数量。
7. 白名单:`squid whitelist add <glob>` 之后该路径在任何面板中都不再被选中。
## 用户输入与外部数据
- **配置文件与规则文件按 TOML 解析,绝不当作代码执行。** 解析失败时降级为默认值,错误通过 `squid doctor` / 引擎的 `settings_errors` 报告,不会 panic。
- 规则模式经 `globset` 编译,`*` 不跨越路径分隔符;`~` 只在家目录下展开。
- 卸载残留的名称匹配区分大小写归一化,且显式排除了文档后缀(`.pdf`、`.png`、`.mp3`…),避免把用户文档当成 App 残留。
- 外部命令一律用 `Command::new(program).args([...])` 直接传参,**不经过 shell**,参数也不来自不可信输入,因此不存在命令注入面。清单如下:
| 命令 | 用途 | 是否修改系统 |
| --- | --- | --- |
| `sw_vers`、`sysctl`、`ps`、`df`、`diskutil`、`pmset`、`ioreg`、`vm_stat`、`tmutil list` | 系统信息与体积探测 | 否,只读 |
| `open`、`xdg-open`、`explorer` | 打开废纸篓 / 在访达中显示 | 否 |
| `git check-ignore`、`git ls-files`、`tmutil listlocalsnapshots` | 判断构建产物是否被 git 忽略(被跟踪的文件绝不删除)、列举 APFS 本地快照 | 否 |
| `launchctl`、`lsregister` | 卸载前停掉 App 的 launchd 任务、注销 Launch Services 注册 | 是,仅 `squid uninstall` 确认之后 |
| `brew uninstall --cask --force` | App 由 Homebrew 安装时优先交给 brew 处理 | 是,仅 `squid uninstall` 确认之后,且只在检测到对应 cask 时 |
| `flatpak` / `snap` | Linux 应用清单与卸载建议 | 清单只读;卸载建议以提示形式给出 |
## 什么不属于安全问题
- 规则没有覆盖到某个 App 的缓存 → 功能缺口,开 issue 即可。
- 磁盘空间没有你预期释放得多 → 可能是 APFS 快照或 purge 的年龄过滤,先用 `squid analyze` 对照。
- 需要 Full Disk Access 才能读到的目录 → macOS 的限制,见上。
## 报告漏洞
如果你发现 squid **可能删除用户未主动选择的数据**(例如某条规则在默认配置下选中了 `~/Documents`、锚点校验可被绕过、`undo` 覆盖已有文件),请视为安全问题:
- 通过仓库的 private issue / security contact 私下披露;
- 附上最小复现(哪个命令、哪个规则 id、哪个路径);
- **先跑 `--dry-run` 采集证据**,不要提供真实删除的日志。
我们会在修复版本发布后再公开细节。
## 你自己的责任
- squid 不是备份工具。重要数据请依赖 Time Machine 或对象存储。
- `--permanent` 跳过回收站,`undo` 也救不回来;除非你确切知道自己在做什么,否则不要用。
- 自定义规则里 `mode = "contents"` 会清空目录内容,`patterns` 只写一个字面目录(例如 `~/Library`)会被安全策略拒绝——如果你绕过或删除了 `crates/squid-core/src/safety.rs` 的守卫,squid 就不再保护你。