基于零信任的AI智能体安全框架Peon：从架构层面强制LLM权限控制

1. 项目概述：一个对AI说“不”的零信任框架

如果你最近在折腾AI智能体（Agent），尤其是那些能调用外部工具、执行脚本的“自动化助手”，那你大概率和我一样，经历过那种提心吊胆的感觉。你给大模型（LLM）开了一个bash终端，祈祷它别一时兴起把你的/home目录给删了，或者更糟，执行了什么不该执行的命令。市面上的主流框架，比如LangChain、AutoGPT，它们的哲学往往是“赋能”——给LLM尽可能多的工具和权限，然后靠提示词（Prompt）去约束它。这就像给一个好奇心旺盛的孩子一把万能钥匙，然后只靠口头叮嘱“别去地下室”，心里总是不踏实。

Peon的出现，彻底扭转了这个思路。它的核心设计哲学不是“LLM能做什么”，而是“LLM绝对不能做什么”。这是一个从架构层面，而非提示词层面，强制执行“零信任”（Zero-Trust）安全模型的AI智能体框架。简单来说，它给LLM套上了一条物理的、不可篡改的“缰绳”。无论LLM在推理时多么“聪明”，试图如何绕过，它都无法突破由Peon在Rust层构建的权限围墙。这个项目特别适合那些需要在生产环境中部署AI智能体的开发者、对安全有苛刻要求的企业内部自动化工具构建者，以及任何不想因为AI的“自由发挥”而熬夜救火的工程师。

2. 核心安全哲学：从“防御性提示”到“架构级强制”

在深入代码之前，我们必须先理解Peon赖以立身的核心理念。传统的AI智能体安全，我称之为“防御性提示工程”。我们在系统提示词里写满“你绝对不能…”、“未经允许禁止…”，并期望LLM会遵守。这种方法存在几个根本性缺陷：

1. 提示词注入（Prompt Injection）：用户输入可能覆盖或混淆系统指令。
2. LLM的不可预测性：即使是最先进的模型，也可能产生“幻觉”，误解指令或进行非预期的工具调用。
3. 权限边界模糊：提示词定义的“允许”和“禁止”是语义层面的，缺乏操作系统级别的精确控制。

Peon采用了截然不同的“架构级强制”安全模型。它将智能体的每一个潜在危险操作（如文件执行、系统调用）的权限检查，从LLM的文本推理世界中剥离出来，下沉到由Rust编写的、确定性的运行时环境中。LLM的角色从“拥有权限的执行者”转变为“提出建议的规划者”。最终能否执行，由一个独立的、LLM无法触及的安全引擎（Casbin）说了算。

这种设计带来了一个关键特性：权限与用户身份（UID）在物理层面绑定，而非逻辑层面。在Peon中，代表用户的UID（如3856588331）是一个在Rust结构体（RequestContext）中传递的硬编码值。它从智能体调用的入口点就被注入，并贯穿整个工具调用链。LLM在它的文本世界里根本“看不到”这个UID，更无法伪造或覆盖它。权限检查发生在LLM输出工具调用参数之后、真正执行操作系统命令之前的两层独立验证中，这构成了深度防御。

3. 架构深度解析：四层防御矩阵如何工作

Peon的安全不是单点突破，而是一个环环相扣的矩阵。下面我们拆解这张安全网中的每一层，看看它们是如何协同工作的。

3.1 第一层：基于技能（Skill）的动态白名单

这是权限收缩的第一道闸门。在Peon中，LLM不能随心所欲地调用任何系统命令或脚本。它能操作的“工具”被封装在名为“技能”（Skill）的模块中。一个技能本质上是一个文件夹，包含一个SKILL.md文件（描述和路径声明）和实际的脚本或资源。

skills/ └── roll-dice/ ├── SKILL.md # 技能定义文件 └── scripts/ └── roll.sh # 实际可执行脚本

当LLM调用read_skill(“roll-dice”)工具时，Peon的核心引擎（peon-core）会做以下几件事：

1. 解析SKILL.md，提取其中声明的所有文件路径（如./scripts/roll.sh）。
2. 将这些相对路径解析（canonicalize()）为绝对路径。
3. 关键一步：将这些绝对路径提交给安全执行器（Enforcer）进行初次校验。
4. 只有通过校验的路径，才会被加入当前会话的“可执行白名单”。

