Skip to content

Security: ruanbw/agent-sweep

Security

docs/SECURITY.md

安全模型

这份文档说明 AgentSweep 信任什么、不信任什么,以及每条边界的依据。 它不是「安全承诺清单」:写在这里的每一条都能在代码里找到对应实现, 反过来,代码里做不到的事情这里也不会写得更好听。

适用范围是 AgentSweep 自身:自更新、删除/撤销、本机 HTTP 接口。 不在范围内的是它读取的第三方 Agent 数据格式,以及 macOS 本身。

更新信任模型

实际走的链路

  1. HTTPS 请求 api.github.com 的 /releases/latest,拿到发布 JSON;
  2. 按资产名挑 zip,校验下载地址的 host 白名单(含每一跳重定向);
  3. 下载 zip 到用户缓存目录;
  4. 取同一个发布里的 checksums.txt,核对 zip 的 SHA-256;
  5. 解压(单根 .app、拒绝越界路径与可疑符号链接、限制条目数与解压体积);
  6. 核对包内 Info.plist 版本等于发布 tag、且高于当前版本;lipo 确认架构匹配;
  7. 复制到旁边、校验、两次 rename 换位,删除旧包;
  8. 去掉 com.apple.quarantine,签名失效则做一次 ad-hoc 重签。

每一步都在「证明某件事」,但没有一步在证明发布者是谁。第 4 步尤其容易被误读: 清单和包来自同一个 Release,它们只互相印证,不构成外部信任根。

威胁模型

场景 现在能挡住吗 依据 / 原因
传输过程中字节损坏、连接被截断 能 下载先写 .part 再改名;SHA-256 不一致直接放弃安装
发布时上传错包、版本号与 tag 不一致 能 包内 Info.plist 版本必须等于发布 tag
发布 JSON 把下载地址指到陌生域名 能 只允许 https 的 GitHub 发布域名;重定向逐跳复查
攻击者在 zip 里塞 ../、第二个顶层目录、指向系统路径的符号链接 能 解压只接受单根 .app,拒绝越界路径与可疑链接
压缩炸弹(解压后几个 GB、几万个条目) 能 条目数上限 20000、声明与实际写出字节都限制在 1 GB
更新包装了错误架构(更新完打不开) 能(本机有 lipo 时) lipo -archs 必须包含本机架构;lipo 缺失时这一步跳过,只靠后续启动失败暴露
网络中间人(不劫持系统证书) 能 全程 HTTPS,且只连固定 host
GitHub 账号 / 仓库写权限被攻破 不能 攻击者可同时替换 zip 与 checksums.txt,整条链不会报警
GitHub Release 被平台侧篡改或误操作 不能 同上:没有独立于发布渠道的信任根
发布者本人(或拿到其设备的人)发布恶意包 不能 没有可核验的身份,也没有可对比的签名
构建机 / 上游依赖被投毒 不能 产物只对「构建出来的字节」负责,不对构建过程负责
同机其它进程以同一用户身份改写解压目录 不能 SHA-256 只覆盖压缩包;解压后的树在校验与复制之间不会再算一次哈希
用旧版本降级攻击 部分 只接受更高的 semver,但攻击者若能改发布,直接发更高版本即可

结论:这条链防护的是传输与打包事故,不是发布授权。 真正的信任边界是 GitHub 账号、仓库写权限和 HTTPS,加上「清单与包出自同一次发布」 这条自洽性约束。仓库或账号失守时,更新器会把攻击者的包当成正常更新装上去, 并以当前用户权限运行。

为什么是 ad-hoc 签名

产物用 codesign --sign - 做 ad-hoc 签名,没有 Developer ID,也没有 Apple 公证。 这是成本取舍,不是疏忽:

  • ad-hoc 重签的唯一作用是让替换后的包还能运行。它贴的是本机临时身份, 没有证书链、没有团队 ID,不比替换前更可信;
  • codesign --verify 只回答「签名与内容是否自洽」。任何能写文件的人都能生成 一份能通过校验的 ad-hoc 签名,所以它不是身份验证;
  • 未公证意味着 Gatekeeper 也给不出「发布者是谁」的结论,而更新器还会主动移除 com.apple.quarantine,等于放弃这层系统检查;
  • 因此代码里不会再加「多 verify 一次」「打印签名有效」这类动作。那只会制造 虚假的安全感,让调用方误以为身份已经核验过。

