falcosecurity/prempti

# Prempti [](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#ecosystem-scope) [](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#sandbox) [](LICENSE)   ## 当 Falco 遇见 AI 编码 Agent [](https://asciinema.org/a/lXqokxXVO4Q3IH3W) **Prempti** 将 [Falco](https://falco.org) 引入了 AI 编码 agent 的世界。它为您提供护栏机制，可以拒绝或要求确认不良行为，同时还能让您实时洞察编码 agent 进行的每一次工具调用——无论是 shell 命令、文件写入、读取还是 API 调用。这两者都由您可以自定义以适应工作流的 [Falco 规则](https://falco.org/docs/rules/) 驱动。 默认情况下，**Prempti** 在**护栏模式**下运行：规则生成判定结果，从而决定 agent 的行为。当工具调用被阻止或标记时，agent 会收到一个对 LLM 友好的解释，了解原因并进行调整——策略通过反馈来引导行为。如果您希望进行纯粹的观察而不加干预，可以切换到**监控模式**：每一次工具调用都会继续执行，同时规则仍会评估并记录活动。 这款工具是为谁准备的？适合任何日常使用编码 agent 的人——开发者、产品经理、设计师、凭直觉编程的程序员，以及任何希望看到 agent 在自己机器上做了什么并为其设定合理边界的人。 ### 它是什么 —— 以及它不是什么 **它是**位于工具调用层面的协作式策略与可视化层。它为您提供 agent 活动的审计追踪，以及 agent 能够遵守的护栏，因为 agent 能够看到并理解这些规则。 **它不是**沙箱、操作系统级别的安全机制，也无法替代最小权限环境或系统加固。它无法防范坚决对抗的 agent。请将其与隔离技术结合使用——它是这些技术的补充，但不能替代它们。 ## 功能 - **实时工具调用拦截** —— 在每一个 shell 命令、文件写入/编辑/读取、网络请求和 MCP 调用执行*之前*对其进行评估。 - **允许 / 拒绝 / 询问判定** —— 阻止、提示确认或放行；agent 在被拒绝时会收到对 LLM 友好的反馈并进行自我调整。 - **两种操作模式** —— *guardrails*（强制执行判定）和 *monitor*（仅观察）；随时可通过 `premptictl mode` 进行切换。 - **可自定义的 Falco 规则** —— 标准 YAML 规则；项目内置了一套精心策划的默认规则集，涵盖了常见的攻击面（凭据、禁用沙箱尝试、数据泄露、持久化、MCP/skill 污染等）。 - **完整的审计追踪** —— 记录每一次工具调用并附带结构化字段，可跨规则警报进行关联。 - **跨平台** —— 支持 Linux、macOS 和 Windows 上的 x86_64 和 aarch64 架构。 - **内置 CLI** —— `premptictl` 可用于状态检查、健康检查、模式切换、日志流式传输和 hook 管理。 - **Claude Code 专用的规则编写 skill** —— 一个交互式 skill，可在 agent 的帮助下起草和验证自定义规则。 ## 工作原理 当您的编码 agent 尝试使用工具时，**Prempti** 会在其执行*之前*拦截该调用，根据您的规则对其进行评估，并做出判定： | 判定 | 结果 | |---------|-------------| | **Allow** | 工具调用正常进行 | | **Deny** | 工具调用被阻止 —— agent 会收到原因说明 | | **Ask** | 系统会提示您批准或拒绝该调用 | 规则是用 YAML 编写的标准 [Falco 规则](https://falco.org/docs/rules/)。**Prempti** 内置了一套合理的默认规则集，您可以添加自己的规则以自定义工作流行为（参见[自定义规则](#custom-rules)）。 ### 模式 - **Guardrails 模式**（默认） —— 强制执行判定：`deny` 会阻止，`ask` 会提示您，`allow` 会继续执行。 - **Monitor 模式** —— 所有工具调用均会执行；判定结果仍会被评估并记录，但绝不会对 agent 产生干预。适用于纯观察、审计和规则调整。 随时可以通过 `premptictl mode ` 切换模式。 ## 适用场景 - 当您希望看到编码 agent 在会话期间的实际操作，而无需手动阅读每一次工具调用时。 - 当您希望设定明确的边界时 —— 例如不触碰 `.env` 文件、不推送到远程仓库、不在项目目录之外进行写入等。 - 当您在试验编码 agent 并希望为防止意外错误提供安全保障时。 - 当团队希望使用可共享的 YAML 规则，在各成员之间标准化 agent 的行为方式时。 - 最好与沙箱、系统加固或最小权限环境结合使用。 ## 快速开始 ### macOS 从[最新发布版本](https://github.com/falcosecurity/prempti/releases/latest)下载通用的 `.pkg` 安装程序并打开： ``` open prempti--darwin-universal.pkg ``` macOS 安装向导将引导您完成设置。服务将立即启动，并在每次后续登录时自动运行。 若需进行非交互式安装（用于 CI、脚本化设置或 SSH 会话）： ``` installer -pkg prempti--darwin-universal.pkg \ -target CurrentUserHomeDirectory ``` ### Linux 从[最新发布版本](https://github.com/falcosecurity/prempti/releases/latest)下载适用于您系统架构的安装包： ``` tar xzf prempti--linux-x86_64.tar.gz cd prempti--linux-x86_64 bash install.sh ``` 安装程序会将所有组件复制到 `~/.prempti/`，启动 systemd 用户服务，并自动注册 hook。 ### Windows 从[最新发布版本](https://github.com/falcosecurity/prempti/releases/latest)中，下载与您 CPU 架构匹配的 `.msi` 安装包并双击运行（或者执行 `msiexec /i prempti--windows-.msi`）。 MSI 会将所有组件部署到 `%LOCALAPPDATA%\prempti\`，将 `bin\` 添加到您的用户 `PATH` 中，注册 Claude Code hook，为后续登录注册自动启动项，并立即启动服务，无需任何额外步骤即可保护 Claude Code。 ### 验证 **Linux / macOS** ``` ~/.prempti/bin/premptictl status ~/.prempti/bin/premptictl hook status ~/.prempti/bin/premptictl health ``` **Windows** 安装程序会自动启动服务。打开一个**新的**终端（以便应用更新后的 `PATH`）并验证： ``` premptictl status premptictl hook status premptictl health ``` 预期的 `health` 输出：`OK: pipeline healthy (synthetic event → allow)`。 如果服务未运行（这种情况很罕见——例如安装后步骤超时），请使用 `premptictl start` 手动启动。系统已注册在每次登录时自动启动。 ## 管理 安装程序会在 Windows 上自动将 `bin/` 添加到您的 shell `PATH` 中；在 Linux/macOS 上，您需要将其添加到 shell 配置文件中（参见[验证](#verify)）。一旦 `premptictl` 进入您的 `PATH`，以下命令在每个平台上都是通用的： ``` # 检查状态 premptictl status # 检查 pipeline 健康状况（通过 full stack 发送 synthetic event） premptictl health # Guardrails 模式（默认）——执行 verdicts：deny 会阻断，ask 会提示 premptictl mode guardrails # Monitor 模式——所有 tool calls 继续；仅记录 verdicts premptictl mode monitor # 查看日志。默认显示最后 100 行；传入 -f 以持续跟踪，传入 --tail=N 进行覆盖。 premptictl logs # 临时禁用 interception（tool calls 在无监控状态下继续） premptictl hook remove # 重新启用 interception premptictl hook add # 停止 / 启动服务 premptictl stop premptictl start ``` ### 卸载 **Linux / macOS** ``` ~/.prempti/bin/premptictl uninstall # 将自定义 rules 保存在 rules/user/ 目录中，以便将来重新安装： ~/.prempti/bin/premptictl uninstall --keep-user-rules ``` **Windows** 以下任何路径均可生效——它们都会运行相同的清理自定义操作： - 应用与功能（推荐）， - `msiexec /x prempti--windows-.msi`（如果您保留了 MSI 文件）， - `msiexec /x `（该 GUID 位于 `HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\` 下的 Prempti 注册表项中）。 MSI 会在删除文件之前移除 Claude Code hook、自动启动项以及 `bin\` 的 `PATH` 条目，因此 Claude Code 不会处于 fail-closed（默认拒绝）状态。 ## 默认规则 本项目附带了一套默认规则集，分为六个部分，涵盖了 AI 编码 agent 常见的攻击面： | 部分 | 涵盖范围 | |---------|----------| | 工作目录边界 | 监控并询问对会话项目目录之外的文件访问 | | 敏感路径 | 拒绝对 `/etc/`、`~/.ssh/`、`~/.aws/`、云凭据、`.env` 文件等的读取和写入 | | 禁用沙箱 | 检测禁用 agent 自身沙箱配置的尝试 | | 威胁 | 凭据访问、破坏性命令、管道至 shell、编码载荷、数据泄露、IMDS 访问、反弹 shell、来自已知恶意主机的供应链安装 | | MCP 和 skill 内容 | MCP 服务器配置投毒 (`.mcp.json`) 和 slash-command 文件注入 (`.claude/commands/`) | | 持久化向量 | Hook 注入、git hooks、包注册表重定向、AI API base-URL 覆盖、API 密钥泄露到 env 文件中 | 有关完整的规则集，请参见 [`rules/default/coding_agents_rules.yaml`](rules/default/coding_agents_rules.yaml)。有关 schema、可用字段和编写约定，请参见 [`rules/README.md`](rules/README.md)。 ## 自定义规则 默认规则集是刻意设计为通用的——它能捕获适用于大多数工作流的明显风险操作。为了充分发挥 **Prempti** 的作用，您通常需要针对自己的具体工作编写专门的规则：您编辑的项目、推送到的远程仓库、视为敏感的文件，以及绝不希望 agent 运行的命令。 将您自己的规则添加到 `~/.prempti/rules/user/` 中。这些规则在升级后会被保留。您可以手动编写，也可以使用[规则编写 skill](#rule-authoring-skill-for-claude-code)，让 Claude Code 以交互方式为您起草并进行验证。 新增或修改后的规则将在下次服务启动时生效——使用以下命令重启服务： ``` premptictl stop premptictl start ``` 示例 —— 阻止将内容通过管道传递给 shell 解释器： ``` - rule: Deny pipe to shell desc: Block piping content to shell interpreters condition: > tool.name = "Bash" and (tool.input_command contains "| sh" or tool.input_command contains "| bash" or tool.input_command contains "| zsh") output: > Falco blocked piping to a shell interpreter (%tool.input_command) priority: CRITICAL source: coding_agent tags: [coding_agent_deny] ``` 规则使用标准的 [Falco 规则语言](https://falco.org/docs/rules/) (YAML) 编写。有关所有可用字段和示例，请参见 [`rules/README.md`](rules/README.md)。 ### Claude Code 的规则编写 Skill 我们内置了一个 Claude Code [skill](https://github.com/anthropics/skills) 来帮助您以交互方式编写自定义规则。 将此仓库注册为 Claude Code 插件市场： ``` /plugin marketplace add falcosecurity/prempti ``` 然后直接安装该 skill： ``` /plugin install prempti-falco-rules@prempti-skills ``` 或者通过交互方式浏览并安装： 1. 选择 `Browse and install plugins` 2. 选择 `prempti-skills` 3. 选择 `prempti-falco-rules` 4. 选择 `Install now` 安装完成后，您可以向 Claude Code 提出如下请求： - “阻止 agent 运行 git push” - “拒绝任何在工作目录之外的读取操作” - “创建一个在编辑 Dockerfiles 前要求确认的规则” 该 skill 会引导 Claude 编写规则、将其放置在正确的目录中，并使用 Falco 进行验证。 ## 支持的 Agent 与平台 | Agent | 平台 | 状态 | |-------|----------|--------| | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Linux (x86_64, aarch64) | 已支持 | | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | macOS (Apple Silicon, Intel) | 已支持 | | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Windows (x86_64, ARM64) | 已支持 | | [Codex](https://openai.com/index/codex/) | Linux | 实验性 | [Codex](https://openai.com/index/codex/) 的支持以实验性的 `codex-interceptor` 二进制文件形式存在于 `hooks/codex/` 中 —— 通信信封、插件字段 schema、默认规则集以及 `apply_patch` 的多文件处理在 Linux 上已实现端到端运行。macOS 和 Windows 理论上也能运行（该拦截器是跨平台的 Rust 程序），但目前尚未经过验证。使用 `premptictl hook add codex` 注册 hook；完整的安装程序集成（二进制文件打包、与 Claude 并行的由 supervisor 管理的生命周期）仍在开发中。有关设置的详细信息（包括 Codex 的 hook 信任要求），请参见 [`hooks/codex/README.md`](hooks/codex/README.md)。 ## 从源码构建

