密钥安全RESOURCE / preventing-agent-secret-leakage
防止 Agent 密钥泄漏
从凭据分类、Connection 边界和变更评审出发，建立可检查的 Agent 密钥治理方式。
Agent 第一次出现时，可以把它理解为会执行任务的 AI 工作助手或智能代理。密钥风险通常不是从“模型把密钥说出来”才开始，而是在更早的交付环节发生：样例工程被复制到新项目、环境变量文件在群里流转、管理员凭据被临时借用、客户环境交接时没有写清撤销负责人。
密钥泄漏往往发生在交付复制时
中国软件团队常见的现实是，一个平台组同时支持内部业务和多个 ToB 项目。为了提高交付速度，脚手架、部署说明和环境模板会被反复复用。如果模板里混入真实 Provider 凭据，或者项目把管理员凭据当成普通调用 key，风险会随着复制扩大。
所以，安全评审不能只问“密钥有没有放进密钥管理系统”，还要问“这份密钥为什么存在、由谁使用、跟哪个资源绑定、项目结束后谁负责替换”。
密钥放在哪里，只回答了存储问题；密钥为什么能被这个 Agent 使用，才是治理问题。
按使用目的分层，不按文件位置分层
同一个 .env 文件里可能同时出现多类凭据，但它们不应因此被视为同一安全等级。
- Gateway API key：面向 Agent 请求入口，用于进入指定的 Service Endpoint 边界。
- 管理员凭据：用于管理 Control Plane，不应进入 Agent 运行配置。
- Provider 凭据：属于具体 Connection，用于到达对应模型服务，不应直接交给 Agent。
这种分类适用于境内或国际模型服务的治理讨论，但不代表 Stravia Console 已验证广泛 Provider 支持。重点是让每个凭据角色有明确用途，而不是对服务覆盖范围作推断。
把 Connection 当成交付隔离单元
Provider 表示可管理的模型服务资源，Connection 表示由该 Provider 拥有的具体配置实例。对交付团队来说，Connection 应当是需要单独确认的项目边界：端点、凭据、所有者和替换流程都要随项目环境重新核对。
这意味着“复用交付方案”可以复用字段和评审流程，但不能默认复用真实 Connection。内部环境、客户环境、不同部署区域或不同模型服务安排，都应保留独立判断。
做一张能交接的密钥责任单
下面是一份适合方案评审或交付交接的工作表，不是产品自动生成的审计报告：
| 交接项 | 必须填写的内容 | 需要停下来复核的情况 |
|---|---|---|
| Agent 入口 | Service Endpoint、Gateway API key 负责人 | 使用管理员凭据代替入口 key |
| 管理权限 | 管理员、使用场景、撤销联系人 | 凭据进入 Agent 配置或共享模板 |
| 模型服务配置 | Provider、Connection、凭据所有者 | Agent 直接持有 Provider 凭据 |
| 项目退出 | 替换或撤销责任人 | 项目结束后无人确认凭据状态 |
责任单的价值不在于承诺“不会泄漏”，而在于让后来接手的人知道从哪里撤销、替换和复核。
在变更评审里设置停线条件
以下变化不应被当作普通配置修改：
- 新增一种凭据角色。
- 把 Provider 凭据移动到 Agent 可直接读取的位置。
- 让多个项目共享同一个 Connection，却没有共同所有者。
- 调整管理员访问范围，但没有单独评审。
- 无法说明变更后可以检查哪些请求证据。
遇到这些情况，团队需要的是一次明确的安全决定，而不是在通用提示词、共享脚本或部署文档里悄悄完成变更。
当前证据能说明什么，不能说明什么
Stravia Console 当前 0.1.0-alpha 预发布产品基础提供了 Service Endpoint、Provider、Connection、确定性路由、凭据边界和请求检查等可核验概念，当前执行范围为 OpenAI-compatible、非流式文本。固定 Demo 证据不是客户数据，也不能证明生产安全结果。
这些证据有助于评审凭据是否分层、Connection 是否被命名、请求路径是否明确。它们不能被解读为隐私扫描、自动密钥发现、完整审计报告、合规认证、生产就绪或 SLA。公开 Early Access 当前仍是 Coming Soon。
一个可执行的默认原则是：Agent 只获得完成入口调用所需的有边界凭据；管理员权限留在 Agent 运行环境之外；Provider 凭据留在有所有者的 Connection 中；每个例外都写明撤销路径。