# AI 编程代理凭据清单模板

AI 编程代理不应该拿到一堆继承来的凭据，再收到一句模糊的“小心使用”。在代理调用 API、部署服务或建立 SSH 连接之前，团队需要先记录清楚：凭据能访问什么，谁对此负责，以及团队如何关闭它。

凭据清单模板听起来像行政工作，直到代理在操作者离开键盘时连续发出二十次调用。那时，它可能决定你只需撤销一个已知能力，还是不得不禁用整个工程组织，因为没人说得清这个令牌是什么。我见过团队直到自动变更落到不该到达的地方，才发现他们的“staging”自动化竟然持有生产环境写入令牌。

## 清单记录的应该是权限，而不是秘密字符串

凭据清单记录的是权限。它不记录 API 令牌、SSH 私钥材料、密码、恢复代码，也不记录这些内容的加密导出。如果清单本身可以登录任何系统，它就变成了另一个访问控制更弱、受众更大的秘密存储处。

这个区别很重要，因为团队经常把标识符和凭据混为一谈。API 令牌的末四位可以帮助操作者在轮换时找到正确条目，却不能说明它是否可以删除项目。SSH 公钥指纹可以标识一个身份，却不能说明它登录的是哪个 Unix 账户，是否允许端口转发，或哪些主机信任它。

每一项可以独立撤销的权限都应单独占一行。同一个服务商账户可能需要多行：生产环境只读报表令牌、staging 部署令牌、代理不能使用的紧急管理员令牌，以及 webhook 签名密钥。把它们合并到一行，会掩盖不同的风险和轮换要求。

SSH 也遵循同样的规则。不要因为同一个私钥碰巧能访问 Git 和服务器，就在一个单元格里写“Git 和服务器”。源代码控制写入身份和主机登录身份的后果不同。即使它们由同一个人在同一个下午创建，也应该分别记录。

NIST SP 800-57 第 1 部分把加密密钥管理视为一个生命周期问题：生成、分发、存储、使用、替换和销毁都需要受到控制。该文件重点讨论加密密钥，但它的管理原则同样适用于这里。只记录“我们创建了一个令牌”的列表不算清单，只是一份记忆辅助，而恰恰在员工需要可靠记录时，它最容易失效。

## 为每份凭据指定一名明确负责人

每一行都需要一名明确的负责人，他能回答“这项权限是否还应该存在？”负责人不必运行秘密管理器，也不必编写代理集成，但必须足够了解相关系统，能够批准访问并承担运行后果。

不要使用“平台”“开发团队”“共享”或已离职员工姓名作为负责人。团队可以执行流程，但团队名称无法告诉事故响应人员凌晨两点该联系谁。记录一名主要负责人，必要时再记录一名有权撤销或替换凭据的备用负责人。

把团队经常混淆的四种角色分开记录：

- 系统负责人决定访问是否仍然合适。
- 凭据保管人可以创建、存储、撤销和轮换凭据。
- 代理操作者启动或监督代理运行。
- 事故联系人在前三类人员都无法联系时处理紧急故障。

小团队中，一个人可能承担多个角色，但清单仍应分别列出这些角色。令牌在发布期间失效时，保管人可以修复存储问题，而系统负责人决定临时替代凭据是否应拥有相同权限。

对于服务商 API，负责人通常应是负责支付或运营该账户的团队，而不是第一个把令牌粘贴进本地配置文件的开发者。对于 SSH 访问，负责人通常是主机或应用负责人，而不是生成密钥对的人。听起来很明显，但失去负责人的凭据通常都始于一个合理的捷径，后来那个人换了团队。

添加一个独立于秘密轮换日期的审核日期。令牌在技术上仍然有效，并不代表它的业务用途还存在。审核要回答的是访问是否还应该存在，轮换则是替换可能已经老化或泄露的材料。完成其中一件，并不等于完成另一件。

## 用动词和目标写明允许的操作

“生产环境访问”不是权限描述，而是一个警示标签，对代理操作者没有实际帮助。清单需要包含动词、目标资源和审核者可以检查的边界。

