这份文档说明 AgentSweep 信任什么、不信任什么,以及每条边界的依据。 它不是「安全承诺清单」:写在这里的每一条都能在代码里找到对应实现, 反过来,代码里做不到的事情这里也不会写得更好听。
适用范围是 AgentSweep 自身:自更新、删除/撤销、本机 HTTP 接口。 不在范围内的是它读取的第三方 Agent 数据格式,以及 macOS 本身。
- HTTPS 请求
api.github.com的/releases/latest,拿到发布 JSON; - 按资产名挑 zip,校验下载地址的 host 白名单(含每一跳重定向);
- 下载 zip 到用户缓存目录;
- 取同一个发布里的
checksums.txt,核对 zip 的 SHA-256; - 解压(单根
.app、拒绝越界路径与可疑符号链接、限制条目数与解压体积); - 核对包内
Info.plist版本等于发布 tag、且高于当前版本;lipo确认架构匹配; - 复制到旁边、校验、两次 rename 换位,删除旧包;
- 去掉
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,加上「清单与包出自同一次发布」 这条自洽性约束。仓库或账号失守时,更新器会把攻击者的包当成正常更新装上去, 并以当前用户权限运行。
产物用 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+ SQLiteVACUUM,只有真正收缩掉的空间才计入。
「移入废纸篓」和「真实释放」在 UI 上始终分开显示。把前者算成后者,是在向用户 谎报战果。
索引和 SQLite 库一旦被改,原始内容就只存在于备份里。所以每个对象都是 「先备份,再改」:数据库在删行前整库复制一份,索引在裁剪前整文件备份一份, 备份失败就跳过这一项并记一条错误——而不是先改后补。
备份放在 ~/Library/Application Support/AgentSweep/backups/<batchID>/,目录 0700。
这也解释了为什么 permanent 模式并不等于「什么都没有」:数据库型会话仍有一份
删行前的整库副本,撤销时整份覆盖回去;只有文件型正文是真的没了。
任何破坏性动作之前,先写一份空 journal;之后每成功移走/删除一个路径就原子重写一次。
- 原子写是「临时文件 → fsync → rename → 目录 fsync」,掉电后不会出现 「删了但没有账本」;
- journal 与备份目录都是
0700,journal 文件0600:里面是会话 ID 和绝对路径, 属于用户隐私; - 写不进去就立刻停手并返回错误。继续删只会扩大「无法撤销」的范围;
- 进程中途被 kill 时,磁盘上至少有一份能说明「已经动了哪些路径」的账本。
journal 是磁盘上一份可以被改写的 JSON(当前用户的权限、未来的导入接口都可能 改它)。所以撤销不把里面的路径当成可信输入:
- 撤销时用 journal 里记下的数据根
Home,对每一条待恢复路径重新跑一遍checkPathInHome,位置在任何文件系统探测之前; - 旧版本写的 journal 没有
Home字段,直接拒绝恢复(fail-closed),并提示按moved记录手工处理。缺字段不等于「无需校验」; - 单条被拒只记错误,不影响其它条目;
- 只有整批没有任何错误才标记
undone;部分失败保持可重试,已恢复的条目在重试时 会被安全跳过。
另外,permanent 且没有任何 SQLite 备份的批次拒绝撤销:正文已经永久删除,
把索引覆盖回去只会得到点进去是空的幽灵会话,比不撤销更糟。
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 口径已经在本轮闭合或写进代码注释,不再作为风险 列出(见本节末尾一句小结)。
风险:Undo 仍用 movePath 按路径把正文从废纸篓搬回 journal.Orig。journal
是磁盘上一份可被改写的 JSON,废纸篓里的副本也可能被替换;虽然撤销前会重放
checkPathInHome,但「校验到搬回」之间仍是路径解析。
为什么仍在:这条路径面对的是本批次私有的废纸篓目录 + 我们写出的 journal,
威胁模型与「Agent 并发改写数据根」不同;fsx.RenameUnder 目前是「源在数据根、
目标目录由调用方给出」的单根形状,而撤销需要「源在 trash、目标在 home」的双根
变体,属于新原语而不是补一个参数。
闭合:给 fsx 增加双根版本(两端都从目录 fd 出发,源侧用 O_NOFOLLOW 逐层
openat,目标侧同样校验父目录),撤销时调用;配套「journal 里的 Orig 被换成
链接」「trash 副本被换链」两类测试。
风险:RenameUnder 先 Fstatat 确认目标不存在,再 renameat;两步之间如果
出现同名文件,renameat 会静默覆盖。
为什么仍在:目标目录是本批次 0700 的废纸篓目录,同用户攻击者不在威胁模型
内;跨用户/跨进程写不进这个目录。窗口只在「我们自己连续两次写入同名」时才有
意义,而命名避让已经处理了那条路径。
闭合:renameat 没有「不覆盖」原语。要么用临时名 + link/unlink 的两阶段,
要么用 renameat2(RENAME_NOREPLACE)(macOS 没有)。收益有限,暂不做。
风险:Freed 是「动作前后足迹差」(主库 + -wal + -shm)的估算。采样点之间
Agent 可能同时在写库,数字可能偏大或偏小;trash 模式只挪位置,不计释放量。
为什么仍在:精确统计需要文件系统块级/配额信息,跨平台不可行;删除是低频操作, 用户需要的只是量级。
现状:deleteSQLiteSessions、trimSQLiteIndex、shared_index.go 三处已统一走
sqliteFootprint + freedFromFootprint(只报正数)。UI 文案应始终读作「约」。
风险: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(可撤销)。
风险: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。