注意：这个过程是动态的、按需的。LLM在读取技能之前，根本不知道roll.sh这个文件的存在，更不知道它的完整路径。因此，它无法在提示词中“发明”一个不存在的路径去尝试调用。这从源头上杜绝了路径遍历（Path Traversal）等攻击。

3.2 第二层与第三层：文件ACL与用户ACL（Casbin）

白名单决定了“什么能被执行”，而访问控制列表（ACL）决定了“谁能执行它”。Peon使用Casbin——一个强大的、支持多种模型的访问控制库——来同时管理文件和用户权限。

• 文件级ACL (file_permissions.txt)：定义了系统范围内所有路径的默认规则。这是一个全局的、与用户无关的许可/禁止清单。

  # 格式: 操作, 路径模式, 效果 x, ./skills/* # 允许执行skills目录下的任何文件 !x, /bin/rm # 明确禁止执行rm命令，无论用户是谁 r, ./data/*.json # 允许读取data目录下的json文件 !r, ./secrets/* # 禁止读取secrets目录下的任何文件

  这层规则在技能扫描阶段（第一层）就会生效。如果一个路径在file_permissions.txt中被标记为!x（禁止执行），那么它在扫描时就会被过滤掉，根本不会进入白名单。

• 用户级ACL (user_permissions.csv)：定义了基于用户或角色的权限。这是实现RBAC（基于角色的访问控制）的关键。

  p, *, *, *, allow # 策略：主体，资源，操作，效果（开发模式-允许所有人） p, 3856588331, *, execute, allow # 策略：仅用户3856588331允许执行任何资源 p, admin_role, *, read, allow # 策略：admin_role角色允许读任何资源 g, alice, admin_role # 分组：alice属于admin_role角色

  Casbin引擎会结合当前的用户UID（从RequestContext中获取）和请求的操作（如execute），查询这些策略，决定是允许还是拒绝。

3.3 第四层：不可伪造的请求上下文（RequestContext）

这是将用户身份与LLM推理过程物理隔离的关键。在许多框架中，用户身份可能以变量的形式存在于LLM的上下文窗口中，或者存储在任务本地存储（Thread-local Storage）中。理论上，这些都可能被精心构造的提示词所影响或覆盖。

在Peon中，RequestContext是一个Rust的结构体实例，它在智能体运行伊始就被创建，并作为不可变引用传递到每一个工具调用函数中。这个结构体包含了uid等字段。由于Rust的所有权和生命周期保证，这个上下文在内存中是独立且受保护的。LLM作为运行在虚拟机或远程API中的代码，没有任何机制可以访问或修改这个Rust结构体内的数据。这就确保了权限检查所依赖的“用户身份”是绝对可信的。

四层联动流程：

1. 用户请求：用户alice发送消息“查看服务器状态”。
2. 上下文注入：Peon创建RequestContext { uid: “alice”, … }，启动智能体。
3. LLM规划：LLM决定调用read_skill(“server-status”)。
4. 技能扫描与白名单：peon-core读取技能，发现路径./scripts/status.sh。首先用文件ACL检查该路径是否全局可执行（是），然后用用户ACL检查alice是否有execute权限（是）。通过后，将该路径加入会话白名单。
5. LLM执行：LLM调用execute_script(“./scripts/status.sh”)。
6. 最终执行检查：工具函数收到调用，再次使用当前的RequestContext和用户ACL，验证alice对./scripts/status.sh的execute权限（再次检查）。同时，验证该路径是否在本次会话的白名单内（防止LLM调用一个它没读过的技能里的脚本）。全部通过后，才使用std::process::Command执行脚本。
7. 结果返回：脚本输出返回给LLM，LLM组织语言回复给用户alice。

如果第4步或第6步中任何一次检查失败，操作会立即被终止，并返回一个权限错误给LLM，LLM只能如实告知用户“权限不足”。整个过程中，LLM就像一个拿着有限工具清单并需要层层审批的办事员，而不是一个拥有根权限的系统管理员。

4. 从零开始构建一个安全的问答技能