可以按以下形式写权限：

`动词 + 目标 + 边界 + 禁止的操作`

例如：

- `在 staging 中 GET /v1/projects/acme/builds，不允许请求生产租户`
- `为 catalog-api 服务 POST 部署版本，不允许回滚或删除`
- `以 deploy 身份 SSH 登录构建主机组，只能运行批准的发布命令，不允许交互式 shell`
- `在 alpha 仓库中创建问题评论，不允许合并、删除分支或修改设置`

这比服务商笼统的“写入”标签有用得多。能够创建部署版本的代理和能够删除部署的代理都拥有写权限，但影响范围完全不同。

记录预期操作属于读取、创建、修改、删除、执行还是管理变更。“执行”需要特别谨慎。启动云任务、轮换服务凭据、触发支付操作或运行远程 shell 的 API 调用，在请求日志中可能看起来无害，却可能在下游造成昂贵或不可逆的结果。

不要把清单写成充满模糊措辞的法律文件。“仅在适当时使用”和“日常部署工作”都没有边界。人无法据此批准，工程师也无法据此构建控制措施。如果操作取决于上下文，就明确写出上下文：指定的环境、仓库、主机组、账户或变更类型。

常见的捷径是授予一个通用管理员令牌，再依靠代理提示词避免危险调用。它之所以流行，是因为几分钟就能让原型运行起来。但这是错误的，因为提示词不是访问控制，后续工具调用可能继承广泛权限，而写提示词的人甚至没有察觉。

## 环境需要分别记录，也需要分别评估后果

staging 凭据和生产凭据不应该仅仅因为调用同一个 API 就放在同一行。它们的负责人可能相同，但目标账户、数据暴露、审批要求和撤销紧迫性往往不同。

不要只把环境当作一个标签。记录服务商账户或租户、端点或主机组、数据分类，以及调用是否可以跨越环境边界。当组织拥有多个生产账户、区域或客户分区时，“Prod”过于模糊。

一个可用的环境字段可以这样写：

`production / 租户 4821 / 客户账户数据 / 端点 api.example.internal`

如果内部主机名本身敏感，不要把真实主机名放进所有人都能读取的清单。重点是让有权限的团队能够精确识别目标。清单的访问策略应与其中运行细节的敏感程度相匹配。

单独增加一个字段，记录代理可以在响应中接收的数据。调用端点的权限和查看响应内容的权限相关，但风险并不相同。一个读取请求可能返回源代码、客户联系方式、发票、访问元数据，或旧配置值中嵌入的秘密。

这能发现一种常见的失败模式。团队为 staging 创建了一个“只读诊断”代理凭据。后来事故处理中，工程师把诊断客户端指向生产环境，因为两边的命令语法完全相同。服务商使用账户级范围，所以凭据成功了，代理还把客户数据返回到了自己的记录中。如果原始清单记录了租户和响应数据，而不是简单写“诊断读取”，就会暴露这个缺失的边界。

如果服务商无法隔离环境，不要用自我安慰式的文档来弥补。标记凭据会跨环境使用，提高审批级别，并决定代理是否应该使用它。诚实的答案有时就是“不应该”。

## SSH 访问需要比 API 访问记录更多细节

SSH 凭据需要单独的字段，因为一次 SSH 连接可能同时携带多种权限。登录账户、允许的主机、命令限制、转发权限和代理转发设置，都会改变连接能做什么。

每一行 SSH 记录应包含公钥指纹、私钥材料位置、登录账户、主机或主机组，以及准确的预期命令。不要把私钥复制进清单。SHA256 指纹足以用于识别，操作者可以在本地生成它。

对公钥文件运行以下命令：

```text
ssh-keygen -lf ~/.ssh/id_agent_deploy.pub
```

正常结果大致如下：

```text
256 SHA256:AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd agent-deploy (ED25519)
```

保存 `SHA256:` 值。只有在注释有助于人类识别角色时，才保存注释。注释不是安全控制措施，任何人在复制公钥时都可以修改它。

