AI Agent 技能的安全陷阱:oz-skills 中权限最小化与密钥保护最佳实践
AI Agent 技能的安全陷阱:oz-skills 中权限最小化与密钥保护最佳实践
🔐 oz-skills 是一个面向 Warp AI agents 与 Oz 的开源 Agent Skills(AI Agent 技能)合集,每个技能就是一个文件夹加一份 SKILL.md 说明书,让 AI Agent 按你的工作流做事。但"会做事"也意味着"能犯错"——本文将用 6 个来自 oz-skills 的权限最小化与密钥保护最佳实践,帮你避开 AI Agent 技能中最常见的安全陷阱。
3 秒看懂 oz-skills:Agent Skills 是什么?
💡 把技能理解为"给 AI Agent 的新员工入职手册":它告诉 Agent 何时触发、按什么流程做、哪些红线不能碰。
- 技能存放在项目的
.agents/skills/或全局的~/.agents/skills/目录 - 每个技能是一个文件夹,核心是带 YAML 元信息的
SKILL.md:
name: ci-fix
description: Diagnose and fix GitHub Actions CI failures.
- Agent 会自动发现并在相关任务中加载技能
想获取完整技能库,执行:
git clone https://gitcode.com/gh_mirrors/oz/oz-skills
把需要的技能文件夹(如 docs-update)复制到你的项目 .agents/skills/ 下即可生效,更多说明见 README.md 与 AGENTS.md。
AI Agent 技能常见的 3 大安全陷阱
| 陷阱 | 典型后果 |
|---|---|
| ⚠️ 权限给太大 | Agent 为了"让测试通过"悄悄扩大 token 权限,一个技能失控就可能影响整个仓库 |
| ⚠️ 破坏性操作无确认 | 定时任务、--force 推送、丢弃未提交修改,执行前没有人工点头 |
| ⚠️ 密钥混进代码 | API key 硬编码在技能脚本或 MCP 服务里,随仓库一并泄露 |
这些不是臆想,而正是 oz-skills 各技能文档中反复强调的防线。下面 6 条最佳实践全部可在仓库中找到出处。
6 个权限最小化与密钥保护最佳实践
实践 1:最小权限——只给 CI 工作流必要的权限
.agents/skills/ci-fix/SKILL.md 的安全守则直接点题:
- 保持 workflow
permissions:最小化,不要为了通过测试而扩大 token 访问范围 - 修改工作流文件时保留既有权限设置,避免顺手"解锁"
- 慎用
pull_request_target——它可能把 secrets 暴露给不可信代码
一句话:Agent 修 CI 时,权限只减不增。
实践 2:认证前置——先验证身份再动手
.agents/skills/create-pull-request/SKILL.md 要求 Agent 在执行任何写操作前先做预检:
gh --version确认工具可用gh auth status确认已认证- 未认证时停下来引导用户,而不是硬着头皮继续
认证前置能避免"半路失败留下脏状态",也让 Agent 的行为边界更清晰。
实践 3:破坏性操作——必须获得显式确认
- 定时技能 .agents/skills/scheduler/SKILL.md 明确:未经显式确认不调度破坏性动作、不改动无关的系统计划、让每个计划项"隔离且可检查"
- 创建 PR 时遇到未提交修改,Agent 会先询问是提交、暂存还是丢弃,绝不擅自决定
✅ 好规则:Agent 可以建议,但"删除类"动作必须人来按确认键。
实践 4:密钥保护——API key 只进环境变量,不进代码
.agents/skills/mcp-builder/reference/mcp_best_practices.md 给出了完整的安全基线:
- API key 存放在环境变量中,绝不写入代码
- 使用 OAuth 2.1 并校验 token 是否专为本服务签发
- 本地服务绑定
127.0.0.1而非0.0.0.0,开启 DNS 重绑定防护 - 出错时返回"有帮助但不泄密"的错误信息
.agents/skills/terraform-style-check/SKILL.md 也把"Never hardcode credentials or secrets"写进了风格检查红线。
实践 5:风险分级——用工具注解声明只读/破坏性
自建 MCP 工具时,.agents/skills/mcp-builder/SKILL.md 建议为每个工具打上注解:
| 注解 | 含义 |
|---|---|
readOnlyHint |
只读,不改变环境 |
destructiveHint |
可能执行破坏性更新 |
idempotentHint |
重复调用无副作用 |
openWorldHint |
会接触外部实体 |
注意:注解是"提示"而非安全保证,客户端不应只凭注解做安全决策——这本身就是最小权限思维的一部分。
实践 6:保守执行——最小修复 + 人工复核
ci-fix技能要求"最小、聚焦的 diff":只修坏掉的那一步,避免无关重构- docs-update 技能 的原则是 Conservative(宁可不更新也不制造噪音)、Clear(说清楚为什么改),并且自动生成的变更会开 PR 请求人工复核
让 Agent"小步走、留证据、等人审",是兜住一切意外的最后一道闸。
AI Agent 技能安全自查清单
把下面 5 项放进你的技能评审流程:
- [ ] 工作流 / CLI token 权限是否已收窄到最小范围?
- [ ] 写操作前是否有
gh auth status之类的认证前置检查? - [ ] 删除、强推、覆盖等动作是否强制人工确认?
- [ ] 代码与脚本中是否零硬编码密钥?(API key 一律走环境变量)
- [ ] 高风险工具是否标注了
destructiveHint并默认保守执行?
延伸阅读
- 技能格式规范与元信息写法:AGENTS.md
- 提交新技能的流程:CONTRIBUTING.md
- 各技能源码目录:.agents/skills/
🧩 记住:给 AI Agent 写技能,本质是在写一份"授权书"。权限最小化 + 密钥不进代码,这两条守住,安全陷阱就少了一半。