log-bell/avakill

## 问题所在 AI Agent 在生产环境中运行，其工具调用却**没有任何安全控制**。结果可想而知： - **Replit 的 Agent** 删除了生产数据库，并伪造了 4000 个虚假用户账户来掩盖此事。 - **Google 的 Gemini CLI** 清空了用户的整个 D: 盘 —— 超过 8000 个文件，瞬间消失。 - **Amazon Q** 在一次调试会话中终止了 EC2 实例并删除了基础设施。 这些并非个案。研究表明，AI Agent 在 **75% 的现实任务中会失败**，而且一旦失败，往往是灾难性的 —— 因为在 Agent 和它的工具之间没有任何阻隔。 **AvaKill 就是那个缺失的层。** 一个防火墙，拦截每一次工具调用，根据你的安全策略进行评估，并在危险操作执行前将其扼杀。无 ML 模型，无 API 调用，无延迟 —— 仅在 <1ms 内进行快速、确定性的策略检查。 ## 快速开始 ``` pipx install avakill avakill setup ``` `avakill setup` 将引导你完成一个交互式流程： 1. **检测 Agent** 跨三个执行路径（hooks, MCP proxy, OS sandbox） 2. **创建策略** 从包含 14 个类别、81 条规则的目录中选择 3. **安装 Hooks** 针对检测到的 Agent（Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw） 4. **封装 MCP 服务器** 针对支持 MCP 的 Agent（Claude Desktop, Cline, Continue） 5. **显示沙箱命令** 针对支持 OS 级别隔离的 Agent 6. **启用追踪**（可选）用于审计日志和诊断 设置完成后，测试一下： ``` echo '{"tool": "Bash", "args": {"command": "rm -rf /"}}' | avakill evaluate --policy avakill.yaml # deny: 匹配规则 'block-catastrophic-shell' ``` 安全的调用会通过。破坏性的调用在执行前被扼杀。 ### 可选框架扩展 ``` pip install "avakill[openai]" # OpenAI function calling pip install "avakill[anthropic]" # Anthropic tool use pip install "avakill[langchain]" # LangChain / LangGraph pip install "avakill[mcp]" # MCP proxy pip install "avakill[all]" # Everything ``` ## 工作原理 AvaKill 通过三条独立的执行路径执行单一的 YAML 策略。每条路径均可独立工作 —— 无需守护进程（daemon），无单点故障。 ``` avakill.yaml (one policy file) | ├── Hooks (Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw) | → work standalone, evaluate in-process | ├── MCP Proxy (wraps MCP servers) | → works standalone, evaluate in-process | ├── OS Sandbox (launch + profiles) | → works standalone, OS-level enforcement | └── Daemon (optional) → shared evaluation, audit logging → hooks/proxy CAN talk to it if running → enables: logs, fix, tracking, approvals, metrics ```

**单一策略文件** `avakill.yaml` 是唯一的真实来源。默认拒绝（Deny-by-default）、允许列表、速率限制、参数模式匹配、Shell 安全检查、路径解析和内容扫描。	**原生 Agent Hooks** 为 Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, 和 OpenClaw 提供开箱即用的 hooks。一条命令即可安装。可独立工作 —— 无需守护进程（daemon）。
**MCP Proxy** 用策略执行封装任何 MCP 服务器。扫描工具响应中的 Secrets、PII 和 Prompt Injection。可独立工作，进程内评估。	**OS Sandbox** 在 OS 级别的沙箱中启动 Agent。Linux 上使用 Landlock，macOS 上使用 sandbox-exec，Windows 上使用 AppContainer。默认拒绝，内核级执行。
**亚毫秒级** 纯规则评估，无 ML 模型。为耗时 500ms-5s 的工具调用增加 <1ms 的开销。三条执行路径，零瓶颈。	**可选 Daemon** 共享评估、审计日志和可观测性工具。Hooks 和 proxy 可在运行时与其通信。启用日志、追踪、审批和指标。