理解了理论，我们动手实现一个实际场景：一个内部帮助文档问答技能。该技能允许授权用户询问公司内部工具的使用方法，它会读取一个本地的Markdown知识库并返回答案。我们要确保：1）只有特定部门的员工能使用；2）智能体只能读取指定的文档目录，绝不能写入或执行其他命令。

4.1 环境搭建与项目初始化

首先，确保你的系统已安装Rust工具链（rustc和cargo）。然后创建一个新项目并添加依赖：

cargo new peon-helpdesk-agent cd peon-helpdesk-agent

编辑Cargo.toml，添加peon-core和peon-runtime依赖，以及我们可能用到的其他库。为了演示，我们假设使用OpenAI的模型。

[dependencies] peon-core = "0.1" # 请检查crates.io使用最新版本 peon-runtime = "0.1" tokio = { version = "1", features = ["full"] } dotenvy = "0.15" # 用于加载.env文件 serde = { version = "1", features = ["derive"] } anyhow = "1.0" # 简化错误处理

接下来，创建项目根目录下的.env文件，配置模型和密钥：

# .env PROVIDER=openai MODEL=gpt-4o-mini # 或 gpt-3.5-turbo 控制成本 API_KEY=sk-your-openai-api-key-here # Peon 核心配置 PEON_SKILLS_DIR=./skills PEON_FILE_PERMISSIONS=./config/file_permissions.txt PEON_USER_PERMISSIONS=./config/user_permissions.csv

4.2 定义安全策略：文件与用户权限

在项目根目录创建config文件夹，并放置两个关键的安全配置文件。这是Peon零信任模型的基石，如果缺失，框架会直接报错，避免任何默认的宽松权限。

1. 文件权限 (config/file_permissions.txt):这个文件定义了智能体在文件系统层面能做什么。我们严格限制为只读（r）我们指定的知识库目录。

# 操作, 路径模式, 效果 # 允许读取知识库目录下的所有.md文件 r, ./knowledge_base/*.md # 禁止执行任何命令（这是一个问答机器人，不需要执行） !x, * # 禁止写入任何文件 !w, * # 禁止删除任何文件 !d, *

2. 用户权限 (config/user_permissions.csv):这个文件基于Casbin的csv模型，定义了哪个用户能进行什么操作。假设我们有两个用户：alice（IT支持部）和bob（市场部），以及一个it_support角色。

p, it_support, knowledge_base, read, allow # 策略：it_support角色可以读knowledge_base资源 p, bob, knowledge_base, read, deny # 策略：bob拒绝读取knowledge_base g, alice, it_support # 分组：alice属于it_support角色

这个配置意味着：

• alice继承了it_support角色的权限，因此她可以readknowledge_base。
• bob被明确拒绝读取knowledge_base，即使他属于某个角色，这条拒绝策略也会优先。

4.3 创建技能与知识库

按照Peon的约定，在项目根目录创建skills文件夹，并在其中创建我们的helpdesk技能。

技能结构：

skills/ └── helpdesk/ ├── SKILL.md └── knowledge_base/ # 技能私有的知识库，路径在SKILL.md中声明 ├── vpn_guide.md ├── email_setup.md └── printer_troubleshooting.md

技能定义 (skills/helpdesk/SKILL.md):这个文件是LLM了解此技能能力的“说明书”，同时也是Peon扫描可访问路径的依据。

--- name: helpdesk description: 回答关于内部IT系统、软件使用和常见问题。通过读取内部知识库Markdown文件来获取信息。 --- 本技能用于提供内部IT支持。 你可以读取 `./knowledge_base/` 目录下的Markdown文件来获取最新、准确的信息。 例如，当用户询问“如何连接公司VPN”时，你应该尝试读取 `./knowledge_base/vpn_guide.md` 文件，从中提取步骤并回答用户。 可用文件： - `./knowledge_base/vpn_guide.md`: 公司VPN连接配置指南。 - `./knowledge_base/email_setup.md`: 新版邮箱客户端设置教程。 - `./knowledge_base/printer_troubleshooting.md`: 网络打印机常见故障排查。 注意：你只能读取这些文件，不能修改、删除或执行它们。如果用户的问题超出知识库范围，请如实告知。

知识库内容示例 (skills/helpdesk/knowledge_base/vpn_guide.md):

