Software Agent SDK（OpenHands Agent SDK V1）是一套用于构建 AI Agent 的模块化 Python SDK，其内置的密钥管理与纵深防御（Defense-in-Depth）安全体系是新手最容易被忽视、却最关键的部分：SDK 在 openhands-sdk/openhands/sdk/security/ 目录下提供了从风险分级、威胁签名扫描到人工确认门禁的完整链路，让 Agent 执行每个动作前都能被"安检"。本文将用一份清单式指南，带你快速看懂这两大安全机制的设计思路与落地方式。

为什么 AI Agent 需要专门的安全体系

AI Agent 与普通的聊天机器人不同——它会直接执行终端命令、修改文件、访问网络。一个被诱导或"幻觉"驱动的 Agent 执行rm -rf /或curl ... | sh的后果是真实的。

OpenHands Software Agent SDK 的应对思路是纵深防御：不依赖任何单一检测手段，而是串联多层检查，任何一层失效都有下一层兜底。核心模块路径：

• 风险定义：risk.py
• 分析器基类：analyzer.py
• 本地确定性检测：defense_in_depth/
• 确认策略：confirmation_policy.py
• 密钥体系：secret/ 与 conversation/secret_registry.py

密钥管理：Software Agent SDK 的安全地基

密钥抽象：StaticSecret 与 LookupSecret

SDK 在 secrets.py 中定义了SecretSource抽象基类，并提供两种实现：

LookupSecret有一个很实用的设计：进程内可以注册LocalSecretResolver，让同时"既提供又消费"密钥的 agent-server 直接本地解析，避免 HTTP 自环导致的死锁等待。

会话级"保险柜"：SecretRegistry

真正管理密钥生命周期的是 secret_registry.py 中的SecretRegistry。它把密钥注册到会话上下文中，并在事件、工具输出等文本中递归执行掩码（masking）替换，防止密钥随日志、轨迹或 LLM 上下文外泄。参考示例：

• 自定义密钥示例：12_custom_secrets.py

透明加密与脱敏：三种序列化模式

密钥落盘时由 cipher.py 与 pydantic_secrets.py 协同处理，支持三种模式：

1. redact（默认脱敏）：替换为**********占位符，最安全；
2. encrypted：用 Fernet 对称加密后存储，前端无法解密，适合需要"回读"的场景；
3. plaintext：明文暴露，仅限可信后端使用。

加密失败时（如换钥升级）会安全降级为脱敏而非抛出明文，保证"最坏情况也不泄露"。

导出边界红action：把凭证挡在轨迹文件之外

agent-server 侧的 _secret_redaction.py（见 openhands-agent-server/openhands/agent_server/_secret_redaction.py）在轨迹导出（trajectory download）等"数据离开服务器"的边界做最后一道递归清洗：无论是明文还是 Fernet 密文（gAAAAA前缀）都会被替换为脱敏标记，确保下载的会话文件永远不携带可恢复的凭证。

纵深防御：多层安全分析器策略清单

风险分级：SecurityRisk 四级模型

risk.py 定义了LOW/MEDIUM/HIGH/UNKNOWN四级风险。一个值得新手注意的细节：UNKNOWN与任何级别都不可比较（比较会抛ValueError），它专门用于表达"评估失败/无法判定"，并会在确认策略中 fail-safe（默认要求确认）。

第一层：PatternSecurityAnalyzer 确定性签名扫描

pattern.py 使用双语料策略扫描 Agent 动作：

• 可执行语料（工具参数）：匹配rm -rf变体、sudo rm、mkfs、dd写裸盘、curl | sh、subprocess调用等破坏性签名；
• 全字段语料（含思考/推理文本）：匹配 "ignore all previous instructions" 等提示注入话术。

关键设计：破坏性命令只扫描"将要执行"的内容，不误伤 Agent 只是"想到"的命令；所有正则做了有界量词约束以防止 ReDoS 攻击。

第二层：PolicyRailSecurityAnalyzer 组合威胁检测

policy_rails.py 处理"组合才有毒"的结构性威胁，v1 内置三条规则（rail）：

按"执行段"逐段评估，避免思考文本里的curl与工具调用里的ls跨字段误触发。

第三层：EnsembleSecurityAnalyzer 最坏情况融合

ensemble.py 把多个分析器组合成一个，取所有结果中最高的具体风险等级。两条重要的安全兜底：

• fail-closed：某个子分析器抛异常时，该动作直接计为HIGH——坏掉的检测器不能悄悄降低安全性；
• propagate_unknown=True严格模式：任一子分析器返回UNKNOWN，整体即UNKNOWN（默认触发人工确认），适合更严格的环境。

第四层：LLM 自评估与外部 AI 安全监控

• LLMSecurityAnalyzer（llm_analyzer.py）：读取 LLM 生成动作时自行标注的security_risk；
• ToolShieldLLMSecurityAnalyzer（toolshield_llm_analyzer.py）：调用 LLM 做工具调用安全评审，并结合安全经验库；
• GraySwanAnalyzer（grayswan/analyzer.py）：接入外部 GraySwan Cygnal API，把对话历史+待执行动作送审，按返回的 violation score 映射到三级风险（low_threshold=0.3/medium_threshold=0.7可调）。

人工门禁：ConfirmationPolicy 三种策略

分析器只"打分"，是否拦截由确认策略决定，见 confirmation_policy.py：

另外，分析器基类的默认行为是"错误即高危"：分析过程抛异常时，该动作按HIGH处理（analyzer.py 第 127-144 行）。

纵深防御配置清单（快速上手）

完整可运行示例见 47_defense_in_depth_security.py，核心接线只有三行：

security_analyzer = EnsembleSecurityAnalyzer( analyzers=[PolicyRailSecurityAnalyzer(), PatternSecurityAnalyzer()] ) confirmation_policy = ConfirmRisky(threshold=SecurityRisk.HIGH) conversation.set_security_analyzer(security_analyzer) conversation.set_confirmation_policy(confirmation_policy)

配套清单：

• 想更严格？把阈值降到ConfirmRisky(threshold=SecurityRisk.MEDIUM)；
• 想加 LLM 评审？往EnsembleSecurityAnalyzer的列表里追加ToolShieldLLMSecurityAnalyzer；
• 想定制风险判断口径？参考自定义安全策略示例 32_configurable_security_policy.py，用自定义CUSTOM_SECURITY_POLICY文本指导 LLM 自评；
• 想体验确认交互？见 04_confirmation_mode_example.py。

💡 记住这条黄金法则：分析器选择不会自动改变确认策略，两者必须显式分别配置——这是 Software Agent SDK 安全体系最常见的配置误区。

总结

OpenHands Software Agent SDK 的安全体系可以概括为一张"双清单"：

1. 密钥管理清单：SecretSource抽象 →SecretRegistry会话掩码 → 三模式序列化（脱敏/加密/明文）→ 导出边界二次清洗，密钥在"输入、存储、运行、导出"四个环节都不落地明文；
2. 纵深防御清单：SecurityRisk分级 → 签名扫描 + 组合威胁检测 → 最坏情况融合（fail-closed）→ LLM/外部 AI 监控 →ConfirmRisky人工门禁，任何单层失效都有下一层兜底。

对新手来说，默认配置（Pattern + PolicyRail +ConfirmRisky(HIGH)）已经能挡住绝大多数危险动作；理解本文的层级设计后，你就可以按业务敏感度自由加码，构建属于自己的 AI Agent 安全边界。