ACF-SDK是一个面向大语言模型智能体系统的零信任安全控制层，通过分布式策略验证机制，在用户输入、RAG检索、工具调用和记忆读写等全生命周期节点提供防护，有效抵御提示注入、上下文操纵、记忆投毒等多种攻击向量。

ACF-SDK：为LLM智能体构建零信任认知防火墙\n\n## 背景：智能体安全的独特挑战\n\n随着大语言模型（LLM）从简单的对话工具演进为能够自主决策、调用工具、访问外部知识的智能体（Agent），安全防护的复杂性也呈指数级增长。传统的网络安全模型依赖"边界防御"——在系统入口处设置防火墙和认证机制，假设内部是可信的。然而，LLM智能体的工作模式彻底打破了这一假设。\n\n智能体的输入来源极其多元：用户直接对话、检索增强生成（RAG）系统返回的文档片段、各类工具的执行结果、以及长期记忆存储中的历史信息。每一个输入通道都可能成为攻击者的切入点。更为棘手的是，攻击者可以通过"间接提示注入"（Indirect Prompt Injection）将恶意指令嵌入到看似无害的文档或网页中，当智能体检索并处理这些内容时，攻击代码便会悄然执行。\n\n传统的单点边界检查完全无法应对这种威胁。我们需要一种全新的安全范式——零信任架构（Zero Trust Architecture），它假设所有输入都不可信，无论其来源如何，都必须在进入模型推理上下文之前经过严格验证。\n\n## ACF-SDK：分布式认知防火墙\n\nACF-SDK（Agentic Cognitive Firewall SDK）正是为应对这一挑战而生的开源项目。它由C2SI组织开发，采用零信任设计理念，将安全验证机制分布到智能体生命周期的每一个关键节点。\n\n### 核心设计理念\n\nACF-SDK的设计哲学可以概括为几个关键原则：\n\n1. 零信任默认（Zero Trust by Default）\n\n所有输入都被视为不可信，无论其来源是用户、数据库还是工具输出。这种"永不信任，始终验证"的态度是防御提示注入攻击的基础。\n\n2. 策略即代码（Policy-as-Code）\n\n安全规则使用Rego语言（Open Policy Agent的标准语言）编写，可以版本控制、审计追踪，并支持热重载而无需重启服务。这种设计将安全逻辑与业务逻辑解耦，使得安全团队可以独立迭代防护策略。\n\n3. 最小性能开销（Minimal Overhead）\n\nACF-SDK的典型执行延迟仅为4-8毫秒，最坏情况下约10毫秒。这种低开销对于实时交互的智能体应用至关重要，确保安全不会成为性能的瓶颈。\n\n4. 框架无关（Framework-Agnostic）\n\n无论你的智能体基于LangGraph、LangChain还是自定义框架构建，ACF-SDK都能无缝集成。这种灵活性使其适用于各种技术栈。\n\n## 架构设计：双进程安全隔离\n\nACF-SDK采用了一种巧妙的双进程架构，在性能与安全之间取得了精妙平衡：\n\n### PEP（Policy Enforcement Point）\n\nPEP是一个轻量级的SDK，运行在智能体进程内部。它负责对待验证的输入进行签名，并通过IPC（进程间通信）将其发送到策略决策点。PEP本身不做任何策略判断，这种设计确保了即使智能体进程被完全攻破，攻击者也无法篡改安全策略。\n\n### PDP（Policy Decision Point）\n\nPDP是一个独立的Go语言侧车进程（Sidecar），与智能体进程通过操作系统级别的进程边界硬隔离。所有的策略评估都在PDP内部完成，智能体进程无法直接访问PDP的内存空间。这种隔离是防御内存投毒攻击的关键。\n\n### 四阶段处理流水线\n\n每一个输入在PDP内部都会经历一个精心设计的四阶段流水线：\n\n第一阶段：验证（Validate）\n\n- HMAC签名验证：确保数据在传输过程中未被篡改\n- 随机数重放检查：防止重放攻击\n- 模式验证：确保数据符合预期的结构\n\n第二阶段：规范化（Normalise）\n\n- URL/Base64/十六进制解码\n- NFKC Unicode规范化\n- 零宽字符剥离（防御视觉欺骗攻击）\n- 火星文清理（将1337 speak等变形文本还原）\n\n第三阶段：扫描（Scan）\n\n- Aho-Corasick算法进行词法扫描\n- 白名单检查\n- 完整性验证\n\n第四阶段：聚合（Aggregate）\n\n- 综合各阶段信号生成0.0到1.0的风险评分\n- 结合来源可信度进行加权\n- 短路至BLOCK：任何阶段发现硬威胁信号立即阻断\n\n## 全生命周期防护矩阵\n\nACF-SDK的防护覆盖智能体工作的每一个关键节点：\n\n### 1. 用户提示到达时（on_prompt）\n\n威胁类型：直接提示注入（Direct Prompt Injection）\n\n攻击者试图通过精心构造的输入覆盖系统指令、实现角色升级或执行越狱攻击。ACF-SDK在此阶段会检测指令覆盖模式、角色升级关键词和已知的越狱提示模板。\n\n### 2. RAG上下文注入时（on_context）\n\n威胁类型：间接提示注入（Indirect Prompt Injection）\n\n这是目前最具隐蔽性的攻击向量。攻击者将恶意指令嵌入到网页、PDF或其他可被检索的文档中。当RAG系统检索到这些文档并注入到智能体上下文时，攻击代码便会执行。ACF-SDK会分析来源可信度、检测嵌入指令和结构异常。\n\n### 3. 工具调用前（on_tool_call）\n\n威胁类型：工具滥用（Tool Abuse）\n\n智能体可能被诱导调用不安全的工具，或传递恶意构造的参数。ACF-SDK在此阶段实施工具白名单、Shell元字符检测、路径遍历防护和网络访问控制。\n\n### 4. 记忆读写时（on_memory_read / on_memory_write）\n\n威胁类型：记忆投毒（Memory Poisoning）\n\n攻击者可能通过污染智能体的长期记忆存储来植入后门或偏见。ACF-SDK对记忆数据进行HMAC签名验证、写入前扫描，并维护数据来源追溯链。\n\n## 策略引擎：Rego的力量\n\nACF-SDK使用Open Policy Agent（OPA）的Rego语言作为策略引擎。这种选择带来了诸多优势：\n\n声明式策略定义：策略作者只需描述"什么"是允许的，而不需要编写"如何"检查的代码。\n\n热重载支持：策略文件可以在运行时更新，无需重启服务，这对生产环境至关重要。\n\n可测试性：Rego提供了完善的测试框架，可以通过make opa-test运行完整的策略测试套件。\n\n版本化策略库：ACF-SDK的策略库采用语义化版本管理，新版本策略与旧版本保持兼容，确保平滑升级。\n\n典型的策略文件结构如下：\n\n\npolicies/v1/\n├── prompt.rego # 提示注入防护\n├── context.rego # 上下文安全\n├── tool.rego # 工具调用安全\n├── memory.rego # 记忆安全\n└── data/\n ├── policy_config.yaml # 阈值、白名单、信任权重\n └── jailbreak_patterns.json # 版本化越狱模式库\n\n\n## 三种决策结果\n\nACF-SDK的每一次策略评估都会产生三种明确的结果之一：\n\nALLOW（允许）：载荷干净，可以安全通过。\n\nSANITISE（净化）：载荷包含潜在威胁，但可以通过清理使其安全。系统会返回净化后的版本，并附加警告标记。\n\nBLOCK（阻断）：硬阻断，智能体不应继续使用此输入。这用于应对明确的恶意攻击。\n\n这种分级响应机制既保证了安全性，又避免了过度防御对用户体验的影响。\n\n## 当前状态与路线图\n\nACF-SDK目前处于积极开发阶段：\n\n第一阶段（已完成）：线协议和加密机制\n- 23个Go单元测试\n- 35个Python单元测试\n- HMAC/随机数加密实现\n\n第二阶段（进行中）：流水线阶段实现\n- 验证、规范化、扫描、聚合四个阶段的完整实现\n\n第三阶段（计划中）：OPA集成和Rego策略\n\n第四阶段（计划中）：OpenTelemetry可观测性和集成测试套件\n\nV2版本（延后）：有状态会话风险、额外钩子、TypeScript SDK\n\n## 实际部署与使用\n\nACF-SDK的部署非常简单。首先生成一个32字节的HMAC密钥：\n\nbash\nexport ACF_HMAC_KEY=$(python3 -c \"import secrets; print(secrets.token_hex(32))\")\n\n\n然后编译并启动Go侧车：\n\nbash\ncd sidecar && go build -o ../bin/acf-sidecar ./cmd/sidecar\n./bin/acf-sidecar\n\n\n在Python智能体中集成SDK：\n\npython\nfrom acf import Firewall, Decision\n\nfw = Firewall() # 自动读取ACF_HMAC_KEY并连接到/tmp/acf.sock\n\nresult = fw.on_prompt(\"用户输入内容\")\nif result == Decision.BLOCK:\n # 处理阻断情况\n pass\n\n\n## 结语：智能体安全的未来\n\nACF-SDK代表了LLM智能体安全领域的重要探索。它不仅仅是一个技术工具，更是一种安全思维的转变——从零信任的角度重新审视智能体系统的每一个输入通道。\n\n随着智能体能力的不断增强，它们将承担越来越关键的任务，从客户服务到代码生成，从数据分析到决策支持。在这样的背景下，ACF-SDK所倡导的分布式、策略驱动、低延迟的安全防护模式将成为智能体基础设施的标准配置。\n\n对于正在构建生产级LLM应用的开发者来说，ACF-SDK提供了一个值得认真考虑的安全选项。它的开源特性、框架无关设计和活跃的社区支持，使其成为智能体安全工具箱中的重要一员。