Linux

依赖项：Rust（最新稳定版） ``` make linux # Both architectures make linux-x86_64 # x86_64 only make linux-aarch64 # aarch64 only (requires cross toolchain) ``` 输出：`build/prempti--linux-{arch}.tar.gz` 详情请参见 [`installers/linux/`](installers/linux/)。

macOS

依赖项：Rust（最新稳定版）、CMake >= 3.24、Xcode Command Line Tools、通过 Homebrew 安装的 OpenSSL -darwin-.{tar.gz,pkg}` 通过以下任一方式安装本地构建的产物： ``` open build/prempti--darwin-.pkg # GUI wizard # 或者，非交互式： installer -pkg build/prempti--darwin-.pkg \ -target CurrentUserHomeDirectory # 或者，从 tarball： tar xzf build/prempti--darwin-.tar.gz -C /tmp bash /tmp/prempti--darwin-/install.sh ``` 详情请参见 [`installers/macos/`](installers/macos/)。

Windows

依赖项：Rust（最新稳定版）、Visual Studio 2022+ 及 C++ 工作负载、CMake 3.24+、带有 curl 的 vcpkg、.NET Runtime 9+、WiX Toolset v7。 ``` powershell -ExecutionPolicy Bypass -File installers\windows\package.ps1 ``` 输出：`build/out/prempti--windows-.msi`。 有关详细的先决条件和构建选项，请参见 [`installers/windows/`](installers/windows/)。