对于目标主机，应检查 `authorized_keys` 中的限制，不要因为大家认为部署账户受限，就假定它真的受限。OpenSSH 在 `sshd` 手册中记录了 `command=`、`no-port-forwarding`、`no-agent-forwarding` 和 `no-pty` 等选项。这些限制可以把自动化身份变成只能运行受限命令的执行器，但它们无法修复一个以不受限管理员账户登录的凭据。

一条记录可以写成：“以 `deploy` 登录，目标为发布组 A 中的主机，强制命令为 `/usr/local/bin/release-catalog`，不允许端口转发、PTY 和代理转发。”如果紧急工作需要交互式 shell，就创建一个由人操作的独立身份。不要因为代理身份已经可用，就悄悄重复使用它。

主机验证也应记录在案。注明代理端集成如何检查主机身份、已知主机条目存放在哪里，以及合法更换主机后由谁更新这些条目。为了应对重建而关闭主机验证，会让有效凭据被发送到错误的机器。

## 好用的清单会迫使人回答关键问题

把下面的模板复制到受控文档、工单系统或清单数据库中。可以删除团队无法维护的列，但不要删除用于确定权限、范围和恢复方式的字段。

| 字段 | 记录内容 |
|---|---|
| 凭据 ID | 稳定的内部 ID，以及非秘密的令牌后缀或 SSH 指纹 |
| 通道 | HTTP API 或 SSH |
| 系统和用途 | 服务商或主机服务，以及具体的代理任务 |
| 环境和目标 | 账户、租户、主机组、仓库或端点边界 |
| 允许的操作 | 动词、目标、限制和禁止的操作 |
| 响应数据 | 代理可以接收或在输出中暴露的数据 |
| 负责人和备用负责人 | 指定的系统负责人和获授权的备用负责人 |
| 保管人 | 可以创建、撤销和轮换材料的个人或团队 |
| 存储位置 | 保险库引用或受管理的位置，绝不放秘密值 |
| 代理路径 | 指定的代理集成、工具调用或批准的执行路径 |
| 审批级别 | 无需审批、每次会话或每次使用，并注明原因 |
| 轮换计划 | 触发条件、计划日期或周期、负责人、替换测试 |
| 撤销方法 | 准确的控制台角色、命令或运行手册引用 |
| 证据 | 审计位置、上次审核日期和审核人 |

`代理路径`这一列会迫使团队回答一个有用的问题：代理如何获得这份凭据所提供的能力？“编程 shell 中的环境变量”是一种答案，但它应该让你感到不安，因为进程可能打印、传输或持久化这个值。“操作网关执行请求并返回响应”则是另一种设计，暴露路径更小。

`撤销方法`字段应该让其他人也能执行。“去找 Sam”不是方法。“在服务商项目设置中禁用令牌，然后撤销当前代理会话”才是方法。第一次添加记录时就测试这条指令，不要等事故发生后才发现每个控制台页面都变得陌生。

不要只用“活动”或“非活动”这样的状态字段。加入 `last used`、`last reviewed` 和 `planned retirement`。未使用的凭据并不安全，项目结束后没人记得撤销的往往就是它。

## 轮换计划必须包含替换和验证

只有在旧凭据被禁用，并且替代凭据通过真实代理路径完成了预期操作后，轮换才算完成。创建新令牌、把它放进存储中，再承诺以后处理旧令牌，会让两个身份同时有效，事故发生时工作量也会翻倍。

轮换计划应写明五项运行事实：

1. 触发轮换的事件，例如计划到期、员工离职、怀疑泄露或权限范围变化。
2. 创建替代凭据的人，以及批准权限变化的人。
3. 新材料的存储位置，且不会因此交给代理。
4. 用于证明替代凭据有效的最小测试操作。
5. 撤销旧材料并记录证据的准确时点。

使用范围狭窄的测试。对于 HTTP 凭据，调用一个需要预期权限且无害的端点，并确认状态和响应结构符合预期。对于 SSH，在批准的主机组上执行强制部署状态命令，而不是用通用 shell 登录测试。

