secure-ai-agent-coding

secure-ai-agent-coding

构建或审查 AI Agent 和大模型应用，确保其影响范围有限、行为可审计，并要求对高影响操作进行明确控制。

根据实际信任边界、数据敏感度、操作影响和部署方式调整控制措施。只读公共数据助手、一次性编码沙箱和生产环境中的支付 Agent 需要不同的控制措施。在模型之外实现授权和隔离；只要能保证这些安全要求，架构和实现方式就保持开放。参考目录是一份风险检查清单，并不要求为每项功能添加所有机制。

决策树

用户的需求是什么？

• 构建新的 AI Agent 或大模型功能： 对不熟悉的控制边界，使用 references/implementation-patterns.md；针对相关风险，使用 references/controls.md。
• 审查现有代码库或设计： 使用 references/review-workflow.md 确定审查范围。可选扫描器能在不熟悉的代码中定位线索；对于已知代码路径，也可以直接检查。
• 添加工具、系统调用、代码执行、数据库写入、API 调用或电子邮件／消息发送功能： 选择控制措施前，先对具体影响进行分类。阅读 references/implementation-patterns.md，了解如何强制执行能力边界；高影响操作必须逐项授权，并要求明确批准或采用可接受的等效机制，而不是对已获授权的沙箱工作反复征求人工许可。
• 处理用户数据、生产数据、文档、网页、电子邮件、向量存储、嵌入或微调数据： 使用 references/threat-model.md 了解注入和数据流风险；涉及生产环境、同意、保留或生命周期义务时，添加 references/governance.md。
• 调试安全事件、模型异常行为、提示词注入、数据泄露或有害自动化： 阅读 references/review-workflow.md 和 references/gotchas.md，保留日志，停止自主操作，并从已知的安全状态恢复。
• 需求仅涉及通用 Web 应用安全，不涉及 AI、模型、RAG、工具调用或 Agent 工作流： 除非任务涉及 AI 特有的攻击面，否则不要使用此技能。

快速参考

任务	操作
查找可能危险的模式	运行 python3 scripts/scan_patterns.py /path/to/project
对风险分类	按影响、可逆性、数据敏感度和外部副作用为每项 Agent 操作划分等级
保护提示词	将指令与不可信数据分开；验证、分隔并尽量减少上下文
保护工具调用	使用明确的允许列表、限定范围的凭据、逐项授权和速率限制
保护用户和数据	对数据分类、尽量减少披露、对日志脱敏、验证同意，并避免在测试系统中使用原始生产数据
保护下游系统	将结构化模型输出用于代码、SQL、shell、API 或 UI 渲染前进行验证
保护生产环境	添加监控、异常告警、安全回归测试、回滚计划和事件响应步骤
审查例外情况	记录控制措施不适用的原因、风险接受者以及到期时间

核心工作流

1. 梳理 AI 的作用范围：模型调用、提示词、检索内容、工具、状态、凭据、数据存储和外部副作用。
2. 将所有输入归类为不可信，除非它由可信的服务端组件生成；即便如此，也要对其进行验证。
3. 对 Agent 能执行的每项操作进行分类。默认采用可逆、低权限的操作，并将高影响操作升级为需人工审批。
4. 在受影响的边界选择控制措施。架构、允许列表、服务端授权、幂等性、速率限制、锁定、回滚和审计日志分别应对不同风险；根据操作和环境的要求选用。
5. 除非模型确实需要，否则不要在提示词和日志中保留敏感数据。优先采用脱敏、令牌化、匿名化或合成数据。
6. 在 AI 输出进入下游解释器、渲染器、数据库、API、文件系统或 shell 命令之前对其进行验证。
7. 模型、提示词、框架、依赖项、检索或工具发生变更后，测试受影响的安全性和输出契约。共享边界发生变更时，进行更广泛的回归测试。

控制路由

领域	加载内容
端到端审查流程、严重程度、报告格式	references/review-workflow.md
控制措施目录和证据检查清单	references/controls.md
可直接复制的实现模式	references/implementation-patterns.md
AI 专属威胁场景和风险等级	references/threat-model.md
清单、同意、模型更新、生命周期和运维	references/governance.md
常见失效模式和审查陷阱	references/gotchas.md
源内容转换说明和范围排除项	references/source-policy.md

运维脚本

将 scripts/scan_patterns.py 用作第一轮启发式扫描器，而非安全性证明。

python3 scripts/scan_patterns.py /path/to/project
python3 scripts/scan_patterns.py /path/to/project --json --fail-on high

该扫描器有意侧重于提供审查提示，而非自动判定。请将发现的问题视为需要检查的内容。

源内容范围

此技能将 Galdren 的《Secure AI & Agent Coding Policy》中适用于工程的控制措施改编为 Agent 技能。它保留了可用于代码审查、架构决策、本地检查和生产环境加固的部分。对于法律判断、组织特定的审批和物理安全，它仅提示应联系相应团队，而不会假装编码技能能够解决这些问题。

当打包的建议失效或提供方／框架的契约发生变化时，请查阅相关的、版本匹配的官方文档以及 OWASP、NIST 或 MITRE 等可信的一手指导。安全地验证受影响的控制措施；当前文档并不授权扩大访问范围或披露数据。明确说明无法获取的证据。请针对受影响的规则、来源／版本以及威胁场景或回归问题，提出对规范技能的修正建议，而不要悄悄更新已安装的副本或发布它。

注意事项

1. 仅靠提示词防御远远不够。应在模型之外强制执行授权、验证和工具限制。
2. 用作验证器的模型仍属于 AI 输入面。应像验证其他组件一样验证其输入和输出。
3. “已通过身份验证的用户”不等于“已获授权的 Agent 操作”。应单独检查每项操作。
4. 日志可能造成数据泄露。记录足够的信息以便调查，同时对机密、个人数据和敏感上下文进行脱敏。
5. 模型或框架升级可能在没有代码差异的情况下改变行为。每次变更后都要重新测试安全性和输出契约。
6. 广泛的工具访问权限会将小小的提示词失误演变为生产事故。在每个步骤中都要尽量缩小 Agent 的权限范围。