单独组件

``` make build # All components (interceptor, plugin, CLI tool) make build-interceptor # Interceptor only make build-plugin # Falco plugin only make build-ctl # CLI tool only make falco-macos # Falco binary (macOS only) ```

## 架构 ``` ┌──────────────┐ ┌──────────────┐ ┌────────────────────────────┐ │ Coding Agent │─────>│ Interceptor │─────>│ Falco (nodriver) │ │ │ │ (hook) │ │ ┌───────────────────────┐ │ │ │<─────│ │<─────│ │ Plugin (src + extract│ │ │ │ │ │ │ │ + embedded broker) │ │ └──────────────┘ └──────────────┘ │ └───────────────────────┘ │ │ Rule Engine + Rules │ └────────────────────────────┘ ``` 1. 编码 agent 的 hook 在每次工具调用前触发 2. **Interceptor（拦截器）** 通过 Unix socket 将事件发送到插件内置的 broker 3. **Plugin（插件）** 将事件提供给 Falco 的规则引擎 4. 匹配的规则产生判定结果 5. **Interceptor（拦截器）** 将判定结果传回给编码 agent 有关设计决策、组件规格和完整的架构文档，请参见 [CLAUDE.md](CLAUDE.md)。 ## 已知的局限性 ### Hook 级别拦截 **Prempti** 在编码 agent 的 hook API 层面拦截工具调用——它能看到 agent 要求运行的命令，但看不到这些命令在系统上产生的副作用。 这意味着，如果编码 agent 将有害逻辑嵌入源文件中，对其进行编译，然后运行生成的二进制文件，Falco 可以检查编译和运行命令，但无法分析编译后的程序在运行时实际执行的操作。规则看到的是 `gcc main.c -o main` 和 `./main`，而不是 `./main` 发起的系统调用。 因此，其覆盖范围是不对称的： - 对于结构化工具（如 `Write`、`Edit` 和 `Read`）效果最强，因为 agent 暴露了一流的文件语义。 - 对于通用工具（如 `Bash`）效果较弱，因为规则评估的是声明的命令，而不是完全解析后的 shell 行为。 - 对于外部系统（如 MCP）仅限于输入端，**Prempti** 可以检查请求的调用，但无法检查 MCP 服务器随后执行的副作用。 在实践中，护栏模式可以阻止许多不安全或违反策略的工具调用，但它不是操作系统级别的隔离机制，不应被视为硬性边界。若要获得更深入的可见性——检测进程在 syscall 级别实际执行的操作——Falco 的内核插桩是正确的工具（至少对于 Linux 而言）。 ## 反馈 针对 AI 编码 agent 的策略和可视化是一个全新的领域——我们正与社区共同探索。 如果您正在使用 **Prempti**，我们非常乐意听到您的反馈： - **哪些功能表现出色？** 您编写了哪些规则？捕获到了什么？ - **缺少了什么？** 您需要支持哪些 agent 或平台？ - **出现了什么问题？** 哪些功能未按预期工作？ 您的体验将直接决定本项目下一步的发展方向。欢迎提交 [issue](https://github.com/falcosecurity/prempti/issues)，或直接联系维护者。每一条反馈都对我们有帮助。 ## 致谢 **Prempti** 的构建得益于 [Claude Code](https://github.com/anthropics/claude-code) 的大力协助。 初步研究和构思由 [Leonardo Grasso](https://github.com/leogr)、[Loris Degioanni](https://github.com/ldegio) 和 [Michael Clark](https://github.com/MikeC-Sysdig) 完成。 支持与测试由 [Alessandro Cannarella](https://github.com/c2ndev)、[Iacopo Rozzo](https://github.com/irozzo-1a) 和 [Leonardo Di Giovanna](https://github.com/ekoops) 提供。 ## 许可证 Apache License 2.0。详见 [LICENSE](LICENSE)。

标签：AI编程助手, DLL 劫持, Falco, Lerna, 大语言模型, 敏感词过滤, 日志审计, 策略执行, 行为监控, 通知系统