测试记录可以简单写成：

```text
Credential ID: api-catalog-deploy-prod-01
Replacement ID suffix: ...7KQ2
Test: POST /deployments/validate for catalog-api revision 8f3c
Expected: HTTP 200 with validation status accepted
Old credential revoked: provider audit event recorded
Reviewer: production service owner
```

不要制定团队无法遵守的轮换周期。反复例外会让人把清单当成虚构物。服务商支持时使用到期机制，建立事件驱动的触发条件，并让审核周期与风险相匹配。生产写入权限、对敏感数据的广泛读取权限，以及共享主机的 SSH 访问，都比没有敏感响应数据的一次性 staging 令牌更值得严格审查。

如果怀疑泄露，服务能够承受时应先撤销。团队经常浪费时间试图确认泄露的令牌是否来自终端缓冲区、CI 日志、提示词记录或本地历史。通常不需要在停止凭据前证明这一点。保留日志，替换凭据，然后调查泄露路径。

## 代理审批应跟随调用后果

代理运行有普通脚本通常没有的生命周期：有人启动它，离开一段时间，回来后才发现它已经发出了许多外部调用。因此，清单不仅应写明谁负责凭据，还应说明何时需要人工授权。

对于一个边界清晰、由可信且已识别的本地代理进程执行、后果低到中等的运行，可以采用每次会话审批。它确认该进程在存活期间可以使用列出的权限，但不意味着未来每一次调用都可以自动放行。

对于可能发布内容、部署服务、修改生产数据、访问高敏感度响应，或创建新的外部承诺的操作，应要求每次使用都审批。多点一下，比向客户或财务团队解释意外操作便宜得多。如果服务商支持，审批级别不同的操作应使用不同凭据。

审批不能替代权限范围。由于请求描述含糊、操作发生在事故期间，或代理快速连续发出了多个相似调用，人可能批准错误的事情。先把权限范围缩小，再用审批覆盖范围控制无法表达的剩余风险。

Sallyport 会把 API 和 SSH 凭据保存在 Mac 的加密保险库中，并可要求新代理进程启动时，或每次使用选定凭据时进行授权，同时代理收到的是结果而不是秘密。

好的清单会把每一项高后果记录映射到使用后预期产生的审计证据。记录会话标识符或运行日志位置、每次调用的活动记录、目标、时间戳、结果，以及适用时的批准人。如果证据无法说明哪份凭据产生了哪项结果，那么这套代理集成对于你授予的权限来说过于不透明。

## 审计记录能在糟糕的运行后解决争议

清单是预防性工作。代理行为异常后，审计记录回答的是另一个问题：它实际尝试了什么，哪些成功了，以及哪项权限让它成为可能。不要把这两项工作混在一起。维护良好的清单无法证明某次调用确实发生，日志也无法证明某项权限是合理的。

围绕一条清单记录进行事故演练。让操作者找到负责人，撤销凭据，停止当前代理访问，确定最后一次成功调用，并验证审计轨迹没有被改动。测量的是困惑程度，而不只是经过的时间。如果人们说不清目标账户，或分不清旧令牌和替代令牌，就修正清单字段。

当多人可以查看或导出日志时，篡改证据很重要。普通的只追加数据库可能被拥有足够权限的管理员修改，然后伪装成历史记录。哈希链式日志可以在用保存的序列验证链条时发现未经授权的修改。但它不能让原始请求变得明智，也不能阻止获授权的人做出错误调用。这是两类不同的控制措施。

把审计保留期限的决定与清单记录放在一起，尤其是在响应可能包含敏感输出时。活动记录应保留足够的上下文供调查使用，同时不要永远随意保存完整的客户载荷。尽可能保存请求元数据和结果状态，只有在确实必要且获得允许时，才保留完整响应。

首先应完成的凭据记录，是代理今天就能用来修改生产环境的那一条。准确写明目标，让允许的动词具体明确，把撤销指令写到其他人也能照做，并测试替换路径。如果这一行还充满猜测，那么其余清单都只是装饰。