Metadata-Version: 2.4
Name: agentperms
Version: 0.1.0
Summary: Least-privilege permissions for AI agents and MCP tools. Record what your agent does, auto-generate a safe policy, and block dangerous tool calls before they happen.
Project-URL: Homepage, https://github.com/hasanmehmood/agentperms
Project-URL: Repository, https://github.com/hasanmehmood/agentperms
Project-URL: Issues, https://github.com/hasanmehmood/agentperms/issues
Author-email: Hassan Mehmood <hassan@boostpanda.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,least-privilege,mcp,permissions,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.110; extra == 'dashboard'
Requires-Dist: uvicorn>=0.29; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# AgentPerms

**Least-privilege permissions for AI agents and MCP tools. Record what your agent does, auto-generate a safe policy, and block dangerous tool calls before they happen.**

> Your AI agent has sudo. AgentPerms takes it away.

MCP is becoming the standard way AI apps connect to tools and data — which means agents are getting access to your filesystem, your repos, your email, and your database faster than anyone can govern them. Scanners tell you something *looks* risky. Firewalls make you hand-write YAML. AgentPerms does the missing thing:

> **record → infer → lock → replay → enforce**

Run your agent in dev, record every tool call, infer the *minimum* permissions it actually needed, generate a policy, prove it blocks attacks, and enforce it in CI and at runtime.

## Install

```bash
pip install agentperms
```

## The flow

```bash
agentperms scan                  # find MCP configs, flag risky tools & exposures
agentperms lock                  # pin every tool's identity (detect tool poisoning)
agentperms record --client cursor  # route the client through the recording proxy
#   ... use your agent normally ...
agentperms infer                 # traces  -> mcp.policy.yaml (least privilege)
agentperms enforce               # route the client through the blocking proxy
agentperms replay                # prove the policy blocks a pack of attacks
agentperms report                # agentperms-report.html
agentperms init                  # .github/workflows/agentperms.yml
```

It produces `mcp.policy.yaml`, `mcp.lock`, `agentperms-report.html`, and a CI workflow.

## The killer command

```bash
agentperms infer
```

> *Your agent only used read-only GitHub calls and local `./src` access. I generated a least-privilege policy. The agent does not need shell, home directory, secrets, Gmail send, or database write access.*

## How enforcement works

AgentPerms is a transparent **stdio proxy**. `record`/`enforce` rewrite your MCP client's config so each server launches through `agentperms _proxy`:

```
Agent  →  AgentPerms proxy  →  MCP server
              │
              ├─ record:  log every tools/call
              └─ enforce: allow / deny / require-approval before forwarding
```

Denied calls never reach the server — the client gets a clean JSON-RPC error. Approval-gated calls prompt on your terminal.

## Try it offline

A bundled over-privileged demo server lets you see a real block with no setup:

```bash
agentperms scan --path examples/vulnerable-mcp-demo   # flags ~/.ssh mount + unpinned npx
agentperms replay --policy examples/policies/example.mcp.policy.yaml
```

## Example policy

```yaml
version: 1
servers:
  github:
    allowed_tools: [list_repos, read_file, create_issue]
    denied_tools: [delete_repo, write_secret, force_push]
  filesystem:
    allowed_paths: [./src, ./docs]
    denied_paths: [~/.ssh, ~/.env, /etc]
    denied_patterns: ["*.pem", "*.key"]
approvals:
  require_human_approval: [gmail.send_email, github.merge_pr, shell.exec]
redaction: { secrets: true, emails: true, api_keys: true }
```

## Status

v0.1 — supports Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Gemini CLI configs and local stdio MCP servers. Roadmap: HTTP/SSE transport, a Node wrapper, and a live dashboard.

## License

MIT
