AI Agent 安全如何保障？AgentArmor 开源 8 层安全框架深度实践

随着 AI Agent 从实验性项目走向生产环境，安全问题成为开发者无法回避的话题。Prompt 注入、Goal Hijacking（目标劫持）、凭证泄露、数据投毒——这些威胁不再是理论风险，而是每天都在 AI Agent 生产环境中真实发生的事件。

如果你正在使用 Claude Code、Cursor、OpenCode 或自定义 AI Agent 来处理文件读写、数据库查询或 API 调用，那么 Agent 的安全防御绝不是「以后再说」的事。

本文将深入介绍 AgentArmor——一个对标 OWASP Top 10 for Agentic Applications (2026) 的开源 8 层安全框架，通过代码示例展示如何为你的 AI Agent 构建端到端的安全防线。

简介

AgentArmor 是首个统一的全链路 AI Agent 安全框架，提供 8 层纵深防御（Defense-in-Depth），覆盖从数据输入到输出的每一个环节。

AgentArmor 将安全视为端到端管道——在 Agent 生命周期的每个关键节点设置安全护栏：

v0.5.0 版本更是将 L3-L6 四个核心层升级为生产级加固引擎，通过了 127+ 对抗性测试案例。

快速安装

AgentArmor 使用 Python 编写，通过 PyPI 发布，推荐使用 uv 安装：

# 核心库
uv add agentarmor-core

# 带 MCP 服务器支持（用于 Claude Code、OpenClaw 等）
uv add "agentarmor-core[mcp]"

# 带 PII 检测
uv add "agentarmor-core[pii]"

# 全功能安装
uv add "agentarmor-core[all]"

核心功能实战

1. 基础拦截：接管 Agent 的每一次操作

最简单的使用方式是在 Agent 启动时创建一个 Armor 实例，用它来拦截所有工具调用：

import asyncio
from agentarmor import AgentArmor

async def main():
    armor = AgentArmor()

    # 注册 Agent 身份
    identity, token = armor.l8_identity.register_agent(
        agent_id="my-agent",
        permissions={"read.*", "search.*"},
    )

    # 拦截工具调用，自动通过 8 层安全检查
    result = await armor.intercept(
        action="read.file",
        params={"path": "/data/notes.txt"},
        agent_id="my-agent",
        input_data="Read the file please",
    )

    print(f"安全通过: {result.is_safe}")
    print(f"裁决结果: {result.final_verdict.value}")

asyncio.run(main())

intercept() 会自动将请求送入全部 8 层安全管道——从输入验证到执行控制再到输出过滤，一气呵成。也可以用作装饰器：

@armor.shield(action="database.query")
async def query_database(sql: str) -> dict:
    return db.execute(sql)

2. L3 Context 加固：防止目标劫持

AI Agent 最危险的攻击面之一是 Goal Hijacking——恶意用户通过 Prompt 注入让 Agent 忘记原始任务，转而执行危险操作。

AgentArmor 的 L3 层提供 GoalLock 机制：在每次对话开始时将 Agent 的原始目标锚定到系统提示中，并在对话过程中持续校验：

from agentarmor.layers.context.assembler import L3ContextLayer

l3 = L3ContextLayer(
    agent_id="my-agent",
    agent_config={
        "system_prompt": "You are a code review assistant.",
        "tools": ["git_diff", "read_file"],
    },
)

# 构建加固后的系统提示（含 GoalLock 锚定 + Canary 令牌）
hardened_prompt = l3.build_secure_system_prompt(
    base_system_prompt="You are a code review assistant.",
    conversation_id="session-123",
)

# 检测 LLM 输出中是否泄露了 Canary 令牌，或发生了目标漂移
safe_response, events = await l3.check_output(
    conversation_id="session-123",
    response=llm_response,
    tool_calls=[],
    turn_number=1,
    user_message=user_input,
)

GoalLock 还配合 CanaryVault 机制——在每个 Session 中注入多个独特的 Canary 令牌，如果 Agent 的响应中出现了这些令牌（意味着系统提示被泄露），立即触发告警。

3. L5 执行控制：谁做了什么、能做什么

L5 层是执行层面的硬控制，包含五个强制执行域：网络策略、速率限制、资源预算、输出消毒和副作用审计。

以下是一个配置了精细化网络策略和安全强控的执行示例：