ACF-SDK：为LLM智能体构建零信任认知防火墙\n\n背景：智能体安全的独特挑战\n\n随着大语言模型（LLM）从简单的对话工具演进为能够自主决策、调用工具、访问外部知识的智能体（Agent），安全防护的复杂性也呈指数级增长。传统的网络安全模型依赖"边界防御"——在系统入口处设置防火墙和认证机制，假设内部是可信的。然而，LLM智能体的工作模式彻底打破了这一假设。\n\n智能体的输入来源极其多元：用户直接对话、检索增强生成（RAG）系统返回的文档片段、各类工具的执行结果、以及长期记忆存储中的历史信息。每一个输入通道都可能成为攻击者的切入点。更为棘手的是，攻击者可以通过"间接提示注入"（Indirect Prompt Injection）将恶意指令嵌入到看似无害的文档或网页中，当智能体检索并处理这些内容时，攻击代码便会悄然执行。\n\n传统的单点边界检查完全无法应对这种威胁。我们需要一种全新的安全范式——零信任架构（Zero Trust Architecture），它假设所有输入都不可信，无论其来源如何，都必须在进入模型推理上下文之前经过严格验证。\n\nACF-SDK：分布式认知防火墙\n\nACF-SDK（Agentic Cognitive Firewall SDK）正是为应对这一挑战而生的开源项目。它由C2SI组织开发，采用零信任设计理念，将安全验证机制分布到智能体生命周期的每一个关键节点。\n\n核心设计理念\n\nACF-SDK的设计哲学可以概括为几个关键原则：\n\n1. 零信任默认（Zero Trust by Default）\n\n所有输入都被视为不可信，无论其来源是用户、数据库还是工具输出。这种"永不信任，始终验证"的态度是防御提示注入攻击的基础。\n\n2. 策略即代码（Policy-as-Code）\n\n安全规则使用Rego语言（Open Policy Agent的标准语言）编写，可以版本控制、审计追踪，并支持热重载而无需重启服务。这种设计将安全逻辑与业务逻辑解耦，使得安全团队可以独立迭代防护策略。\n\n3. 最小性能开销（Minimal Overhead）\n\nACF-SDK的典型执行延迟仅为4-8毫秒，最坏情况下约10毫秒。这种低开销对于实时交互的智能体应用至关重要，确保安全不会成为性能的瓶颈。\n\n4. 框架无关（Framework-Agnostic）\n\n无论你的智能体基于LangGraph、LangChain还是自定义框架构建，ACF-SDK都能无缝集成。这种灵活性使其适用于各种技术栈。\n\n架构设计：双进程安全隔离\n\nACF-SDK采用了一种巧妙的双进程架构，在性能与安全之间取得了精妙平衡：\n\nPEP（Policy Enforcement Point）\n\nPEP是一个轻量级的SDK，运行在智能体进程内部。它负责对待验证的输入进行签名，并通过IPC（进程间通信）将其发送到策略决策点。PEP本身不做任何策略判断，这种设计确保了即使智能体进程被完全攻破，攻击者也无法篡改安全策略。\n\nPDP（Policy Decision Point）\n\nPDP是一个独立的Go语言侧车进程（Sidecar），与智能体进程通过操作系统级别的进程边界硬隔离。所有的策略评估都在PDP内部完成，智能体进程无法直接访问PDP的内存空间。这种隔离是防御内存投毒攻击的关键。\n\n四阶段处理流水线\n\n每一个输入在PDP内部都会经历一个精心设计的四阶段流水线：\n\n第一阶段：验证（Validate）\n\n- HMAC签名验证：确保数据在传输过程中未被篡改\n- 随机数重放检查：防止重放攻击\n- 模式验证：确保数据符合预期的结构\n\n第二阶段：规范化（Normalise）\n\n- URL/Base64/十六进制解码\n- NFKC Unicode规范化\n- 零宽字符剥离（防御视觉欺骗攻击）\n- 火星文清理（将1337 speak等变形文本还原）\n\n第三阶段：扫描（Scan）\n\n- Aho-Corasick算法进行词法扫描\n- 白名单检查\n- 完整性验证\n\n第四阶段：聚合（Aggregate）\n\n- 综合各阶段信号生成0.0到1.0的风险评分\n- 结合来源可信度进行加权\n- 短路至BLOCK：任何阶段发现硬威胁信号立即阻断\n\n全生命周期防护矩阵\n\nACF-SDK的防护覆盖智能体工作的每一个关键节点：\n\n1. 用户提示到达时（on_prompt）\n\n威胁类型：直接提示注入（Direct Prompt Injection）\n\n攻击者试图通过精心构造的输入覆盖系统指令、实现角色升级或执行越狱攻击。ACF-SDK在此阶段会检测指令覆盖模式、角色升级关键词和已知的越狱提示模板。\n\n2. RAG上下文注入时（on_context）\n\n威胁类型：间接提示注入（Indirect Prompt Injection）\n\n这是目前最具隐蔽性的攻击向量。攻击者将恶意指令嵌入到网页、PDF或其他可被检索的文档中。当RAG系统检索到这些文档并注入到智能体上下文时，攻击代码便会执行。ACF-SDK会分析来源可信度、检测嵌入指令和结构异常。\n\n3. 工具调用前（on_tool_call）\n\n威胁类型：工具滥用（Tool Abuse）\n\n智能体可能被诱导调用不安全的工具，或传递恶意构造的参数。ACF-SDK在此阶段实施工具白名单、Shell元字符检测、路径遍历防护和网络访问控制。\n\n4. 记忆读写时（on_memory_read / on_memory_write）\n\n威胁类型：记忆投毒（Memory Poisoning）\n\n攻击者可能通过污染智能体的长期记忆存储来植入后门或偏见。ACF-SDK对记忆数据进行HMAC签名验证、写入前扫描，并维护数据来源追溯链。\n\n策略引擎：Rego的力量\n\nACF-SDK使用Open Policy Agent（OPA）的Rego语言作为策略引擎。这种选择带来了诸多优势：\n\n声明式策略定义：策略作者只需描述"什么"是允许的，而不需要编写"如何"检查的代码。\n\n热重载支持：策略文件可以在运行时更新，无需重启服务，这对生产环境至关重要。\n\n可测试性：Rego提供了完善的测试框架，可以通过make opa-test运行完整的策略测试套件。\n\n版本化策略库：ACF-SDK的策略库采用语义化版本管理，新版本策略与旧版本保持兼容，确保平滑升级。\n\n典型的策略文件结构如下：\n\n\npolicies/v1/\n├── prompt.rego 提示注入防护\n├── context.rego 上下文安全\n├── tool.rego 工具调用安全\n├── memory.rego 记忆安全\n└── data/\n ├── policy_config.yaml 阈值、白名单、信任权重\n └── jailbreak_patterns.json 版本化越狱模式库\n\n\n三种决策结果\n\nACF-SDK的每一次策略评估都会产生三种明确的结果之一：\n\nALLOW（允许）：载荷干净，可以安全通过。\n\nSANITISE（净化）：载荷包含潜在威胁，但可以通过清理使其安全。系统会返回净化后的版本，并附加警告标记。\n\nBLOCK（阻断）：硬阻断，智能体不应继续使用此输入。这用于应对明确的恶意攻击。\n\n这种分级响应机制既保证了安全性，又避免了过度防御对用户体验的影响。\n\n当前状态与路线图\n\nACF-SDK目前处于积极开发阶段：\n\n第一阶段（已完成）：线协议和加密机制\n- 23个Go单元测试\n- 35个Python单元测试\n- HMAC/随机数加密实现\n\n第二阶段（进行中）：流水线阶段实现\n- 验证、规范化、扫描、聚合四个阶段的完整实现\n\n第三阶段（计划中）：OPA集成和Rego策略\n\n第四阶段（计划中）：OpenTelemetry可观测性和集成测试套件\n\nV2版本（延后）：有状态会话风险、额外钩子、TypeScript SDK\n\n实际部署与使用\n\nACF-SDK的部署非常简单。首先生成一个32字节的HMAC密钥：\n\nbash\nexport ACF_HMAC_KEY=$(python3 -c \"import secrets; print(secrets.token_hex(32))\")\n\n\n然后编译并启动Go侧车：\n\nbash\ncd sidecar && go build -o ../bin/acf-sidecar ./cmd/sidecar\n./bin/acf-sidecar\n\n\n在Python智能体中集成SDK：\n\npython\nfrom acf import Firewall, Decision\n\nfw = Firewall() 自动读取ACF_HMAC_KEY并连接到/tmp/acf.sock\n\nresult = fw.on_prompt(\"用户输入内容\")\nif result == Decision.BLOCK:\n 处理阻断情况\n pass\n\n\n结语：智能体安全的未来\n\nACF-SDK代表了LLM智能体安全领域的重要探索。它不仅仅是一个技术工具，更是一种安全思维的转变——从零信任的角度重新审视智能体系统的每一个输入通道。\n\n随着智能体能力的不断增强，它们将承担越来越关键的任务，从客户服务到代码生成，从数据分析到决策支持。在这样的背景下，ACF-SDK所倡导的分布式、策略驱动、低延迟的安全防护模式将成为智能体基础设施的标准配置。\n\n对于正在构建生产级LLM应用的开发者来说，ACF-SDK提供了一个值得认真考虑的安全选项。它的开源特性、框架无关设计和活跃的社区支持，使其成为智能体安全工具箱中的重要一员。