# 公司VPN连接指南 (2024年更新) ## 适用平台 - Windows 11 / 10 - macOS Sonoma 及以上 - Linux (Ubuntu 22.04) ## 连接步骤 1. 从内部软件门户下载并安装“GlobalProtect”客户端。 2. 启动客户端，在门户地址栏输入：`vpn.company.com`。 3. 使用你的公司邮箱和密码登录。 4. 首次登录需通过多因素认证(MFA)应用确认。 5. 连接成功后，右下角（Windows）或菜单栏（macOS）会显示图标。 ## 常见问题 - **连接失败**：检查是否在公司网络内，或联系IT部门检查账户状态。 - **MFA不通过**：确保手机时间与网络时间同步。 - **无法访问内部网站**：请确认已连接到正确的VPN策略组“Internal-All”。

4.4 编写智能体主程序

现在，我们将所有部分组合起来。在src/main.rs中，编写启动智能体并处理用户查询的代码。

use anyhow::Result; use dotenvy::dotenv; use peon_core::{PeonAgentBuilder, RequestContext}; use peon_runtime::providers::openai::OpenAIConfig; use std::env; #[tokio::main] async fn main() -> Result<()> { // 1. 加载环境变量 dotenv().ok(); // 2. 构建智能体 // `default_prompt()` 会加载一个基础的系统提示，你也可以用 `.custom_prompt()` 完全自定义 let agent = PeonAgentBuilder::new() .await? // 异步初始化，会加载权限配置文件 .default_prompt() .build(); // 3. 模拟两个不同用户的查询 let queries = vec![ ("alice", "如何设置公司VPN？"), ("bob", "如何设置公司VPN？"), ]; for (uid, query) in queries { println!("\n=== 用户 [{}] 的查询 ===", uid); println!("问: {}", query); // 4. 创建不可伪造的请求上下文 let ctx = RequestContext::new(uid.to_string()); // 5. 运行智能体，上下文被物理传递 match agent.prompt(query, &ctx).await { Ok(response) => println!("答: {}", response), Err(e) => eprintln!("错误: {}", e), // 例如，bob会在这里触发权限错误 } } Ok(()) }

4.5 运行与观察深度防御

运行程序：cargo run。观察控制台输出，你会看到Peon安全矩阵在行动。

对于用户alice(uid=”alice”):

