{"id":49813348,"url":"https://github.com/dortort/agent-bound","last_synced_at":"2026-05-13T02:30:44.879Z","repository":{"id":336866153,"uuid":"1151201469","full_name":"dortort/agent-bound","owner":"dortort","description":"Access control framework for MCP servers — Android-style declarative permissions for the Model Context Protocol, inspired by the AgentBound paper","archived":false,"fork":false,"pushed_at":"2026-02-06T14:06:09.000Z","size":75,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T21:28:21.210Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dortort.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2026-02-06T07:05:36.000Z","updated_at":"2026-02-06T14:29:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dortort/agent-bound","commit_stats":null,"previous_names":["dortort/agent-bound"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dortort/agent-bound","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fagent-bound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fagent-bound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fagent-bound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fagent-bound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dortort","download_url":"https://codeload.github.com/dortort/agent-bound/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dortort%2Fagent-bound/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32965212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"online","status_checked_at":"2026-05-13T02:00:07.132Z","response_time":115,"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":[],"created_at":"2026-05-13T02:30:44.177Z","updated_at":"2026-05-13T02:30:44.872Z","avatar_url":"https://github.com/dortort.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-bound\n\n\u003e **Experimental** — Access control framework for MCP servers, inspired by the [AgentBound](https://arxiv.org/abs/2510.21236) research paper.\n\n`agent-bound` brings Android-style declarative permissions to [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers. Each MCP server ships a manifest declaring the system resources it needs. At runtime a policy enforcement engine restricts the server to only those resources, shifting the ecosystem from *trust-by-default* toward *least-privilege*.\n\n## Status\n\nThis is an **experimental reference implementation** for research and prototyping. It is not production-hardened. The permission vocabulary and manifest format may change.\n\n## Overview\n\nThe framework has three components, mirroring the paper's architecture:\n\n| Component | Description |\n|---|---|\n| **AgentManifest** | Declarative JSON policy declaring which resources an MCP server requires |\n| **AgentBox** | Policy enforcement engine — resolves generic permissions into scoped runtime permissions and enforces them |\n| **AgentManifestGen** | Automated manifest generator — analyses source code to produce a draft manifest |\n\n### How it works\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│  MCP Server Codebase                                         │\n│                                                              │\n│  ┌───────────────────┐     ┌──────────────────────────────┐  │\n│  │ AgentManifestGen  │────▶│ agent-manifest.json          │  │\n│  │ (source analysis) │     │ {                            │  │\n│  └───────────────────┘     │   \"description\": \"...\",      │  │\n│                            │   \"permissions\": [           │  │\n│                            │     \"mcp.ac.filesystem.read\",│  │\n│                            │     \"mcp.ac.network.client\"  │  │\n│                            │   ]                          │  │\n│                            │ }                            │  │\n│                            └──────────────┬───────────────┘  │\n└───────────────────────────────────────────┼──────────────────┘\n                                            │\n                                            ▼\n┌──────────────────────────────────────────────────────────────┐\n│  AgentBox (Policy Enforcement Engine)                        │\n│                                                              │\n│  1. Load manifest                                            │\n│  2. Resolve generic → effective permissions (with overrides) │\n│  3. Request user consent                                     │\n│  4. Launch MCP server in sandboxed environment               │\n│  5. Enforce: filtered env, scoped fs, network allow-list     │\n│  6. Audit all access attempts                                │\n└──────────────────────────────────────────────────────────────┘\n```\n\n## Installation\n\n```bash\nnpm install agent-bound\n```\n\nOr clone and build from source:\n\n```bash\ngit clone \u003crepo-url\u003e\ncd agent-bound\nnpm install\nnpm run build\n```\n\n## Permission Vocabulary\n\nPermissions use the `mcp.ac.\u003ccategory\u003e.\u003caction\u003e` naming convention:\n\n| Permission | Category | Description |\n|---|---|---|\n| `mcp.ac.filesystem.read` | Filesystem | Read files and directories |\n| `mcp.ac.filesystem.write` | Filesystem | Create or modify files and directories |\n| `mcp.ac.filesystem.delete` | Filesystem | Delete files and directories |\n| `mcp.ac.network.client` | Network | Make outbound network requests (HTTP, TCP, WebSocket) |\n| `mcp.ac.network.server` | Network | Listen for inbound connections (HTTP, SSE, gRPC) |\n| `mcp.ac.system.env.read` | System | Read environment variables and configuration |\n| `mcp.ac.system.exec` | System | Execute child processes and shell commands |\n\nThe vocabulary was validated against 296 real-world MCP servers (see [paper evaluation](#academic-reference)).\n\n## Usage\n\n### CLI\n\n```bash\n# List all permissions in the vocabulary\nagent-bound permissions\n\n# Validate a manifest file\nagent-bound validate ./agent-manifest.json\n\n# Inspect a manifest (human-readable output with effective policy)\nagent-bound inspect ./agent-manifest.json\n\n# Auto-generate a manifest from source code\nagent-bound generate ./my-mcp-server/ -o agent-manifest.json -d \"My server description\"\n\n# Launch an MCP server with enforcement\nagent-bound run ./agent-manifest.json -- node server.js\n```\n\n### Programmatic API\n\n#### Creating and validating manifests\n\n```typescript\nimport {\n  createManifest,\n  validateManifest,\n  saveManifest,\n  loadManifest,\n  FILESYSTEM_READ,\n  NETWORK_CLIENT,\n  SYSTEM_ENV_READ,\n} from \"agent-bound\";\n\n// Create a manifest\nconst manifest = createManifest(\n  \"My MCP server that reads config files and calls external APIs\",\n  [FILESYSTEM_READ, NETWORK_CLIENT, SYSTEM_ENV_READ],\n);\n\n// Validate arbitrary JSON\nconst result = validateManifest(someJsonData);\nif (!result.valid) {\n  console.error(result.errors);\n}\n\n// Persist and load\nawait saveManifest(manifest, \"./agent-manifest.json\");\nconst loaded = await loadManifest(\"./agent-manifest.json\");\n```\n\n#### Policy resolution and enforcement\n\n```typescript\nimport {\n  loadManifest,\n  resolvePolicy,\n  PermissionChecker,\n  AuditLog,\n} from \"agent-bound\";\n\nconst manifest = await loadManifest(\"./agent-manifest.json\");\n\n// Resolve generic permissions into scoped effective permissions\nconst effective = resolvePolicy(manifest, {\n  readPaths: [\"/data/project\"],\n  allowedHosts: [\"api.example.com\"],\n  envVars: [\"API_KEY\", \"NODE_ENV\"],\n});\n\n// Create a checker for runtime enforcement\nconst audit = new AuditLog();\nconst checker = new PermissionChecker(effective, audit);\n\nchecker.checkFileRead(\"/data/project/config.json\"); // true\nchecker.checkFileRead(\"/etc/passwd\");                // false\nchecker.checkNetworkClient(\"api.example.com\");       // true\nchecker.checkNetworkClient(\"evil.com\");              // false\nchecker.checkEnvRead(\"API_KEY\");                     // true\nchecker.checkEnvRead(\"DATABASE_URL\");                // false\n\n// Review denied attempts\nfor (const entry of audit.denied()) {\n  console.log(`DENIED: ${entry.permission} → ${entry.resource}`);\n}\n```\n\n#### Launching a sandboxed MCP server\n\n```typescript\nimport { loadManifest, createAgentBox } from \"agent-bound\";\n\nconst manifest = await loadManifest(\"./agent-manifest.json\");\n\nconst box = createAgentBox({\n  manifest,\n  command: [\"node\", \"my-mcp-server.js\"],\n  overrides: {\n    readPaths: [\"/data/shared\"],\n    allowedHosts: [\"api.example.com\"],\n    envVars: [\"API_KEY\"],\n  },\n});\n\n// The server process runs with a filtered environment\n// Only declared env vars are visible; PATH is restricted\n\n// Dynamic checks during operation\nbox.checker.checkFileRead(\"/data/shared/doc.txt\"); // true\n\n// Shut down\nbox.stop();\n\n// Review audit log\nconsole.log(box.audit.toJSON());\n```\n\n#### Auto-generating manifests from source code\n\n```typescript\nimport { generateManifest } from \"agent-bound\";\n\nconst result = await generateManifest(\"./path/to/mcp-server\", \"My MCP server\");\n\nconsole.log(`Scanned ${result.filesScanned} files`);\nfor (const detection of result.detections) {\n  console.log(`${detection.permission} (${detection.matchCount} matches)`);\n  console.log(`  Rationale: ${detection.rationale}`);\n}\n\nconsole.log(JSON.stringify(result.manifest, null, 2));\n```\n\n## Manifest Format\n\nAn `agent-manifest.json` file:\n\n```json\n{\n  \"description\": \"Filesystem MCP server with read-only access to project files.\",\n  \"permissions\": [\n    \"mcp.ac.filesystem.read\"\n  ]\n}\n```\n\nA more complete example (browser automation server):\n\n```json\n{\n  \"description\": \"Playwright MCP server providing browser automation. Launches browsers, navigates pages, takes screenshots, and writes artifacts to disk.\",\n  \"permissions\": [\n    \"mcp.ac.filesystem.read\",\n    \"mcp.ac.filesystem.write\",\n    \"mcp.ac.system.env.read\",\n    \"mcp.ac.network.client\",\n    \"mcp.ac.system.exec\"\n  ]\n}\n```\n\nSee [`examples/`](./examples/) for more manifest examples.\n\n## Generic vs. Effective Permissions\n\nThe framework uses a two-layer permission model:\n\n1. **Generic permissions** are declared in the manifest (`mcp.ac.filesystem.read`). They state *what kind* of access is needed.\n\n2. **Effective permissions** are resolved at launch time by the operator. They scope each generic permission to concrete resources:\n\n```typescript\n// Generic: \"this server needs filesystem read access\"\n// Effective: \"it can read /data/project and /tmp, nothing else\"\n\nconst effective = resolvePolicy(manifest, {\n  readPaths: [\"/data/project\", \"/tmp\"],\n  allowedHosts: [\"api.example.com\"],\n  envVars: [\"API_KEY\"],\n  listenPorts: [3000],\n  allowedCommands: [\"node\", \"npx\"],\n});\n```\n\nThis separation allows manifest authors to declare intent while operators maintain control over the actual scope.\n\n## Project Structure\n\n```\nagent-bound/\n├── src/\n│   ├── permissions.ts          # Permission vocabulary (mcp.ac.* constants)\n│   ├── index.ts                # Public API re-exports\n│   ├── manifest/\n│   │   ├── schema.ts           # AgentManifest types and validation\n│   │   └── index.ts            # Manifest I/O (load, save, create)\n│   ├── box/\n│   │   ├── policy.ts           # Generic → effective permission resolution\n│   │   ├── sandbox.ts          # Process sandbox launcher\n│   │   ├── checker.ts          # Runtime permission checker\n│   │   ├── audit.ts            # Audit logging\n│   │   └── index.ts            # AgentBox high-level API\n│   ├── gen/\n│   │   ├── heuristics.ts       # Source-code pattern detection\n│   │   └── index.ts            # Manifest generation pipeline\n│   └── cli/\n│       └── index.ts            # CLI entry point\n├── tests/                      # Vitest test suite\n├── examples/                   # Example manifests and usage code\n├── package.json\n└── tsconfig.json\n```\n\n## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run build        # Compile TypeScript\nnpm test             # Run tests\nnpm run dev          # Watch mode compilation\n```\n\n## Limitations\n\n- **Process-level enforcement only.** The current sandbox filters the environment and restricts PATH but does not use OS-level isolation (namespaces, seccomp, cgroups). For stronger guarantees, run within a container runtime.\n- **Static heuristic analysis.** `AgentManifestGen` uses pattern matching, not full program analysis. It may produce false positives or miss permissions accessed through dynamic patterns.\n- **No runtime interception.** The `PermissionChecker` is advisory — it evaluates whether an action *should* be allowed, but does not intercept syscalls. Pair with a real sandbox for enforcement.\n\n## Academic Reference\n\nThis project is inspired by:\n\n\u003e Christoph Bühler, Matteo Biagiola, Luca Di Grazia, and Guido Salvaneschi.\n\u003e **\"Securing AI Agent Execution.\"**\n\u003e arXiv preprint arXiv:2510.21236, 2025.\n\u003e [https://arxiv.org/abs/2510.21236](https://arxiv.org/abs/2510.21236)\n\nThe paper introduces AgentBound, the first access control framework for MCP servers, combining a declarative policy mechanism (inspired by the Android permission model) with a policy enforcement engine. Their evaluation on 296 popular MCP servers showed that manifests can be auto-generated with 80.9% accuracy, the permission vocabulary covers 100% of real-world requirements, and enforcement overhead is negligible (0.6 ms average).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdortort%2Fagent-bound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdortort%2Fagent-bound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdortort%2Fagent-bound/lists"}