a4agent 的核心工作对象是 API Key 与完整的模型对话流量,任何界面与功能的改动都不能削弱安全性。项目把「安全可靠」作为立身之本,从密钥存储、网络边界、配置写入、进程管控到日志隐私做了成体系的防护。本文章汇总全部安全机制的设计意图与实现位置,作为安全审计与使用信任的索引。
1. 防护全景
接口永不回显] C --> G[代理仅监听本机
随机 token 鉴权
CORS 白名单] D --> H[自动备份
原子写入
合并式更新] E --> I[清单签名验签
SHA256 校验
传输白名单] J --> K[一次确认配对
私网限定
TOFU 指纹] style A fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B fill:#fadbd8,stroke:#c0392b,stroke-width:2px style C fill:#fadbd8,stroke:#c0392b,stroke-width:2px style D fill:#fadbd8,stroke:#c0392b,stroke-width:2px style E fill:#fadbd8,stroke:#c0392b,stroke-width:2px style J fill:#fadbd8,stroke:#c0392b,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style H fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style I fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style K fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
2. API Key 加密存储
- 所有 API Key 在入库前经 Windows DPAPI 加密——直接调用
crypt32.dll的CryptProtectData,无第三方依赖;密文以 base64 存入 SQLite,与当前 Windows 用户绑定,换用户或换机器后无法解密。 - 任何后端接口的响应都不包含 Key 明文或密文:序列化模型不暴露密钥字段,前端永远只显示「已设置」状态。
- 密钥仅在两个时机被解密使用:执行切换写入目标配置文件时、本地翻译代理按生效配置更新上游时。
- 解密失败时返回空字符串并记录错误日志,不静默产出脏数据。
- 非 Windows 环境仅做 base64 编码兜底,不具备安全性,仅供开发调试使用。
3. 本地翻译代理的边界
为 OpenAI 兼容服务商运行的本地翻译代理遵循最小暴露原则:
| 防护 | 取值 |
|---|---|
| 监听地址 | 仅 127.0.0.1,不对局域网或外网开放 |
| 端口范围 | 17890 - 17899 固定小段 |
| 鉴权 | 每次启动以加密随机数生成 token,请求必须携带且匹配,否则 401 |
| 密钥持有 | 从数据库按生效配置解密获得,进程内使用,不硬编码、不落盘明文 |
| 运行条件 | 仅当前生效配置需要代理时存活,否则数秒内自动退出;0.6.3 起拉起后始终等不到生效配置的孤儿代理最多宽限 120 秒自动退出,不留看不见的进程 |
复用已运行代理前还会做能力握手校验,避免误用旧版本遗留的未鉴权进程。机制细节见本地翻译代理。
4. 配置写入完整性
用户最怕「切一次配置毁一套环境」,a4agent 用三层机制保证写坏不可能发生:
| 层次 | 机制 |
|---|---|
| 事前 | 修改前自动备份原文件到数据目录,各类文件独立滚动保留最近 5 份 |
| 事中 | 合并式生成:只覆盖工具托管的字段,hooks、permissions、MCP 配置等原样保留 |
| 写入 | 原子替换:临时文件加 fsync 加操作系统级 replace,断电也不产生半截文件 |
配合切换前置的兼容性校验(目标与服务商协议不符时零写入返回),任何失败路径都不会留下半生效状态,详见配置方案与一键切换。
MCP 管理同样遵循备份与原子写约束,并额外收紧回收站安全:被替换 / 删除的 server 配置片段快照进回收站时,其中的 env / headers 用 DPAPI 加密落盘,恢复时才解密写回;0.6.3 起恢复时若解密失败会立即中止并报错,不再静默清空凭证(避免把坏数据写回原配置文件);发现、预览与回收站接口对敏感字段全程脱敏。机制细节见MCP管理。
5. 后端接口防护
桌面形态下 FastAPI 只服务本机,但仍做了纵深防御:
- CORS 白名单仅放行
localhost、127.0.0.1与[::1],恶意网站无法跨域读取或篡改本地配置。 - 请求体强校验:Pydantic 模型约束字段类型与枚举(如协议类型仅允许 anthropic 或 openai),非法输入直接拒绝。
- 静态资源统一托管:前端由后端进程自己提供,不存在独立对外的静态服务器。
5.1 会话 hook 的写入边界
「通知提醒」为各端挂载会话 hook 时会写入宿主配置文件(Claude Code / Qoder / WorkBuddy 的 settings.json、Codex 的 config.toml 标记块、ZCode 的 hooks.events),约束与配置切换一致:
- 只写自己的条目:归属判定用「命令含 a4agent 且含 hook」的正则,卸载时只摘这些条目,不会误删用户自己的 a4phone(a4p)或其它 hook 命令;
- dsh 与 OpenCode 不写宿主文件:dsh 走进程内加载的内置 Cordis 插件(只改 profile 的 patch 层,不碰 dsh 自身配置语义),OpenCode 没有 hook 协议,注册只是开启 a4agent 侧的服务事件监听——两者的「注册」都不往宿主配置里落任何东西;
- 合并式写入 + 备份 + 原子替换:与配置切换共用同一套
config_io公共层,不覆盖用户原有的 hooks 内容。
5.2 手机推送的话题即凭据
手机推送走 ntfy:话题名即凭据,知晓话题即可向你的手机推送。因此话题随机生成(a4ag- 前缀)、可一键重置换名,页面只在本机展示二维码与订阅地址。
| 风险 | 处理 |
|---|---|
| 话题泄露后被无关方推送 | 一键重置话题名并重新订阅 |
| 公共服务上的内容可见性 | 默认走公共 ntfy 服务器;数据敏感时在页面改为自建 ntfy 并填写访问令牌 |
| 访问令牌存储 | 明文存于数据目录 phone_config.json(目录本身已收 ACL 权限),不入库、不随日志外泄 |
推送内容只含「话题名称 / 通知类型 / 应用名称」三行与 AI 最后一段输出(最多 1000 字),不含密钥。
5.3 无头任务的产出与进程
- 产出是引擎原始输出,可能包含代码、路径等敏感内容:落盘在
%APPDATA%\a4agent\task_outputs\,与其它运行数据同级、仅本机用户可访问; - 应用内「问题反馈」不会自动附带任务产出,删除任务会同步删除其产出文件;
- 取消与超时用
taskkill /T /F杀整棵进程树(Node 壳会派生子进程),不留失控子进程;0.6.3 起任务取消后还会复查补杀(RUNNING 落库后再查一次),防止「取消后复活」;应用退出时先登记原因再杀进程,让任务如实标记为「应用退出」而不是留下僵尸行。
5.4 设备互联的信任边界
设备互联(0.7.0 起)把控制面伸到了局域网里,信任的建立被刻意设计成「看得见 ≠ 可控制」:
- 广播只用于发现:UDP 广播让同网段设备互相看见,但不自动建立信任,也不提供同网段静默互信——每台新设备都需要被控端本地一次确认(确认窗显示来源 IP、可拒绝),拒绝则连接不建立;
- 配对码一次性:6 位配对码配合 5 分钟倒计时,猜错达上限(默认 5 次)即作废本次会话,发起端受 10 秒限频保护;配对成功 / 失败 / 拒绝全程落被控端审计;
- 网络位置限定:非私有网段来源一律拒绝,设备互联只在局域网内成立;未配对设备对被控端的任何请求一律 401;
- TOFU 指纹校验:首次配对时记录对方 TLS 证书指纹,此后指纹变更一律拒绝(防中间人),正当场景(如对方重装系统)需在设备页人工重置指纹后重新配对;
- 凭据最小暴露:控制端侧的设备令牌与证书指纹经 DPAPI 加密落盘(见第 2 节同款机制),只在内存解密使用,任何接口与日志都不回传明文;Agent 开放交互的
/overview端点返回设备全景与接口速查,令牌与指纹不出 backend;配对 toast 也不含配对码 / IP / 令牌; - 文件访问沙箱:远程文件上传受白名单约束,越界写入报错只携带允许根列表;
install-skill安装内置技能同名不覆盖,配对确认永远是设备页的人工动作,AI 不能替用户信任新设备。
机制细节见设备互联。
6. 数据目录与文件权限
- 打包运行时数据(数据库、备份)写入
%APPDATA%\a4agent\,位于当前用户目录内,不写程序目录,规避多版本冲突与权限问题。 .gitignore排除数据库与运行时数据,密钥密文不会随仓库泄露。- 非 Windows 环境对数据目录与数据库文件执行
700/600权限收紧(尽力而为的加固,Windows 上由 NTFS ACL 控制)。
7. 并发与数据一致性
- 配置激活使用进程内互斥锁串行化,并发点击多张卡片也不会把两个方案同时标为生效。
- 异常路径事务回滚,数据库不留半写入状态。
- SQLite 连接统一开启外键约束(
PRAGMA foreign_keys=ON);删除服务商前校验其下配置方案数量,有引用则拒绝删除,杜绝孤儿数据。
8. 进程管控
- 以 Windows 命名互斥体保证桌面应用单实例运行,防止多实例互相覆盖配置;二次启动会通过
/api/v1/desktop/wake唤回已有窗口,而不是新起一个进程。0.6.4 起升级为启动自恢复三段式:先唤回隐藏窗口,唤不到就清障重启(重建实例记录),兜底仍失败才提示到任务管理器结束进程。 - 重启 Claude Code 前用 CIM 精确匹配命令行包含 claude 的进程再结束,避免误杀无关进程。
- 关窗不等于退出:关闭主窗口转为后台常驻(0.6.4 起托盘图标常驻),任务继续执行;真正的退出入口是顶栏「退出」或托盘右键「退出」,会先告知还有几个任务在跑并二次确认,退出时先收托盘再终止进程树——这条设计同时避免了「以为退出了其实还在跑」的失控感。
9. 日志与隐私
- 默认日志不记录任何请求或响应内容,只有时间、级别与摘要,写入
~/.a4agent/logs/。 - 含完整请求头、请求体与上游响应的调试日志默认关闭,仅在显式设置环境变量
A4AGENT_PROXY_DEBUG时开启,排障后应关闭。 - 应用内反馈仅本地留档(自 0.3.2 起):反馈内容与截图先存入本地数据库,再尽力直邮开发者邮箱;SMTP 凭据存本地私有文件(不入库、不入仓库),未配置邮件时反馈仅入库留档不上传;接口响应中的环境信息只含版本 / 系统 / 运行模式,不含密钥与对话内容。
10. 更新链路防篡改
自动更新是远程攻击面,a4agent 用「签名清单 + 内容哈希 + 传输白名单」三重校验保证装进来的安装包就是作者发布的那个:Ed25519 签名的更新清单、边下边算的 SHA256 比对、逐跳 HTTPS 主机白名单,外加严格防降级。0.6.3 起应用侧再加两道约束:安装包路径必须位于数据目录 updates\ 之内(防状态文件被改写成任意程序执行);离线且缺少已持久化校验值时拒绝应用安装包。完整机制见自动更新。
11. 测试保障
关键安全行为都有自动化回归测试守护:
| 测试文件 | 覆盖内容 |
|---|---|
test_crypto.py |
DPAPI 加解密往返、非法密文返回空 |
test_config_manager.py |
两端配置生成与合并、原子写入不留临时残留 |
test_skill_manager.py |
九端 skill 发现与迁移、回收站恢复与过期清理、越界路径防护 |
test_mcp_manager.py |
九端 MCP 发现/聚合、传输能力矩阵校验、回收站加密快照与恢复、迁移日志 |
test_openai_proxy.py |
Anthropic 与 Responses 协议翻译正确性、工具 schema 处理、null 归一回归 |
test_updater.py |
签名载荷基准、验签与篡改拒绝、版本比较与降级、SHA256 与尺寸校验、URL 白名单等 |
test_database.py |
数据目录迁移(a4api → a4agent 整目录迁入 / 逐项拷贝退化)与旧 a4api_p* 托管前缀清理回归(0.4.0 起) |
test_switch.py 等 |
切换流程、预置播种、配置接口的行为约束 |
test_removal.py |
0.5.1 移交三端的托管配置清理:只删自写条目、永久快照、用户自有配置不被动(17 项,含反向用例) |
test_task_*.py |
引擎矩阵与坏壳识别、预检四类连通分支、真实子进程跑状态机、超时杀树与退出竞态 |
test_devices_*.py / test_pair_watcher.py / test_node_proc_multi.py |
设备互联:配对码与限频、DPAPI 凭据存取、发现池与回环帧过滤、node 守护与多实例、TOFU 指纹(0.7.0 起) |
test_proxy_standalone.py |
代理端口属主 pid 一致性校验(孤儿进程占端口导致 token 失效的回归) |
评论