1. LLM接收到问题，决定使用helpdesk技能。
2. 调用read_skill(“helpdesk”)。peon-core扫描技能，发现路径./knowledge_base/vpn_guide.md。
3. 安全检查：文件ACL允许读取./knowledge_base/*.md；用户ACL中，alice属于it_support角色，该角色允许readknowledge_base。路径通过校验，加入白名单。
4. LLM调用read_file(“./knowledge_base/vpn_guide.md”)。
5. 最终检查：路径在白名单中，且用户alice有read权限。执行读取。
6. LLM根据文件内容生成答案返回。

对于用户bob(uid=”bob”):

1. 前几步相同，LLM同样决定读取vpn_guide.md。
2. 在read_skill的扫描阶段或read_file的最终检查阶段，用户ACL检查会失败。因为策略p, bob, knowledge_base, read, deny明确拒绝了bob的读取权限。
3. 操作被peon-core的Casbin执行器拦截，工具调用返回权限错误。
4. LLM收到错误，只能回复用户：“我无法读取该文件，权限被拒绝。”

实操心得：在开发调试时，建议将日志级别设为DEBUG（通过环境变量RUST_LOG=peon_core=debug,peon_runtime=debug）。你可以清晰地看到“扫描路径”、“检查策略”、“加入白名单”、“违反策略”等每一步日志，这对于理解权限流和排查配置错误至关重要。生产环境中则应调回INFO或WARN级别。

5. 高级配置与生产环境部署要点

将Peon用于原型验证和投入生产环境是两回事。以下是一些关键的生产级考量。

5.1 权限策略的管理与版本控制

手动编辑csv和txt文件在用户量小的时候可行，但规模扩大后会成为噩梦。建议：

• 策略即代码：编写一个简单的Rust脚本或使用构建脚本，从更易维护的源（如YAML、JSON或数据库）生成最终的file_permissions.txt和user_permissions.csv文件。例如：

  # permissions.yaml file_rules: - action: read pattern: "./skills/*/knowledge_base/*.md" effect: allow - action: execute pattern: "/bin/*" effect: deny user_roles: it_support: - "read:knowledge_base" guest: - "deny:*" user_assignments: alice: it_support bob: guest

• 与现有系统集成：Casbin支持从数据库适配器加载策略。你可以修改peon-core的初始化部分（或提交PR），使其支持从PostgreSQL、MySQL等数据库加载用户ACL，实现动态权限更新，无需重启服务。
• 版本控制：将skills/目录和权限配置文件一同纳入Git管理。任何技能更新或权限变更都应通过Pull Request流程，进行代码审查和自动化测试。

5.2 技能设计的黄金法则

技能是Peon安全模型中的“可信计算基”。设计不良的技能会扩大攻击面。

1. 最小路径声明：在SKILL.md的---分隔符内或通过清晰注释，只声明该技能运行所必需的最少路径。不要使用模糊的通配符如./scripts/*，而应明确列出./scripts/roll.sh。
2. 输入验证与净化：即使路径在白名单内，脚本自身也应对参数进行严格验证。例如，上面的roll.sh应该检查参数是否为数字且在合理范围内（如1-1000）。Peon提供了安全的参数传递，但脚本内部的逻辑安全仍需开发者保证。
3. 无状态与幂等性：尽可能将技能设计为无状态的、幂等的操作。避免技能执行会修改系统状态或产生副作用的操作。如果必须修改，应通过专门的、审计日志完备的API进行，而不是直接执行shell命令。
4. 技能隔离：考虑使用Docker容器或更轻量的沙箱（如gVisor、Firecracker）来运行技能脚本。Peon的核心库可以与此类沙箱集成，在允许执行脚本时，实质上是启动一个隔离的容器。这提供了另一层强大的隔离。

5.3 性能、扩展性与监控

• 连接池与预热：如果你使用远程LLM API（如OpenAI），确保peon-runtime中的HTTP客户端使用了连接池。对于生产服务，可以在启动时预热智能体，提前加载必要的技能和权限模型，避免第一个请求的延迟。
• 分布式会话：默认情况下，会话白名单是内存中的、与智能体实例绑定的。在分布式部署中（多实例），你需要一个共享存储（如Redis）来维护会话状态，或者确保用户请求总是路由到同一个实例（Sticky Session）。
• 全面的审计日志：Peon的核心库已经记录了关键的安全事件（如权限违规）。你需要将这些日志与你的集中式日志系统（如ELK、Loki）集成。务必记录：UID、请求内容、尝试的工具调用、路径、最终决策（允许/拒绝）、时间戳。这对于安全审计和事后追溯至关重要。
• 健康检查与指标：为你的Peon服务添加健康检查端点（如/health），检查权限文件是否存在、Casbin引擎是否加载成功、LLM API连接是否正常。同时，暴露Prometheus指标，如请求次数、工具调用次数、权限拒绝次数、平均响应时间等。

6. 常见陷阱与排查指南

即使理解了原理，在实际集成中仍会遇到一些问题。以下是我在实战中总结的常见坑点。

6.1 权限配置错误导致“全拒”或“全放”

• 症状：所有用户的操作都被拒绝，或者所有用户都能执行任何操作。
• 排查：
  1. 检查文件路径：PEON_FILE_PERMISSIONS和PEON_USER_PERMISSIONS环境变量指向的文件路径是否正确？文件是否可读？Peon启动失败时会panic，这是好事。
  2. 理解Casbin模型：user_permissions.csv遵循特定的csv模型。第一行通常是模型定义，如p, sub, obj, act, eft。确保你的策略行（p, ...）和分组行（g, ...）格式正确。一个常见的错误是混淆了allow和deny的优先级。Casbin的rbac模型通常遵循“拒绝优先”或“允许优先”，具体取决于模型定义。仔细阅读peon-core中集成的Casbin模型配置。
  3. 使用casbin命令行工具：你可以单独安装casbin命令行工具，离线测试你的策略文件，验证特定(sub, obj, act)是否会返回预期的allow/deny。

6.2 技能路径解析失败

• 症状：read_skill成功，但后续execute_script或read_file提示路径不在白名单。
• 排查：
  1. 绝对路径 vs 相对路径：Peon在扫描技能时会使用std::fs::canonicalize将相对路径转为绝对路径。确保SKILL.md中声明的路径相对于技能目录本身是正确的。在SKILL.md中使用./scripts/roll.sh比scripts/roll.sh更明确。
  2. 查看调试日志：设置RUST_LOG=peon_core=debug。在日志中搜索Added to execute whitelist或not added to any whitelist。这里会显示扫描到的路径和解析后的绝对路径。对比这个绝对路径和你期望的是否一致。
  3. 文件系统权限：确保运行Peon进程的用户有权限读取技能目录及其下的文件。Peon的权限检查是逻辑上的，操作系统级的文件读权限是前提。

6.3 LLM“不听话”，不调用技能

• 症状：用户的问题明明应该触发某个技能，但LLM选择自行回答，或调用错误的工具。
• 排查：
  1. 优化系统提示词：Peon的default_prompt()提供了一个基础模板，但你可能需要强化。在提示词中清晰列出可用的技能名称和描述，并强制要求LLM在回答特定类型问题前必须先调用read_skill。例如：“当用户询问IT相关问题时，你必须首先使用read_skill工具查阅helpdesk技能。”
  2. 技能描述质量：SKILL.md的description字段至关重要。它应该清晰、简洁，并包含触发关键词。LLM根据描述来决定是否使用该技能。
  3. 工具定义清晰度：Peon会自动将技能暴露为工具。确保工具的名称和参数描述对LLM友好。你可以通过PeonAgentBuilder的方法自定义工具的描述，使其更符合LLM的理解习惯。

6.4 性能与超时问题

• 症状：智能体响应缓慢，或工具调用超时。
• 排查：
  1. 网络延迟：如果使用远程LLM API，网络是主要瓶颈。考虑部署在离API服务区更近的云区域，或使用具有更好网络链路的主机。
  2. 脚本执行超时：Peon执行外部脚本时，默认可能有超时设置。如果技能脚本执行时间过长，会导致整个智能体调用失败。对于长时任务，应考虑将其异步化，通过消息队列触发，并通过另一个接口查询结果。
  3. 会话内存增长：Peon的会话可能会积累上下文。对于长时间运行的聊天机器人，需要定期重置会话或实现一个基于Token数量的上下文窗口滑动机制，这通常在peon-runtime的配置中设置。

7. 对比与选型：何时选择Peon？

Peon并非适用于所有场景。理解它的定位能帮助你做出正确选择。

• vs LangChain / LlamaIndex：这些是功能极其丰富的“全家桶”框架，提供了从数据加载、向量存储到链式调用的一切。它们的权限控制往往通过“工具”层面的参数验证和提示词来实现。选择Peon，如果你需要的是军事级、架构层面的操作安全，并且愿意为了安全接受更陡峭的学习曲线和更“固执”的框架设计。Peon是一个专门的安全层，理论上可以与其他框架的某些部分结合，但其理念是深度集成的。
• vs AutoGPT / CrewAI：这些框架专注于自主智能体，强调目标的分解和循环执行。它们的安全考虑通常更少。如果你的智能体需要高度的自主性，但同时必须运行在严格受控的环境（如企业内部网、生产服务器）中，Peon是目前为数不多的、将“零信任”作为首要设计目标的框架。
• 自研安全层：你可以自己在现有框架上包裹一层权限检查。但Peon的价值在于它提供了一个经过深思熟虑、多层防御、且与Rust语言特性（内存安全、无畏并发）深度结合的安全实现。使用Peon相当于直接引入了一个成熟的安全架构，避免了从头设计可能产生的逻辑漏洞。

我个人在将内部运维助手从基于提示词约束迁移到Peon后，最深刻的体会是“睡得安稳了”。以前总会担心某次复杂的用户查询会让模型“灵机一动”尝试危险操作。现在，我知道无论模型输出什么，那堵由Rust代码和Casbin策略构成的墙都会在那里。这种确定性，对于生产系统而言，是无价的。它的设计迫使你以“最小权限”的原则去思考每一个技能，这本身就是一次良好的安全实践教育。如果你正在构建一个需要对底层系统进行受控访问的AI应用，Peon提供的这条“缰绳”，值得你花时间握在手中。