yasindce1998/NeuronTrace

使用 eBPF/LSM 对 AI agent 进行内核级的行为控制。

NeuronTrace 在内核级别对 AI agent 进程实施**默认拒绝**策略。与应用层沙箱不同，agent 无法绕过执行限制——内核会在 syscall 执行前将其阻断。 ## 核心特性 - **BPF-LSM 钩子**：在内核级别拦截 exec、file open、unlink、rename、connect、ptrace 和 task_kill - **默认拒绝**：没有策略规则 = 拦截。agent 初始权限为零 - **代际标记**：当 agent 启动新任务时，使过期的权限失效——防止跨代际的数据泄露 - **Cgroup 作用域**：执行限制仅针对 agent 进程树，而不影响整个系统 - **路径/glob 过滤**：通过 glob 模式实现细粒度规则（例如允许 `/usr/bin/git`，拦截其他所有操作） - **自我保护**：BPF 程序被 pin 住以在用户空间崩溃中存活；`task_kill` 钩子防止 agent 终止控制器 - **仅审计模式**：在不拦截的情况下观察 agent 行为——在正式实施前提供安全的观察体验 - **入门策略**：为 Claude Code、Codex 和通用 agent 提供预构建的 YAML 策略 ## 环境要求 - Linux kernel 5.15+ 且启用了 BTF - 启用 BPF-LSM（`CONFIG_BPF_LSM=y`，且启动参数中包含 `lsm=bpf`） - Rust nightly（用于编译 eBPF） - Root 权限（用于加载 BPF 程序） ## 快速开始 ``` # 构建一切 cargo xtask build --release # 查看 enforcement 实际运行 — 一个 command，处理一切 sudo ./scripts/demo.sh ``` 该演示会创建一个 cgroup，启动 NeuronTrace，运行会被内核拦截的测试命令，展示违规日志，最后进行清理。无需开启第二个终端。 **[完整的快速开始指南 →](docs/quickstart.md)** ### 手动使用 ``` # 使用特定的 policy 运行 sudo ./target/release/neurontrace run \ --policy policies/claude-code.yaml \ --cgroup /sys/fs/cgroup/neurontrace # 仅观察不阻断（audit-only 模式） sudo ./target/release/neurontrace run \ --policy policies/claude-code.yaml \ --cgroup /sys/fs/cgroup/neurontrace \ --audit-only # 检查 enforcement 状态 sudo ./target/release/neurontrace status # 在不加载 BPF 的情况下验证 policy cargo run --package neurontrace -- validate --policy policies/generic-agent.yaml # 提升 generation（使陈旧的 labels 失效） sudo ./target/release/neurontrace bump # 停止 enforcement 并 unpin BPF programs sudo ./target/release/neurontrace unload ``` ## 项目结构 ``` neurontrace/ Userspace binary — CLI, BPF loader, policy engine neurontrace-ebpf/ BPF programs — LSM hooks (no_std, runs in kernel) neurontrace-common/ Shared types between kernel and userspace xtask/ Build automation policies/ Starter policy packs (YAML) ``` ## 工作原理 1. **加载**：用户空间二进制文件通过 aya 将 BPF 程序加载到内核中 2. **附加**：LSM 钩子会在目标 cgroup 内的每个相关 syscall 上触发 3. **检查**：每个钩子都会查找策略映射表——没有匹配项则意味着拦截 4. **报告**：违规行为会通过 ring buffer 将事件发回用户空间 5. **反馈**：违规行为会被序列化为 JSON 并传递到 Unix socket（或 JSONL 文件），以便 agent 进行自我纠正 ## 编写策略 策略是包含一系列规则的 YAML 文件。每条规则将一个事件类型映射到一个操作，并带有可选的 path/argv glob 过滤器： ``` name: my-policy description: Custom policy for my agent rules: - event_type: exec action: allow path: "/usr/bin/git" - event_type: exec action: block - event_type: open action: allow - event_type: connect action: audit ``` 操作：`allow`、`block`、`kill`、`audit` 事件类型：`exec`、`open`、`unlink`、`rename`、`connect`、`ptrace`、`task_kill` 规则支持 `path` 和 `argv` glob 模式以进行细粒度过滤。请参阅[策略参考](docs/policies.md)。 ## 文档 | 文档 | 描述 | |-----|-------------| | **[快速开始](docs/quickstart.md)** | 通过一条命令查看执行限制效果 | | [策略参考](docs/policies.md) | schema、事件类型、操作、示例 | | [用例](docs/usecases.md) | 8 个带有开箱即用策略的真实场景 | | [开发指南](docs/development.md) | 内核设置、构建、虚拟机测试、调试 | | [贡献指南](CONTRIBUTING.md) | 如何贡献、代码风格、CI | | [安全政策](SECURITY.md) | 报告漏洞 | | [更新日志](CHANGELOG.md) | 更新内容 | ## License MIT

标签：AI代理沙箱, BPF-LSM, Docker镜像, HTTP工具, Rust, Streamlit, 内核级防护, 子域名枚举, 系统安全, 网络流量审计, 行为审计, 访问控制, 通知系统