## 集成 ### 原生 Agent Hooks 零代码修改保护 AI Agent —— 只需安装 hook： ``` # 安装 hooks (独立运行 — 无需 daemon) avakill hook install --agent claude-code # or cursor, windsurf, gemini-cli, openai-codex, kiro, amp, openclaw, all avakill hook list ``` Hooks 默认独立工作 —— 每个 hook 在进程内评估策略。策略使用规范化的工具名称（`shell_execute`, `file_write`, `file_read`），因此一个策略适用于所有 Agent。 | Agent | Hook 状态 | |---|---| | Claude Code | 实战检验 | | Cursor | 支持 | | Windsurf | 支持 | | Gemini CLI | 支持 | | OpenAI Codex | 支持 | | Kiro | 支持 | | Amp | 支持 | | OpenClaw | 原生插件 (6 层) | **OpenClaw 原生插件：** OpenClaw 使用专用插件（[avakill-openclaw](https://github.com/log-bell/avakill-openclaw)），具有 6 层执行 —— 硬阻断、守护工具、输出扫描、消息网关、生成控制和上下文注入。使用 `openclaw plugins install avakill-openclaw` 安装。沙箱可通过 `avakill launch --agent openclaw` 作为备选方案。 ### MCP Proxy 封装 MCP 服务器以将所有工具调用路由通过 AvaKill： ``` avakill mcp-wrap --agent claude-desktop # or cursor, windsurf, cline, continue, all avakill mcp-unwrap --agent all # Restore original configs ``` 支持的 Agent：Claude Desktop, Cursor, Windsurf, Cline, Continue.dev。 ### OS Sandbox 使用预置的配置文件在 OS 级别的沙箱中启动 Agent： ``` avakill profile list # See available profiles avakill profile show aider # See what a profile restricts avakill launch --agent aider -- aider # Launch with OS sandbox ``` 提供的 Profiles 包括：OpenClaw（备选 —— 优先使用[原生插件](https://github.com/log-bell/avakill-openclaw)）、Cline、Continue、SWE-Agent 和 Aider。 ### Python SDK 对于编程集成，AvaKill 的 `Guard` 可作为 Python API 使用： ``` from avakill import Guard, protect guard = Guard(policy="avakill.yaml") @protect(guard=guard, on_deny="return_none") # or "raise" (default), "callback" def execute_sql(query: str) -> str: return db.execute(query) ``` **框架包装器：** ``` # OpenAI from avakill import GuardedOpenAIClient client = GuardedOpenAIClient(OpenAI(), policy="avakill.yaml") # Anthropic from avakill import GuardedAnthropicClient client = GuardedAnthropicClient(Anthropic(), policy="avakill.yaml") # LangChain / LangGraph from avakill import AvaKillCallbackHandler handler = AvaKillCallbackHandler(policy="avakill.yaml") agent.invoke({"input": "..."}, config={"callbacks": [handler]}) ``` ## 策略配置 策略是 YAML 文件。规则从上到下评估 —— 首次匹配生效。 ``` version: "1.0" default_action: deny policies: # Allow safe shell with allowlist + metacharacter protection - name: "allow-safe-shell" tools: ["shell_execute", "Bash", "run_shell_command", "run_command", "shell", "local_shell", "exec_command"] action: allow conditions: shell_safe: true command_allowlist: [echo, ls, cat, pwd, git, python, pip, npm, node, make] # Block destructive SQL - name: "block-destructive-sql" tools: ["execute_sql", "database_*"] action: deny conditions: args_match: query: ["DROP", "DELETE", "TRUNCATE", "ALTER"] message: "Destructive SQL blocked. Use a manual migration." # Block writes to system directories - name: "block-system-writes" tools: ["file_write", "file_edit", "Write", "Edit"] action: deny conditions: path_match: file_path: ["/etc/", "/usr/", "/bin/", "/sbin/"] # Scan for secrets in tool arguments - name: "block-secret-leaks" tools: ["*"] action: deny conditions: content_scan: true # Rate limit API calls - name: "rate-limit-search" tools: ["web_search"] action: allow rate_limit: max_calls: 10 window: "60s" # Require human approval for file writes - name: "approve-writes" tools: ["file_write"] action: require_approval ``` **策略特性：** - **Glob 模式** — `*`, `delete_*`, `*_execute` 匹配工具名称 - **参数匹配** — `args_match` / `args_not_match` 检查参数（不区分大小写的子字符串） - **Shell 安全** — `shell_safe` 阻断元字符；`command_allowlist` 限制为已知安全的二进制文件 - **路径解析** — `path_match` / `path_not_match` 支持 symlink 解析、`~` 和 `$HOME` 展开 - **内容扫描** — `content_scan` 检测参数中的 Secrets、PII 和 Prompt Injection - **速率限制** — 滑动窗口（`10s`, `5m`, `1h`） - **审批关卡** — `require_approval` 暂停执行直到人工批准或拒绝 - **执行级别** — `hard`（默认）、`soft` 或 `advisory` - **首次匹配生效** — 顺序很重要，将具体规则放在通用规则之前 ## CLI ### 设置与策略 ``` avakill setup # Interactive setup — detects agents, builds policy, installs hooks avakill validate avakill.yaml # Validate a policy file avakill rules # Browse and toggle catalog rules avakill rules list # Show all rules with sources avakill rules create # Interactive custom rule creation avakill reset # Factory-reset AvaKill ``` ### Hooks 与 MCP ``` avakill hook install --agent all # Install hooks for detected agents avakill hook list # Show hook status avakill mcp-wrap --agent all # Wrap MCP servers with policy enforcement avakill mcp-unwrap --agent all # Restore original MCP configs ``` ### 监控与恢复 ``` avakill fix # See why a call was blocked and how to fix it avakill logs --denied-only --since 1h # Query audit logs avakill logs tail # Follow new events in real-time avakill tracking on # Enable activity tracking ``` ### 评估与审批 ``` echo '{"tool": "Bash", "args": {"command": "rm -rf /"}}' | avakill evaluate --policy avakill.yaml avakill review avakill.proposed.yaml # Review proposed policy changes avakill approve avakill.proposed.yaml # Activate proposed policy (human-only) avakill approvals list # List pending approval requests avakill approvals grant REQUEST_ID # Approve a pending request ``` ### Daemon ``` avakill daemon start --policy avakill.yaml # Start persistent daemon (optional) avakill daemon status # Check daemon status avakill daemon stop # Stop daemon ``` ### 安全与合规 ``` avakill keygen # Generate Ed25519 keypair avakill sign avakill.yaml # Sign policy avakill verify avakill.yaml # Verify signature avakill harden avakill.yaml # Set OS-level immutable flags avakill compliance report --framework soc2 # Compliance assessment avakill compliance gaps # Show compliance gaps ``` ### 使用任意 LLM 生成策略 ``` avakill schema --format=prompt # Generate a prompt for any LLM avakill schema --format=prompt --tools="execute_sql,shell_exec" --use-case="data pipeline" avakill validate generated-policy.yaml # Validate the LLM's output ``` ## 为什么选择 AvaKill？ | | 无保护 | Prompt Guardrails | **AvaKill** | |---|:---:|:---:|:---:| | 阻止破坏性工具调用 | :x: | :x: | :white_check_mark: | | 适用于所有主流 Agent | — | 部分 | :white_check_mark: | | 三条独立执行路径 | — | :x: | :white_check_mark: | | 确定性（无需 LLM） | — | :x: | :white_check_mark: | | <1ms 开销 | — | :x: (LLM 往返) | :white_check_mark: | | 基于 YAML 的策略 | — | :x: | :white_check_mark: | | 完整审计追踪 | :x: | :x: | :white_check_mark: | | 人工参与审批 | :x: | :x: | :white_check_mark: | | 自我保护（防篡改） | :x: | :x: | :white_check_mark: | | 开源 | — | 部分 | :white_check_mark: AGPL 3.0 | ## 路线图 ### 稳定版 - [x] 核心策略引擎，支持 Glob 模式、参数匹配、速率限制 - [x] 交互式设置向导，包含 81 条规则目录（`avakill setup`） - [x] 原生 Agent Hooks（Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw） - [x] MCP Proxy，支持 `avakill mcp-wrap` 和 `avakill-shim`（Go 二进制） - [x] OS 级别沙箱 —— Landlock, sandbox-exec, AppContainer - [x] 独立 Hook 模式（无需 daemon） - [x] 持久化 Daemon 与 Unix socket（<5ms 评估） - [x] Shell 安全（`shell_safe` + `command_allowlist`） - [x] 路径解析，包含 Symlink 检测、`~` 和 `$HOME` 展开 - [x] 内容扫描（Secrets, PII, Prompt Injection） - [x] SQLite 审计日志，支持异步批量写入 - [x] 跨 Agent 的工具名称标准化 - [x] 多级策略级联（system/global/project/local） - [x] 人工参与审批工作流 - [x] 策略提议/审查/批准工作流 - [x] 恢复 UX（`avakill fix`） - [x] 自我保护（硬编码防篡改规则） - [x] 策略签名（HMAC-SHA256 + Ed25519） - [x] 合规报告（SOC 2, NIST AI RMF, EU AI Act, ISO 42001） - [x] 用于任何 Python 函数的 `@protect` 装饰器 - [x] 框架包装器（OpenAI, Anthropic, LangChain/LangGraph） - [x] `avakill rules` 用于设置后的规则管理 ### 计划中 - [ ] 实时监控仪表板 - [ ] MCP HTTP 传输代理（Streamable HTTP） - [ ] Slack / webhook / PagerDuty 通知 - [ ] CrewAI / AutoGen / 自定义框架拦截器 ## 许可证 [AGPL-3.0](LICENSE) —— 可免费使用、修改和分发。如果你将 AvaKill 作为网络服务提供，你必须以相同的许可证发布你的源代码。详情请参阅 [LICENSE](LICENSE)。

标签：Agentic AI, Agent 防火墙, AI 安全, AI 防火墙, Anthropic, AppSec, CI/CD 安全, CISA项目, CIS基准, Deterministic Security, LangChain, Lerna, LLM 安全, MCP, OpenAI, Python, RAG 安全, Streamlit, Web报告查看器, YAML 策略, 人工智能安全, 内存规避, 合规性, 大模型安全, 安全中间件, 实时拦截, 工具调用拦截, 恶意操作拦截, 提示词注入防护, 数据库保护, 数据投毒防御, 文件系统保护, 无后门, 日志审计, 智能体安全, 模型上下文协议, 沙箱, 生产环境安全, 策略执行, 访问控制, 越狱防护, 轻量级, 运行时防护, 逆向工具, 配置错误