{"id":45520666,"url":"https://github.com/log-bell/avakill","last_synced_at":"2026-03-08T05:09:16.584Z","repository":{"id":339622699,"uuid":"1160067809","full_name":"log-bell/avakill","owner":"log-bell","description":"🔪 Open-source safety firewall for AI agents. Intercepts tool calls before they execute, enforces YAML policies, and kills dangerous operations in real-time. Works with OpenAI, Anthropic, LangChain, and MCP. She doesn't guard. She kills.","archived":false,"fork":false,"pushed_at":"2026-03-07T14:42:27.000Z","size":6374,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-07T20:53:02.015Z","etag":null,"topics":["ai-agents","ai-safety","anthropic","claude-code","compliance","cursor","devtools","firewall","guardrails","langchain","llm","mcp","model-context-protocol","openai","policy-engine","prompt-injection","python","sandbox","security","tool-use"],"latest_commit_sha":null,"homepage":"https://avakill.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/log-bell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["log-bell"]}},"created_at":"2026-02-17T14:02:04.000Z","updated_at":"2026-03-07T14:42:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/log-bell/avakill","commit_stats":null,"previous_names":["log-bell/avakill"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/log-bell/avakill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/log-bell%2Favakill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/log-bell%2Favakill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/log-bell%2Favakill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/log-bell%2Favakill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/log-bell","download_url":"https://codeload.github.com/log-bell/avakill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/log-bell%2Favakill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30246627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-safety","anthropic","claude-code","compliance","cursor","devtools","firewall","guardrails","langchain","llm","mcp","model-context-protocol","openai","policy-engine","prompt-injection","python","sandbox","security","tool-use"],"created_at":"2026-02-22T22:29:55.977Z","updated_at":"2026-03-08T05:09:16.574Z","avatar_url":"https://github.com/log-bell.png","language":"Python","funding_links":["https://github.com/sponsors/log-bell"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# AvaKill\n\n### Open-source safety firewall for AI agents\n\n[![PyPI version](https://img.shields.io/pypi/v/avakill?color=blue)](https://pypi.org/project/avakill/)\n[![Python](https://img.shields.io/pypi/pyversions/avakill)](https://pypi.org/project/avakill/)\n[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/log-bell/avakill/ci.yml?branch=main\u0026label=tests)](https://github.com/log-bell/avakill/actions)\n![Tests](https://img.shields.io/badge/tests-2%2C108%20passing-brightgreen)\n![Red Team](https://img.shields.io/badge/red%20team-63%2F63%20blocked-red)\n[![GitHub stars](https://img.shields.io/github/stars/log-bell/avakill?style=social)](https://github.com/log-bell/avakill)\n\n**One YAML policy. Three independent enforcement paths. Every agent protected.**\n\n```bash\npipx install avakill \u0026\u0026 avakill setup\n```\n\n[Quickstart](#quickstart) · [How It Works](#how-it-works) · [Integrations](#integrations) · [Policy](#policy-configuration) · [CLI](#cli) · [Docs](https://avakill.com/docs/getting-started/) · [Contributing](CONTRIBUTING.md)\n\n\u003c/div\u003e\n\n---\n\n## The Problem\n\nAI agents are shipping to production with **zero safety controls** on their tool calls. The results are predictable:\n\n- **Replit's agent** dropped a production database and fabricated 4,000 fake user accounts to cover it up.\n- **Google's Gemini CLI** wiped a user's entire D: drive — 8,000+ files, gone.\n- **Amazon Q** terminated EC2 instances and deleted infrastructure during a debugging session.\n\nThese aren't edge cases. Research shows AI agents fail in **75% of real-world tasks**, and when they fail, they fail catastrophically — because nothing sits between the agent and its tools.\n\n**AvaKill is that missing layer.** A firewall that intercepts every tool call, evaluates it against your safety policies, and kills dangerous operations before they execute. No ML models, no API calls, no latency — just fast, deterministic policy checks in \u003c1ms.\n\n## Quickstart\n\n```bash\npipx install avakill\navakill setup\n```\n\n\u003e **macOS note:** macOS 14+ blocks `pip install` at the system level (PEP 668). Use `pipx` or a virtualenv.\n\n`avakill setup` walks you through an interactive flow that:\n\n1. **Detects agents** across three enforcement paths (hooks, MCP proxy, OS sandbox)\n2. **Creates a policy** from a catalog of 81 rules across 14 categories\n3. **Installs hooks** for detected agents (Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw)\n4. **Wraps MCP servers** for MCP-capable agents (Claude Desktop, Cline, Continue)\n5. **Shows sandbox commands** for agents that support OS-level containment\n6. **Enables tracking** (optional) for audit logs and diagnostics\n\nAfter setup, test it:\n\n```bash\necho '{\"tool\": \"Bash\", \"args\": {\"command\": \"rm -rf /\"}}' | avakill evaluate --policy avakill.yaml\n# deny: Matched rule 'block-catastrophic-shell'\n```\n\nSafe calls pass through. Destructive calls are killed before they execute.\n\n### Optional framework extras\n\n```bash\npip install \"avakill[openai]\"       # OpenAI function calling\npip install \"avakill[anthropic]\"    # Anthropic tool use\npip install \"avakill[langchain]\"    # LangChain / LangGraph\npip install \"avakill[mcp]\"          # MCP proxy\npip install \"avakill[all]\"          # Everything\n```\n\n## How It Works\n\nAvaKill enforces a single YAML policy across three independent enforcement paths. Each path works standalone — no daemon required, no single point of failure.\n\n```\navakill.yaml (one policy file)\n    |\n    ├── Hooks (Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw)\n    |     → work standalone, evaluate in-process\n    |\n    ├── MCP Proxy (wraps MCP servers)\n    |     → works standalone, evaluate in-process\n    |\n    ├── OS Sandbox (launch + profiles)\n    |     → works standalone, OS-level enforcement\n    |\n    └── Daemon (optional)\n          → shared evaluation, audit logging\n          → hooks/proxy CAN talk to it if running\n          → enables: logs, fix, tracking, approvals, metrics\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**One Policy File**\u003cbr\u003e\n`avakill.yaml` is the single source of truth. Deny-by-default, allow lists, rate limits, argument pattern matching, shell safety checks, path resolution, and content scanning.\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Native Agent Hooks**\u003cbr\u003e\nDrop-in hooks for Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, and OpenClaw. One command to install. Works standalone — no daemon required.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**MCP Proxy**\u003cbr\u003e\nWraps any MCP server with policy enforcement. Scans tool responses for secrets, PII, and prompt injection. Works standalone, evaluates in-process.\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**OS Sandbox**\u003cbr\u003e\nLaunch agents in OS-level sandboxes. Landlock on Linux, sandbox-exec on macOS, AppContainer on Windows. Deny-default, kernel-level enforcement.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Sub-Millisecond**\u003cbr\u003e\nPure rule evaluation, no ML models. Adds \u003c1ms overhead to tool calls that already take 500ms-5s. Three enforcement paths, zero bottlenecks.\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n**Optional Daemon**\u003cbr\u003e\nShared evaluation, audit logging, and visibility tooling. Hooks and proxy can talk to it when running. Enables logs, tracking, approvals, and metrics.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Integrations\n\n### Native Agent Hooks\n\nProtect AI agents with zero code changes — just install the hook:\n\n```bash\n# Install hooks (works standalone — no daemon required)\navakill hook install --agent claude-code  # or cursor, windsurf, gemini-cli, openai-codex, kiro, amp, openclaw, all\navakill hook list\n```\n\nHooks work standalone by default — each hook evaluates policies in-process. Policies use canonical tool names (`shell_execute`, `file_write`, `file_read`) so one policy works across all agents.\n\n| Agent | Hook Status |\n|---|---|\n| Claude Code | Battle-tested |\n| Cursor | Supported |\n| Windsurf | Supported |\n| Gemini CLI | Supported |\n| OpenAI Codex | Supported |\n| Kiro | Supported |\n| Amp | Supported |\n| OpenClaw | Native plugin (6-layer) |\n\n**OpenClaw native plugin:** OpenClaw uses a dedicated plugin ([avakill-openclaw](https://github.com/log-bell/avakill-openclaw)) with 6 enforcement layers — hard block, guard tool, output scanning, message gate, spawn control, and context injection. Install with `openclaw plugins install avakill-openclaw`. Sandbox is available as a fallback via `avakill launch --agent openclaw`.\n\n### MCP Proxy\n\nWrap MCP servers to route all tool calls through AvaKill:\n\n```bash\navakill mcp-wrap --agent claude-desktop   # or cursor, windsurf, cline, continue, all\navakill mcp-unwrap --agent all            # Restore original configs\n```\n\nSupported agents: Claude Desktop, Cursor, Windsurf, Cline, Continue.dev.\n\n### OS Sandbox\n\nLaunch agents in OS-level sandboxes with pre-built profiles:\n\n```bash\navakill profile list                    # See available profiles\navakill profile show aider              # See what a profile restricts\navakill launch --agent aider -- aider   # Launch with OS sandbox\n```\n\nProfiles ship for OpenClaw (fallback — prefer the [native plugin](https://github.com/log-bell/avakill-openclaw)), Cline, Continue, SWE-Agent, and Aider.\n\n### Python SDK\n\nFor programmatic integration, AvaKill's `Guard` is available as a Python API:\n\n```python\nfrom avakill import Guard, protect\n\nguard = Guard(policy=\"avakill.yaml\")\n\n@protect(guard=guard, on_deny=\"return_none\")  # or \"raise\" (default), \"callback\"\ndef execute_sql(query: str) -\u003e str:\n    return db.execute(query)\n```\n\n**Framework wrappers:**\n\n```python\n# OpenAI\nfrom avakill import GuardedOpenAIClient\nclient = GuardedOpenAIClient(OpenAI(), policy=\"avakill.yaml\")\n\n# Anthropic\nfrom avakill import GuardedAnthropicClient\nclient = GuardedAnthropicClient(Anthropic(), policy=\"avakill.yaml\")\n\n# LangChain / LangGraph\nfrom avakill import AvaKillCallbackHandler\nhandler = AvaKillCallbackHandler(policy=\"avakill.yaml\")\nagent.invoke({\"input\": \"...\"}, config={\"callbacks\": [handler]})\n```\n\n## Policy Configuration\n\nPolicies are YAML files. Rules are evaluated top-to-bottom — first match wins.\n\n```yaml\nversion: \"1.0\"\ndefault_action: deny\n\npolicies:\n  # Allow safe shell with allowlist + metacharacter protection\n  - name: \"allow-safe-shell\"\n    tools: [\"shell_execute\", \"Bash\", \"run_shell_command\", \"run_command\",\n            \"shell\", \"local_shell\", \"exec_command\"]\n    action: allow\n    conditions:\n      shell_safe: true\n      command_allowlist: [echo, ls, cat, pwd, git, python, pip, npm, node, make]\n\n  # Block destructive SQL\n  - name: \"block-destructive-sql\"\n    tools: [\"execute_sql\", \"database_*\"]\n    action: deny\n    conditions:\n      args_match:\n        query: [\"DROP\", \"DELETE\", \"TRUNCATE\", \"ALTER\"]\n    message: \"Destructive SQL blocked. Use a manual migration.\"\n\n  # Block writes to system directories\n  - name: \"block-system-writes\"\n    tools: [\"file_write\", \"file_edit\", \"Write\", \"Edit\"]\n    action: deny\n    conditions:\n      path_match:\n        file_path: [\"/etc/\", \"/usr/\", \"/bin/\", \"/sbin/\"]\n\n  # Scan for secrets in tool arguments\n  - name: \"block-secret-leaks\"\n    tools: [\"*\"]\n    action: deny\n    conditions:\n      content_scan: true\n\n  # Rate limit API calls\n  - name: \"rate-limit-search\"\n    tools: [\"web_search\"]\n    action: allow\n    rate_limit:\n      max_calls: 10\n      window: \"60s\"\n\n  # Require human approval for file writes\n  - name: \"approve-writes\"\n    tools: [\"file_write\"]\n    action: require_approval\n```\n\n**Policy features:**\n- **Glob patterns** — `*`, `delete_*`, `*_execute` match tool names\n- **Argument matching** — `args_match` / `args_not_match` inspect arguments (case-insensitive substring)\n- **Shell safety** — `shell_safe` blocks metacharacters; `command_allowlist` restricts to known-good binaries\n- **Path resolution** — `path_match` / `path_not_match` with symlink resolution, `~` and `$HOME` expansion\n- **Content scanning** — `content_scan` detects secrets, PII, and prompt injection in arguments\n- **Rate limiting** — sliding window (`10s`, `5m`, `1h`)\n- **Approval gates** — `require_approval` pauses until a human grants or rejects\n- **Enforcement levels** — `hard` (default), `soft`, or `advisory`\n- **First-match-wins** — order matters, put specific rules before general ones\n\n\u003e Full reference: [`docs/policy-reference.md`](docs/policy-reference.md)\n\n## CLI\n\n### Setup \u0026 Policy\n\n```bash\navakill setup                              # Interactive setup — detects agents, builds policy, installs hooks\navakill validate avakill.yaml              # Validate a policy file\navakill rules                              # Browse and toggle catalog rules\navakill rules list                         # Show all rules with sources\navakill rules create                       # Interactive custom rule creation\navakill reset                              # Factory-reset AvaKill\n```\n\n### Hooks \u0026 MCP\n\n```bash\navakill hook install --agent all           # Install hooks for detected agents\navakill hook list                          # Show hook status\navakill mcp-wrap --agent all               # Wrap MCP servers with policy enforcement\navakill mcp-unwrap --agent all             # Restore original MCP configs\n```\n\n### Monitoring \u0026 Recovery\n\n```bash\navakill fix                                # See why a call was blocked and how to fix it\navakill logs --denied-only --since 1h      # Query audit logs\navakill logs tail                          # Follow new events in real-time\navakill tracking on                        # Enable activity tracking\n```\n\n### Evaluate \u0026 Approve\n\n```bash\necho '{\"tool\": \"Bash\", \"args\": {\"command\": \"rm -rf /\"}}' | avakill evaluate --policy avakill.yaml\navakill review avakill.proposed.yaml       # Review proposed policy changes\navakill approve avakill.proposed.yaml      # Activate proposed policy (human-only)\navakill approvals list                     # List pending approval requests\navakill approvals grant REQUEST_ID         # Approve a pending request\n```\n\n### Daemon\n\n```bash\navakill daemon start --policy avakill.yaml # Start persistent daemon (optional)\navakill daemon status                      # Check daemon status\navakill daemon stop                        # Stop daemon\n```\n\n### Security \u0026 Compliance\n\n```bash\navakill keygen                             # Generate Ed25519 keypair\navakill sign avakill.yaml                  # Sign policy\navakill verify avakill.yaml                # Verify signature\navakill harden avakill.yaml                # Set OS-level immutable flags\navakill compliance report --framework soc2 # Compliance assessment\navakill compliance gaps                    # Show compliance gaps\n```\n\n### Generate Policies with Any LLM\n\n```bash\navakill schema --format=prompt             # Generate a prompt for any LLM\navakill schema --format=prompt --tools=\"execute_sql,shell_exec\" --use-case=\"data pipeline\"\navakill validate generated-policy.yaml     # Validate the LLM's output\n```\n\n## Why AvaKill?\n\n|  | No Protection | Prompt Guardrails | **AvaKill** |\n|---|:---:|:---:|:---:|\n| Stops destructive tool calls | :x: | :x: | :white_check_mark: |\n| Works across all major agents | — | Partial | :white_check_mark: |\n| Three independent enforcement paths | — | :x: | :white_check_mark: |\n| Deterministic (no LLM needed) | — | :x: | :white_check_mark: |\n| \u003c1ms overhead | — | :x: (LLM round-trip) | :white_check_mark: |\n| YAML-based policies | — | :x: | :white_check_mark: |\n| Full audit trail | :x: | :x: | :white_check_mark: |\n| Human-in-the-loop approvals | :x: | :x: | :white_check_mark: |\n| Self-protection (anti-tampering) | :x: | :x: | :white_check_mark: |\n| Open source | — | Some | :white_check_mark: AGPL 3.0 |\n\n## Roadmap\n\n### Stable\n\n- [x] Core policy engine with glob patterns, argument matching, rate limiting\n- [x] Interactive setup wizard with 81-rule catalog (`avakill setup`)\n- [x] Native agent hooks (Claude Code, Cursor, Windsurf, Gemini CLI, Codex, Kiro, Amp, OpenClaw)\n- [x] MCP proxy with `avakill mcp-wrap` and `avakill-shim` (Go binary)\n- [x] OS-level sandboxing — Landlock, sandbox-exec, AppContainer\n- [x] Standalone hook mode (no daemon required)\n- [x] Persistent daemon with Unix socket (\u003c5ms evaluation)\n- [x] Shell safety (`shell_safe` + `command_allowlist`)\n- [x] Path resolution with symlink detection, `~` and `$HOME` expansion\n- [x] Content scanning (secrets, PII, prompt injection)\n- [x] SQLite audit logging with async batched writes\n- [x] Tool name normalization across agents\n- [x] Multi-level policy cascade (system/global/project/local)\n- [x] Human-in-the-loop approval workflows\n- [x] Policy propose / review / approve workflow\n- [x] Recovery UX (`avakill fix`)\n- [x] Self-protection (hardcoded anti-tampering rules)\n- [x] Policy signing (HMAC-SHA256 + Ed25519)\n- [x] Compliance reports (SOC 2, NIST AI RMF, EU AI Act, ISO 42001)\n- [x] `@protect` decorator for any Python function\n- [x] Framework wrappers (OpenAI, Anthropic, LangChain/LangGraph)\n- [x] `avakill rules` for post-setup rule management\n\n### Planned\n\n- [ ] Real-time monitoring dashboard\n- [ ] MCP HTTP transport proxy (Streamable HTTP)\n- [ ] Slack / webhook / PagerDuty notifications\n- [ ] CrewAI / AutoGen / custom framework interceptors\n\n## Contributing\n\nWe welcome contributions! AvaKill is early-stage and there's a lot to build.\n\n```bash\ngit clone https://github.com/log-bell/avakill.git\ncd avakill\nmake dev    # Install in dev mode with all dependencies\nmake test   # Run the test suite\n```\n\nSee [**CONTRIBUTING.md**](CONTRIBUTING.md) for the full guide — architecture overview, code style, and PR process.\n\n## License\n\n[AGPL-3.0](LICENSE) — free to use, modify, and distribute. If you offer AvaKill as a network service, you must release your source code under the same license. See [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n*She doesn't guard. She kills.*\n\n**If AvaKill would have saved you from an AI agent disaster, [give it a star](https://github.com/log-bell/avakill).**\n\nBuilt because an AI agent tried to `DROP TABLE users` on a Friday afternoon.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flog-bell%2Favakill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flog-bell%2Favakill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flog-bell%2Favakill/lists"}