capfencelabs/capfence

# CapFence AI智能体是非确定性的。但现实世界的执行绝不能如此。

CapFence位于自主系统与特权执行目标（API、数据库、文件系统及网关）之间。它基于声明式的、基于能力的策略评估智能体的动作——允许、阻止或排队等待审批。 它充当一个**策略执行层和可验证的审计日志**，将IAM（身份与访问管理）和事务网关的控制能力带入自主智能体的运行时。 ``` Agent SDK ──> CapFence Runtime ──> Target System │ ├── [Allow] ──> Safe Execution ├── [Deny] ──> Blocked └── [Approval] ──> Temporary / Expiring Grant ``` ## 为何选择 CapFence 当自主智能体调用修改云基础设施、查询数据库或执行支付的工具时，**提示词并非安全边界。** 提示词可能被绕过、操纵，或在模型更新中发生偏移。 CapFence 引入了一个独立的执行边界： * **解耦的访问控制：** 策略逻辑与LLM隔离，并使用快速的能力引擎在本地进行评估。 * **默认安全失败：** 如果策略验证或审计日志记录失败，则该动作将被阻止。 * **防篡改审计追踪：** 每个决策都被提交到一个哈希链式的、可验证的审计追踪中，以防止事后篡改日志。 ## 示例场景 ### 防止未授权的资金转移 一个财务智能体试图转移超出其批准每日限额的公司资金。 CapFence 在执行前拦截该动作，并要求进行一个有时限的人工介入预授权。 ### 阻止破坏性Shell命令执行 一个自主运维智能体尝试运行： ``` rm -rf /var/lib/postgresql ``` CapFence 在原始CLI命令字符串执行前进行拦截，并使用本地确定性的拒绝策略将其阻止。 ### 沙箱化桌面智能体MCP工具 一个本地IDE智能体被仓库级别的提示词注入劫持，试图读取项目工作区之外的文件。 CapFence网关代理stdio JSON-RPC流，阻止主机路径遍历并返回标准协议错误。 ### 守护数据库写入与模式变更 一个生成SQL的分析智能体试图删除表或运行未索引的批量删除。 CapFence 在生成查询执行前进行解析，在DDL/DML操作进入连接池前将其阻止。 ### 强制执行多智能体信任与血缘 一个被入侵的公共路由智能体向特权计费智能体传播一个带有提示词注入的负载。 CapFence 跟踪完整的节点执行血缘，如果事务曾被未验证的节点接触过，则阻止其执行。 ## 10秒示例 ### 1. 定义能力策略 (`policies/ops.yaml`) 建立严格的、资源-动作-范围访问限制。未匹配的能力默认为拒绝。 ``` policy_name: Production Security Policy version: 2.0.0 allow: - filesystem.read.workspace require_approval: - payment.transfer.* - deployment.execute.production deny: - filesystem.delete.workspace - shell.execute.* ``` ### 2. 在运行时边界强制执行 初始化CapFence并在执行前评估动作： ``` from capfence import ActionRuntime, ActionEvent # 1. 直接从策略文件初始化运行时 runtime = ActionRuntime.from_policy("policies/ops.yaml") # 2. 将动作表示为受管事件 event = ActionEvent.create( actor="deployment-agent", action="execute", resource="deployment", environment="production" ) # 3. 执行决策 verdict = runtime.execute(event) if not verdict.authorized: raise PermissionError(f"Action blocked by CapFence: {verdict.reason}") ``` ## 策略模拟与事件重放 `ReplayEngine` 允许您对策略变更进行干运行，并重构过去的执行轨迹。 ``` from capfence import ReplayEngine # 针对新候选策略重放历史轨迹以验证安全性 engine = ReplayEngine() summary = engine.simulate_policy( trace_path="traces/incident_log.jsonl", policy_path="policies/ops_v2.yaml" ) print(f"Total Replayed: {summary.total_events} | Blocked: {summary.blocked}") ``` * **事件重构：** 准确评估在历史事件轨迹下本应发生什么。 * **策略验证：** 通过在实际部署前使用真实事务日志测试候选策略变更，来防止回归。 ## 命令行接口 CapFence 直接集成到标准的CI/CD和运维工作流中。 ### 授予临时预授权 向活动智能体授予临时、有时限的能力： ``` # 授予热修复代理10分钟推送访问权限 capfence grant --actor hotfix-agent --capability github.push.main --duration 600 ``` ### 干运行轨迹模拟 使用候选策略重放执行日志： ``` capfence replay traces/agent_trace.jsonl --policy policies/ops_v2.yaml ``` ### 验证审计日志完整性 验证审计数据库条目是否未被修改： ``` capfence verify --audit-log audit.db ``` ### 代码库扫描 扫描Python项目以确保所有工具均由CapFence进行门控： ``` capfence check ./src --fail-on-ungated ``` ## 模型上下文协议 (MCP) 治理 CapFence 原生实现了**模型上下文协议**的执行控制，提供了一个透明的stdio代理网关和一个进程内会话适配器，以便在工具调用到底层系统之前进行拦截和授权。 ### 1. 透明代理网关 (`MCPGatewayServer`) 在任何MCP客户端（如Claude Desktop或Cursor）与上游工具服务器进程之间运行一个安全的stdio代理。如果工具调用违反了能力策略，网关将拦截该请求并返回一个标准的JSON-RPC错误。 ``` from capfence import MCPGatewayServer # 初始化包装任意上游服务器命令的代理 gateway = MCPGatewayServer( upstream_command=["python", "-m", "mcp_server_filesystem", "/tmp"], policy_path="policies/ops.yaml", agent_id="mcp-file-agent", ) # 启动标准输入输出代理（动态阻断并拦截工具调用） gateway.run() ``` ### 2. 进程内客户端会话适配器 (`CapFenceMCPSession`) 在进程内包装任何活动的 `mcp.ClientSession` 实例。CapFence 针对活动的能力运行时评估每个 `call_tool` 请求。如果被拒绝，它会抛出 `AgentActionBlocked` 异常，而不会将其转发给服务器。 ``` from capfence import CapFenceMCPSession # 动态包装任意活跃的MCP客户端会话 gated_session = CapFenceMCPSession( underlying_session=mcp_client_session, policy_path="policies/ops.yaml", agent_id="mcp-agent-1" ) # 调用在执行前被无缝拦截并审计 response = await gated_session.call_tool("filesystem_write", {"path": "/tmp/test", "content": "data"}) ``` ## 运营范围 CapFence 强制执行运行时策略边界。它**不**替代： * **进程沙箱：** 始终在隔离的运行时（如Docker、gVisor）中运行智能体。 * **最小权限基础设施：** 云IAM策略和数据库访问凭证必须保持严格锁定。 * **网络隔离：** 限制网络出口以防止未授权的公共连接。 ## 项目信息 * **文档：** https://capfencelabs.github.io/capfence/ * **PyPI：** https://pypi.org/project/capfence/ * **仓库：** https://github.com/capfencelabs/capfence MIT 许可证 | 由 [CapFence Labs](https://github.com/capfencelabs) 构建

标签：AI代理, AI安全, Chat Copilot, Lerna, Streamlit, 代理安全, 可验证审计, 哈希链验证, 声明性策略, 安全防护, 审计日志, 工具包装, 强制执行层, 故障关闭, 文档结构分析, 无LLM调用, 时序数据库, 本地执行, 知识图谱, 确定性执行, 离线工作, 策略执行, 能力策略, 能力管理, 自主系统, 访问控制, 运行时保护, 运行时治理, 逆向工具, 零云依赖