# 安全

发现安全问题，请用 GitHub 的 [Security Advisories](https://github.com/KKKKhazix/agent-autoloop/security/advisories/new) 私下告诉我，不要开公开的 issue。

私密漏洞报告入口需要仓库公开并启用该功能。入口不可用时，只在 Issue 中说明“需要私密联系维护者报告安全问题”，等维护者安排私密渠道；不要贴漏洞细节、密钥或业务资料。

私密报告请提供受影响的提交版本、运行环境、最少复现步骤和可能影响，日志与截图先脱敏。目前在最新 `main` 上验证和修复安全问题，修复随下一个 Release 到用户手上，严重的问题单独发一个小版本，没有单独维护的长期支持分支，也不承诺固定响应时间。

## 边界

- 中台默认只听本机。要对外，前面放一个做 HTTPS 的反向代理。
- 安装器和中台启动时在 macOS/Linux 把数据目录设为 `0700`，Windows 用受保护的 ACL 只保留当前账号与 SYSTEM，已有目录也会修正；数据库、事件正文和运行输出因此不向其他系统用户开放。Codex 的 Windows 沙箱会给用户目录下的文件夹加上它的账号的读权限，数据目录也在内；中台启动时收回，在那之前沙箱里的命令能读到主密钥和配置里的密钥。插件另外给每轮的 `context.json` 加这个读权限。这不隔离同一系统账号下的进程。
- 事件决定不了交给谁、在哪个目录、用哪个 Skill、给什么权限，这些只由 `rules.json` 决定。别人写的标题和正文不进提示词，只放进标明“是资料”的文件；提示词里只有校验过字符的类型、编号和链接。这挡不住所有提示注入：Agent 还是会读到别人写的话。所以默认权限是 `edit`，给 `full` 之前想清楚这个 Agent 能碰到什么。`askFirst` 是写进提示词的要求，Agent 不照做，中台也拦不住；真正挡得住的是 `access` 和 Agent 自己的沙箱。
- `access` 由专用 Agent 插件映射到 CLI 权限；`command` 不替任意程序限制权限。普通 Agent 的 `read` 不等于读不到这台电脑上的密钥。要隔离密钥，用单独的系统账号或容器。
- 普通访问密钥只存 SHA-256，另有本机 `master.key` 推导轮次和卡片链接的 token。`master.key` 为空或不完整时中台拒绝启动，不会拿它签链接，也不会自己换一把新的。接单程序不通过提示词、资料或环境变量传递中台凭据；同一系统账号下能读哪些文件仍由 Agent 沙箱决定。回执能影响的范围见 `docs/protocol.md`。
- 卡片链接谁拿到谁就能回答这一张卡片，从卡片创建起 7 天内有效，过期后也不再显示卡片内容，只发给配了 `"links": true` 的通道。
- 本项目只启动你自己安装、自己登录的官方命令行工具，不接触、不保存、不中转它们的登录凭据。
- 浏览器能力由 Agent 自己的工具配置提供；专用入口只从可信规则或 Skill 取得，不从事件正文取命令。中台不自动授予浏览器权限或接管桌面会话。需本人恢复的连接或验证用 `ask` 交回，保留未验收项。

## 插件与交付

插件是安装者信任的本地代码，安装目录的同名插件优先；`agent-autoloop add` 只克隆，不运行安装脚本，但之后加载入口就会执行它。事件不能指定插件、仓库、命令或权限。

ACP 的授权依赖 Agent 遵守协议，规范允许它不询问就执行，`access` 只管它主动来问的操作。桥接只按结构化工具种类、编辑路径与一次性选项作决定，不提供文件或终端服务。MCP 使用本机已有身份，只提供协议列出的七种操作；它不区分调用方，都按本人记录，不要配进接单程序启动的 CLI 的用户级配置，否则一轮能自己回答自己的卡片。撤销密钥立即终止其长轮询和日志订阅；轮次 token 独立。

交付只接受规则指定仓库内的分支到 main。项目设置、审查要求、替换审查命令均读 main；PR 只下载 Git 对象，生成文字差异，不检出、不运行 PR 的代码、测试、配置或 hooks；审查看不到内容的章鱼合并直接报问题，不放行。默认 Codex 禁用用户配置与记忆，只读隔离的快照。自定义审查命令由项目管理者负责提供同等权限约束。

审查成功状态只在同一提交的完整检查通过后写入；审查发现问题时写失败，同一个提交不再审第二次；合并前再次核对提交、目标分支、标签和 main，等待检查期间新增 `deliver-review` 也会阻止合并，清标签只成功一部分时重试也不会合并只审查的 PR。项目仍需在 GitHub 配好自身合并规则，插件不能代替平台权限。带 `deliver` 标签的已合并 PR 只继续核实 Ship 与健康版本，不重复合并。健康 URL 默认要求 HTTPS，只有显式测试开关允许 HTTP 127.0.0.1；跳转和不合格的版本不能证明上线。

桌面通知的正文包含 Agent 写的卡片标题，只作为参数传给 `osascript` 或 `notify-send`，放在 `--` 之后，不拼进脚本。Webhook 模板没有外部幂等保证；发送成功但报告丢失可能重复。链接回答是持有即授权，不能把链接发到公开位置。飞书应用只能保留一个卡片事件监听；本仓库测试只使用假 CLI。

## 场景资料

公开模板只包含虚构数据、示例域名和占位标识。反馈内容、网页响应与飞书资料都不能指定命令、目录、权限或收件人；反馈的现状与决定从可信业务接口重新读取。飞书汇报和表格用本人身份读取，不能换成机器人身份补齐看不到的数据。摘要输入保存在本人私有目录，完整读取后才替换，通知不携带敏感正文。

通道接收人属于整个中台，规则不能单独挑收件人。处理私人反馈和汇报的中台应只连接本人可见的通道；不要把它们接到共享群。新增接入沿用用户自己的身份与授权，不复制内部部署配置、密钥或业务日志。

浏览器交接模板的命令数组、目标网址和允许操作来自本人的可信配置，按参数传递，不把任务文字交给 shell 解释。允许操作是给 Agent 的任务范围，不是额外的系统沙箱；实际工具和账号权限仍由既有运行环境决定。会话编号只用入口实际返回的值；中断或结果不明先核实，不盲目重复有副作用的网页操作。模板不修改应用内部状态、不自动启动新的账号授权，也不打包某台电脑的浏览器修复脚本。

## 日志与恢复

门的权限、通道回答人和原消息、轮次 token 的范围、重复回执与卡片回答都有行为和一致性检查。`sim/invariants.ts` 是模拟与穷举共用的不变量；夜间检查另外对真实 SQLite 进程做 SIGKILL。范围是进程崩溃和有限场景，不等同于断电恢复证明或完整安全审计。

`kernel/` 不读时钟、不取随机数。判断、事实追加和 `evolve` 更新投影在同一 WAL + FULL 事务里完成，提交后才应答。正常启动复用带游标和编号高水位的投影；格式指纹变化时从日志逐条重建，不改变旧事实。`agent-autoloop why 42` 查一轮的事件、规则和回执；`GET /v1/stream?after=42` 供本人客户端按序号续读。备份用 `agent-autoloop backup [目录]`，中台运行时也能做；恢复用 `agent-autoloop restore <目录>`，要先停中台。规则写了 `resume` 时，一轮读到的资料会留在会话里，后面的轮次还看得到，事件里别人写的字也在其中；没写 `parallel` 时，这条规则的所有事件共用一个会话。来源不可信的规则不要这样配。

备份里有主密钥、配置里的密钥和 `secrets.env`，macOS/Linux 上目录权限 0700、文件 0600，Windows 上继承只允许本人和 SYSTEM 的目录 ACL，要和密钥一样保管。恢复时这些文件和规则都会被替换。手工备份要一起保留 `hub.db` 和受相同访问限制的 `master.key`；后者推导轮次和卡片链接的 token。普通访问密钥只保存哈希；卡片链接查找索引也只保存 token 的哈希。