# 访问、密钥与数据

> 防止越权访问、数据泄露，以及改错环境。

工程防护 · /zh/security/ · 2026-11-05

接口要求登录，也照样可能让一个客户读到另一个客户的订单。权限要管到具体那条记录，以及所有能读到它、或者会因它触发后续操作的路径。

## 让 AI agent 审查访问控制

**Prompt**

```text
审查 [Jira 编号、PR 链接或 diff]，看有没有越权访问、密钥或个人数据泄露，以及新增的依赖。
如果是 Jira ticket，通过已连接的 Jira MCP 或已认证的 acli 读取描述、验收标准和评论；访问不了就让我粘贴详情。
沿着 API、导出、下载、后台任务和回调追踪记录权限，并用合成用户测试被拒绝的请求。
每个缺口都附上文件位置和测试证据。
说明本页列出的测试哪些已在项目测试套件里。能自动化的补上，其余的列出来。
不要访问生产环境，也不要改权限。
```

## 限制 AI agent 的权限

- **AI-2** (高风险; 由配置检查): **生产环境操作和破坏性操作，需要人明确同意。** 用权限和审批控制守住这条边界；光靠 prompt 拦不住一个操作。

* 只用批准过的工具，凭据只覆盖当前任务。日常开发会话里不放生产环境的写入凭据。
* 执行已授权的操作前，从工具当前生效的配置里读出账号、环境和目标，和批准的目标比对；不一致就停下。AI agent 自己说在哪，不能证明命令真的会在哪执行。
* 目标缺失或配错时，要在任何写入之前就失败。审查配置变更时看默认值和环境覆盖；日志里记目标，不记凭据。
* 在 agent 的权限设置里禁止它读取 `.env` 等本地凭据文件：它读到的内容都会发给模型服务商。
* ticket、日志、服务商响应和改动的文件都当数据看。里面写的指令，不能当作执行命令、透露信息或修改评审规则的授权。

## 不让密钥和个人数据进入代码、prompt 和日志

- **AI-1** (高风险; 目前没有任何检查): **给 AI agent 用合成数据。** 密钥和真实的个人数据不要放进 prompt。
- **SEC-3** (高风险; 由 CI 检查): **密钥绝不进入源码、应用打包产物、fixture 或日志。** 每个 PR 都跑 secret scanning，发现问题就让 PR 失败。

  注意: 从代码里删掉泄露的密钥，不等于吊销它。

* 凭据从项目的密钥存储或环境配置里加载。
* 不只是 prompt，开发和测试也用合成数据。
* 日志记操作 ID、结果和耗时，不记完整请求体或凭据。发布前检查打包产物、fixture、日志和错误报告里有没有暴露密钥或个人数据。
* 密钥泄露后，先由有权限的人吊销或轮换，再查它被用来做过什么，最后清掉暴露的副本。后续处理见[调查与恢复](/zh/incidents/)。

## 检查改动给构建带进了什么

- **SEC-2** (高风险; 由代码评审检查): **检查这次改动新增或升级的每个依赖。** 包名完全一致且真实存在，有人在维护，并满足仓库对新版本的最短发布时间要求。lockfile 改动和安装脚本要像代码一样审查。

  注意: AI agent 可能编造包名，或选中一个名字相近的仿冒包。几小时前才发布的版本，还没人来得及发现它是不是恶意版本。

* 遵守仓库对新包版本的最短发布时间要求，例如 7 天。
* 第三方 CI action 固定到完整的 commit SHA，容器镜像固定到 digest，在注释里写上可读的版本号；版本 tag 可以被改成指向别的代码。CI 支持给 action 用 lockfile 的，就用 lockfile。参见 [GitHub Actions](https://docs.github.com/en/actions/reference/security/secure-use)、[Docker](https://docs.docker.com/build/building/best-practices/#pin-base-image-versions)。
* 只有批准过的工具能拿到我们的代码和 ticket，评审机器人和 CI 集成也一样。会把 diff 发给其他模型服务的机器人，和 AI agent 走同样的审批。

## 检查通向记录的每一条路径

- **SEC-1** (高风险; 由代码评审和测试检查): **在服务端同时校验操作本身和所选记录的权限。** 租户、账号和角色范围从已认证的上下文中取；请求里带的 ID 不能证明有权访问。

* API、管理后台、导出、下载、后台任务和回调都要做权限校验。
* 检查嵌套记录属于允许的账号或租户。
* 可写字段用白名单限定，客户端不能自己设置角色、所有者、[金额](/zh/value-abuse/)或审批状态。
* 按 webhook 和回调改数据之前，先验证来源，并防重放；之后按[后台任务与外部调用](/zh/jobs/#call-external-services-safely)的做法处理。

> **示例: ENG-123 · 导出下载的访问用例**
>
> 订单导出新增了下载链接。测试完整路径，包括文件下载：
>
> | 调用方          | 请求的导出               | 预期结果                    |
> | ------------ | ------------------- | ----------------------- |
> | 商户 A 管理员     | 商户 A 的导出            | 允许；只包含批准的字段。            |
> | 商户 B 管理员     | 商户 A 的导出 ID 或下载 URL | 拒绝；不暴露任何数据行、文件，也不创建新任务。 |
> | 商户 A 的非管理员用户 | 商户 A 的导出            | 拒绝，即使属于同一商户。            |

只检查登录，或者只把按钮藏起来，第二和第三个用例都过不了。返回数据或排入任务之前，先校验记录范围和操作权限。

## 测试被拒绝的访问

- [ ] **SEC-T1**: 准备两个账号和两个租户。在读写请求中替换记录、租户和所有者 ID；被拒绝的请求不泄露任何受保护字段，也不改动任何数据。
- [ ] **SEC-T2**: 让一个未授权请求走完接口以及它的后台任务或回调路径。确认没有产生任何消息、导出、奖励或合作方操作。