要真正提升保证,得换信任根,而不是加校验步骤:

  • Developer ID 签名 + notarytool 公证:Gatekeeper 能回答「谁发布的」, 代价是付费开发者账号与发布流程中的额外一步;
  • Minisign/EdDSA 签 checksums.txt:公钥编进二进制,私钥只存在 CI secret 或离线介质,代价是密钥轮换需要发新版;
  • 两者都不改变「清单与包必须同源」。如果引入签名校验,位置固定在 Install 里下载完成之后、解压之前——此刻还是发布方签过的那份原始字节; 挪到解压之后就只剩「包内自洽」,证明力归零。

数据安全边界

删除是应用里唯一会真正改动用户数据的动作:trash 可以撤销,permanent 不能。 所以护栏都压在「动磁盘之前」。

路径必须在数据根内

删除路径一律先过 internal/clean 的 checkPathInHome。它分两层,两层都要过:

  • 词法层:用 filepath.Rel 计算与数据根的关系,绝对路径、..、以及 相对结果为 .(即数据根本身)一律拒绝。它不依赖文件系统状态,路径不存在时 也能给出结论;
  • 真实路径层:先 EvalSymlinks 数据根,再解析待删路径的父目录、 把原 basename 拼回去,然后重新做一次包含性判断。父目录里的中间层符号链接 会被展开,最后一段保持原样,所以删链接本身仍然安全。

路径不存在是正常情况(用户可能刚手动清过、或同一条会话的上一步已经删掉), 此时退回词法层的结论,不把「不存在」误判成越界。

同一套护栏也用在适配器声明里的相对路径(索引库、SQLite 库)上:自定义适配器是 adapters.json 里的用户可写数据,不能假设它一定安全。

两种删除模式,语义分开

  • trash(默认):正文移进 ~/.Trash/AgentSweep/<batchID>,可撤销。 废纸篓只是挪了位置,磁盘并没有释放,所以不计入「已释放空间」;
  • permanent:os.RemoveAll + SQLite VACUUM,只有真正收缩掉的空间才计入。

「移入废纸篓」和「真实释放」在 UI 上始终分开显示。把前者算成后者,是在向用户 谎报战果。

先能备份,才允许动

索引和 SQLite 库一旦被改,原始内容就只存在于备份里。所以每个对象都是 「先备份,再改」:数据库在删行前整库复制一份,索引在裁剪前整文件备份一份, 备份失败就跳过这一项并记一条错误——而不是先改后补。

备份放在 ~/Library/Application Support/AgentSweep/backups/<batchID>/,目录 0700。 这也解释了为什么 permanent 模式并不等于「什么都没有」:数据库型会话仍有一份 删行前的整库副本,撤销时整份覆盖回去;只有文件型正文是真的没了。

journal 逐步落盘

任何破坏性动作之前,先写一份空 journal;之后每成功移走/删除一个路径就原子重写一次。

  • 原子写是「临时文件 → fsync → rename → 目录 fsync」,掉电后不会出现 「删了但没有账本」;
  • journal 与备份目录都是 0700,journal 文件 0600:里面是会话 ID 和绝对路径, 属于用户隐私;
  • 写不进去就立刻停手并返回错误。继续删只会扩大「无法撤销」的范围;
  • 进程中途被 kill 时,磁盘上至少有一份能说明「已经动了哪些路径」的账本。

撤销前重放越界校验

journal 是磁盘上一份可以被改写的 JSON(当前用户的权限、未来的导入接口都可能 改它)。所以撤销不把里面的路径当成可信输入:

  • 撤销时用 journal 里记下的数据根 Home,对每一条待恢复路径重新跑一遍 checkPathInHome,位置在任何文件系统探测之前;
  • 旧版本写的 journal 没有 Home 字段,直接拒绝恢复(fail-closed),并提示按 moved 记录手工处理。缺字段不等于「无需校验」;
  • 单条被拒只记错误,不影响其它条目;
  • 只有整批没有任何错误才标记 undone;部分失败保持可重试,已恢复的条目在重试时 会被安全跳过。

