c2siorg/acf-sdk

# ACF-SDK — 代理认知防火墙 [](LICENSE) [](https://github.com/c2siorg/acf-sdk/actions/workflows/ci.yml) LLM 代理的零信任安全层。在代理摄入输入的每个点强制执行策略驱动的验证——不仅仅是入口处。 ## 问题 LLM 代理没有单一的输入边界。它们从用户、RAG 管道、工具输出和内存存储中获取数据——每个都是潜在的攻击面。在入口处进行单一的边界检查会遗漏所有后续到达的内容。 ACF-SDK 将执行分布在整个代理生命周期中： | 位置 | 威胁 | |---|---| | 用户提示到达 | 直接提示注入——覆盖系统指令 | | RAG 块注入 | 间接注入——检索文档中的恶意指令 | | 工具执行前 | 工具滥用——不安全的工具或恶意参数 | | 内存读写前 | 内存污染——持久代理状态中的恶意值 | ## 工作原理  两个区域由严格的操作系统进程边界分隔： - **PEP** — 代理进程内的轻量级 SDK。对有效载荷进行签名并通过 IPC 分发。 - **PDP** — 隔离的 Go 边车。所有策略评估都在这里进行。代理无法访问其内部。 边车通过四阶段管道运行每个有效载荷——验证、规范化、扫描、聚合——然后评估 OPA (Rego) 策略以产生结构化决策。 每个决策都是以下三种结果之一： | 决策 | 含义 | |---|---| | `ALLOW` | 有效载荷是干净的——放行 | | `SANITISE` | 有效载荷包含威胁——返回带有警告标记的清理版本 | | `BLOCK` | 硬阻止——代理不得继续处理此输入 | 执行延迟：**典型 4–8ms，最坏情况约 10ms。**可观察性跨度异步发出，从不触及执行路径。 ## 快速开始 (Python) ```python from acf import Firewall, Decision firewall = Firewall() # 连接到 /tmp/acf.sock 的边车 # 在消息入口处 result = firewall.on_prompt(user_message) if result.decision == Decision.BLOCK: raise ValueError("输入被防火墙阻止") if result.decision == Decision.SANITISE: user_message = result.sanitised # 使用清理后的版本 # RAG 注入前 chunks = firewall.on_context(retrieved_docs) safe_chunks = [c.sanitised for c in chunks if c.decision != Decision.BLOCK] # 工具执行前 result = firewall.on_tool_call(tool_name, tool_params) if result.decision == Decision.BLOCK: raise ToolException("工具调用被防火墙阻止") # 内存写入前 result = firewall.on_memory(key, value, op="write") if result.decision != Decision.ALLOW: raise MemoryException("内存写入被防火墙阻止") ``` ### LangGraph 适配器 ```python from acf.adapters.langgraph import FirewallNode from langgraph.graph import StateGraph graph = StateGraph(AgentState) graph.add_node("firewall", FirewallNode(firewall)) graph.add_node("agent", your_agent_node) graph.add_edge("firewall", "agent") ## 架构 ### 缝合一 — 钩子注册表  钩子在启动时自我注册。管道只调用已注册的内容。添加新钩子（v2: `on_tool_result`、`on_outbound`、`on_subagent`）是纯增量的——管道、IPC 层和边车核心不会改变。 ### 风险上下文对象  单个类型化有效载荷流经每个管道阶段。模式在 v1 和 v2 之间固定——`state` 字段在 v1 中为空，在 v2 中由 TTL 会话存储填充。策略文件在两个版本中保持不变。 ### 边车管道 ``` validate → normalise → scan → aggregate → OPA policy engine → executor ``` | 阶段 | 功能 | |---|---| | **验证** | HMAC 验证、nonce 重放检查、模式验证 | | **规范化** | URL/Base64/hex 解码、NFKC unicode、零宽字符剥离、leet speak 清理 | | **扫描** | Aho-Corasick 词法扫描、允许列表检查、完整性验证 | | **聚合** | 将信号组合为 0.0–1.0 的风险评分，并带有来源信任权重 | | **策略引擎** | OPA (Rego) 按钩子类型评估规则，返回结构化决策 | | **执行器** | 对 SANITISE 决策执行 OPA 声明的字符串转换 | 在任何阶段检测到硬信号时短路到 BLOCK。 ## 策略 策略是 Rego 文件，可在不重启边车的情况下热重载。逻辑和数据分离，因此模式库更新无需触及决策规则。 ``` policies/v1/ ├── prompt.rego instruction override · role escalation · jailbreak ├── context.rego source trust · embedded instruction · structural anomaly ├── tool.rego allowlist · shell metachar · path traversal · network ├── memory.rego HMAC stamp/verify · write scan · provenance └── data/ ├── policy_config.yaml thresholds · allowlists · trust weights └── jailbreak_patterns.json versioned pattern library ``` 使用 `make opa-test` 测试策略——使用 `opa test` 运行完整的 Rego 测试套件。 ## 入门 ### 前置条件 - Go 1.22+ - Python 3.10+ - [OPA](https://www.openpolicyagent.org/docs/latest/#running-opa) （用于策略测试，阶段 3+） ### 1. 生成 HMAC 密钥 ``` export ACF_HMAC_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))") ``` 保留此值——边车和 SDK 必须使用相同的密钥。 ### 2. 构建并运行边车 ``` cd sidecar && go build -o ../bin/acf-sidecar ./cmd/sidecar ./bin/acf-sidecar # sidecar: pipeline ready (mode=strict, block_threshold=0.85) # sidecar: listening on /tmp/acf.sock ``` 或使用 `make`： ``` make build && ./bin/acf-sidecar ``` ### 3. 安装 Python SDK ``` pip install -e sdk/python ``` ### 4. 发送您的第一个请求 ``` from acf import Firewall, Decision fw = Firewall() # reads ACF_HMAC_KEY and connects to /tmp/acf.sock result = fw.on_prompt("hello world") assert result == Decision.ALLOW print("Round-trip OK:", result) ``` ### 5. 运行测试套件 ``` # Go unit tests cd sidecar && go test ./... -v # Python unit tests cd sdk/python && python -m pytest -v # Or both via make (from repo root) make test # Go tests make sdk-test-python # Python tests ``` ### Docker（边车 + 可选 OTel 收集器） ``` # Set your key in the environment first, then: docker compose up -d # With observability (OTel collector): docker compose --profile observability up -d ``` ## 项目结构 ``` acf-sdk/ ├── sidecar/ Go enforcement kernel (PDP) ├── sdk/ │ ├── python/ Python SDK v1 — zero external dependencies │ └── typescript/ TypeScript SDK v2 — deferred until v1 is stable ├── policies/v1/ Rego policies + data ├── tests/integration/ 33-payload adversarial test suite ├── config/ Sidecar configuration └── docs/ Architecture and policy authoring guides ``` ## 路线图 | 阶段 | 目标 | 状态 | |---|---|---| | 1 | 有线协议 + HMAC/nonce 加密 | **完成** — 23 个 Go 测试，35 个 Python 测试 | | 2 | 管道阶段（验证/规范化/扫描/聚合） | **完成** — 49 个 Go 测试 | | 3 | OPA 集成 + Rego 策略 | 下一个 | | 4 | OTel 可观察性 + 集成测试套件 | 待定 | | v2 | 有状态会话风险、额外钩子、TypeScript SDK | 推迟 | ## 设计原则 完整的设计理由请参阅 [PHILOSOPHY.md](

标签：Agentic AI, AI安全, AI对抗性攻击, API密钥检测, Chat Copilot, CISA项目, EVTX分析, Go语言, IPC通信, OPA, RAG安全, Red Canary, Rego策略, SDK开发, Sidecar架构, 上下文安全, 代理安全, 内存污染防护, 域名收集, 大语言模型安全, 威胁防护, 安全扫描, 安全控制层, 工具滥用防护, 恶意指令检测, 提示注入防护, 日志审计, 时序注入, 机密管理, 程序破解, 策略引擎, 结构化提示词, 网络安全挑战, 认知防火墙, 请求拦截, 输入验证, 逆向工具, 零信任安全, 靶场