from agentarmor.layers.execution.l5_execution import L5ExecutionLayer, NetworkPolicy

l5 = L5ExecutionLayer(
    agent_id="my-agent",
    network_policy=NetworkPolicy(
        allow_http=False,  # 仅允许 HTTPS
        domain_allowlist=["api.github.com", "*.openai.com"],
        domain_blocklist=["metadata.google.internal", "*.local"],
        dns_rebinding_protection=True,
        max_outbound_payload_bytes=50_000,
    ),
)

# 执行工具调用，经过 L5 完整链路审核
result, event = await l5.execute(
    tool_name="web_search",
    tool_args={"query": "latest AI news"},
    tool_func=my_search_function,
    session_id="session-123",
    outbound_url="https://api.tavily.com/search",
)

想象一下：即使 Agent 被诱导去访问 metadata.google.internal 这类云元数据端点，L5 的 domain_blocklist 会直接将其拦截。不需要修改 Agent 的业务代码——安全策略与应用逻辑完全解耦。

4. L6 输出安全：不让敏感信息流出

AI Agent 的输出是最后一道防线。如果 Agent 在对话中泄露了 API 密钥、客户手机号或内部文档，后果不堪设想。

AgentArmor 的 L6 层是一个五扫描器管道，对每一次输出做全面安全检查：

from agentarmor.layers.output.filter import L6OutputLayer

l6 = L6OutputLayer(
    agent_id="my-agent",
    enable_pii_scan=True,       # 身份证号、邮箱、电话检测
    enable_harmful_scan=True,   # 有害内容阻断
)

# 扫描 LLM 响应
safe_text, result = l6.process(llm_response, session_id="session-123")

if result["verdict"] == "block":
    print("⚠️ 响应包含严重安全违规，已拦截！")
else:
    print(f"✅ 清理完成: 发现 {result['findings_count']} 项，已脱敏")

五个扫描器包括：凭据识别（13+ 模式，零误报）、PII 检测（置信度门控）、有害内容识别（Jailbreak + 系统提示泄露）、语义泄露追踪（跨响应关联）和 Schema 校验。同时支持流式和非流式响应模式。

5. MCP Server 集成：零代码接入

如果你正在使用 Claude Code、Cursor 或任何 MCP 兼容的编码 Agent，AgentArmor 可以直接作为 MCP Server 运行——不需要改 Python 代码。

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "agentarmor": {
      "command": "uv",
      "args": ["run", "agentarmor-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

MCP Server 模式下可用的工具：

对于 LangChain 和 OpenAI SDK 用户，AgentArmor 也提供了原生集成：

# LangChain
from agentarmor.integrations.langchain import AgentArmorCallback
callback = AgentArmorCallback(armor=armor)

# OpenAI
from agentarmor.integrations.openai import secure_openai_client
client = secure_openai_client(OpenAI(), armor=armor)

实战技巧与最佳实践

1. 从策略文件开始

将安全配置与代码分离：

# policies/database_agent.yaml
version: "1.0"
name: "database_agent"
risk_level: "high"

global_denied_actions:
  - "database.drop"
  - "database.truncate"

require_human_approval_for:
  - "database.delete"

这样做的好处是：安全团队可以独立审核和调整策略，开发人员不需要理解安全细节。

2. 分层启用，由松到严

不建议一开始就全量启用所有 8 层；先启用 L1（输入扫描）和 L6（输出过滤）观察效果，逐步扩展到 L3、L5 等开销较高的层。

3. 用 MCP Server 扫描做供应链安全

armor_scan_mcp_server 可对第三方 MCP Server 自动做 TLS 验证、OAuth 2.1 合规和 Rug Pull 检测——接入新服务前用其做安全评级，避免引入恶意或配置不当的服务。

总结

AgentArmor 是一个统一的全链路 AI Agent 安全框架——从身份管理到输出过滤，用 8 层纵深防御覆盖 Agent 的每一个关键节点。127+ 对抗性测试案例、MCP Server 原生支持和 OWASP ASI 全覆盖，使其在生产环境中具备实用价值。

如果你的 AI Agent 正在处理真实数据或执行系统操作，AgentArmor 值得纳入技术栈。安全问题不是「会不会发生」，而是「什么时候发生」——提前防御总比事后补救划算。

项目地址：github.com/Agastya910/agentarmor 许可证：Apache 2.0