另外,permanent 且没有任何 SQLite 备份的批次拒绝撤销:正文已经永久删除, 把索引覆盖回去只会得到点进去是空的幽灵会话,比不撤销更糟。

本机 HTTP 接口

agentsweep serve 可以删会话、也能触发一次自我替换,所以默认只接受回环来源:

  • 非本机 RemoteAddr、非回环 Host 一律拒绝,即使有人把它 bind 到 0.0.0.0;
  • 写请求要求 Origin 与当前 Host 同源,且只收 application/json, 挡掉不需要预检的表单型 CSRF;
  • 桌面壳走 wails://,不经过这层,因为它的来源就是应用自身。

已知限制

  • 没有发布者签名,没有公证。 见上文。这是当前最大的、且是设计层面的缺口: 它不能被「更多的校验步骤」补上,只能靠换信任根。
  • 跨进程靠同目录文件锁,不是全局互斥。 clean 包用包级 sync.Mutex 串行化 同一进程内的删除与撤销,再对 backups/journal 的父目录(正常即应用数据目录) 下的 .clean.lock 取排他 flock(LOCK_EX|LOCK_NB,最多等 5 秒)把其它进程 挡在外面。GUI 开着时再跑 agentsweep clean,第二个进程会明确失败而不是一起改 账本。锁文件放在父目录而不是 journal 目录里,是因为它同时保护 backups 与 journal,而 journal 目录自身不可写时应当报「写盘失败」而不是「另一个进程在清理」。 边界在于:锁保护的是这一份 backups/journal,不是「这台机器上的删除」——把 BackupDir/JournalDir 指到不同目录的两个实例互不阻塞;锁也是按打开的文件 描述符算的,不跨用户、不跨机器。等待超时是错误,不是「可以继续」。
  • 文件锁挡不住绕过它的人。 恶意进程可以直接改 journal 或废纸篓里的文件, flock 只对「愿意先拿锁」的调用者有效;撤销侧的重放校验才是最后一道防线。
  • 替换不是一步原子的。 旧包改名与新包换位之间如果崩溃/断电,目录里只剩 AgentSweep.app.old-<时间戳>,应用「消失」。这是已知的手工恢复场景, 不是可以通过重试消掉的错误。
  • 同用户的本地攻击者不在威胁模型内。 更新缓存目录、备份目录、journal 都是 当前用户可写;恶意进程以同一身份运行时,能做的事远多于本应用能防的范围。
  • 删除的可撤销性依赖磁盘上的 journal。 journal 被删除或损坏时,撤销入口会 如实失败,不会假装成功;此时只能按 ~/.Trash/AgentSweep/ 里的目录手工恢复。
  • /Applications 需要可写。 安装过程不需要管理员权限,但如果用户把应用装在 只有 root 能写的目录里,替换会因为权限失败——这是明确报错,不是静默跳过。

本轮仍未闭合的残余风险

下面这些是审计确认过、但本轮刻意不改的项。它们不是遗忘:每一项要么需要 结构性改造,要么收益与复杂度不匹配。写在这里是为了让后来者知道现状与闭合路径, 而不是把「没修」当成「已修」。

上一版里列的删除路径 TOCTOU、只信 Paths、journal 动作后记账、glob 单层宽度、 符号链接体积口径、Freed/Count 口径已经在本轮闭合或写进代码注释,不再作为风险 列出(见本节末尾一句小结)。

撤销路径仍未 fd 化

风险:Undo 仍用 movePath 按路径把正文从废纸篓搬回 journal.Orig。journal 是磁盘上一份可被改写的 JSON,废纸篓里的副本也可能被替换;虽然撤销前会重放 checkPathInHome,但「校验到搬回」之间仍是路径解析。

为什么仍在:这条路径面对的是本批次私有的废纸篓目录 + 我们写出的 journal, 威胁模型与「Agent 并发改写数据根」不同;fsx.RenameUnder 目前是「源在数据根、 目标目录由调用方给出」的单根形状,而撤销需要「源在 trash、目标在 home」的双根 变体,属于新原语而不是补一个参数。

闭合:给 fsx 增加双根版本(两端都从目录 fd 出发,源侧用 O_NOFOLLOW 逐层 openat,目标侧同样校验父目录),撤销时调用;配套「journal 里的 Orig 被换成 链接」「trash 副本被换链」两类测试。

rename 目标存在性检查与 renameat 之间

风险:RenameUnder 先 Fstatat 确认目标不存在,再 renameat;两步之间如果 出现同名文件,renameat 会静默覆盖。

为什么仍在:目标目录是本批次 0700 的废纸篓目录,同用户攻击者不在威胁模型 内;跨用户/跨进程写不进这个目录。窗口只在「我们自己连续两次写入同名」时才有 意义,而命名避让已经处理了那条路径。

闭合:renameat 没有「不覆盖」原语。要么用临时名 + link/unlink 的两阶段, 要么用 renameat2(RENAME_NOREPLACE)(macOS 没有)。收益有限,暂不做。

SQLite 释放量是估算

风险:Freed 是「动作前后足迹差」(主库 + -wal + -shm)的估算。采样点之间 Agent 可能同时在写库,数字可能偏大或偏小;trash 模式只挪位置,不计释放量。

为什么仍在:精确统计需要文件系统块级/配额信息,跨平台不可行;删除是低频操作, 用户需要的只是量级。

现状:deleteSQLiteSessions、trimSQLiteIndex、shared_index.go 三处已统一走 sqliteFootprint + freedFromFootprint(只报正数)。UI 文案应始终读作「约」。

agent-host.db 的按会话 metadata 键未清理

风险:agent-host.db 的 metadata 表里有 sessionsV2Excluded:copilotcli:...:/<uuid>、sessionsV2PayloadBackfilled:... 这类按会话的键。删 claude-code / copilot-cli 时只裁 session_chats / session_chat_catalogs / sessions_v2 / sessions,这些键 会留下。属残留状态,不影响会话列表,但会让「已删会话」的排除/回填标记留在库 里。

为什么仍在:这些键的格式(provider 段重复、URI 形态)没有一手文档;按前缀模糊 删可能误伤 sessionRegistryBackfilled:claude 这类全局开关。

闭合:拿到 VS Code 源码或稳定的 metadata 键规范后,按精确前缀清理,并把清理 动作并入 shared index 的 journal(可撤销)。

state.vscdb 系索引未裁

风险:vscode / cursor / windsurf / positron 等条目把 globalStorage/state.vscdb 登记为索引,但表名/键名未核实;trimIndexes 遇到 空 Table/IDCol 会跳过。删正文后,旧版 UI 的索引里可能留空条目(幽灵会话)。

为什么仍在:VS Code 系把会话存在 state.vscdb 的 ItemTable key-value 里,键名 随版本变化,猜错会整表重写。

闭合:实测各版本的 key 名后,为索引增加「key-value 形态」(不是表列)或在 scan 层识别;cursor/windsurf 的正文是否在 state.vscdb 也需要复核。

新收条目的推断表名

风险:msty / hermes / minimax-code 的会话表名没有实机 schema(调研只给到 库路径)。真机上可能只显示扫描错误、扫不到会话;不会误删(没有扫到就没有可删 的行)。

为什么仍在:缺的是实机证据,不是代码能力。

闭合:拿到实机 schema 后修正 Table/列名,并移除 Note 里的「未验证」提示。

形态不支持的格式

XML、IndexedDB 单体、加密 protobuf、聚合 markdown 等格式不在现有四种 Store 形态内(JetBrains AI Assistant、Cherry Studio/Chatbox、Void、Windsurf Cascade、 Aider 等)。逐条线索与下一步需要的证据在 docs/adding-agents.md 的「已调研但暂不能收录」一节,这里 不重复展开。

本轮闭合的相邻项(不在此节重列):删除路径 TOCTOU(fd 相对 RemoveAllUnder / RenameUnder)、删除重放 Store/Assoc 声明(含 sidecar)、journal 改为动作前 落盘、glob 增加访问条目预算、符号链接体积口径、Freed/Count 口径注释。

报告问题

安全问题请通过仓库主页列出的联系方式告知维护者。

如果问题涉及尚未修复的利用细节,请先不要开公开 issue,避免在修复前扩散。 普通的加固建议、文档纠错、威胁模型讨论可以直接开 issue。

There aren't any published security advisories