AgentsID Guard

<p align="center"> <h1 align="center">AgentsID Guard</h1> <p align="center"> <strong>One MCP server. Every operation protected.</strong> </p> </p>

<p align="center"> <a href="https://agentsid.dev"><img src="https://img.shields.io/badge/powered%20by-AgentsID-f59e0b?style=flat-square" alt="AgentsID" /></a> <a href="https://github.com/AgentsID-dev/shell-guard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-f59e0b?style=flat-square" alt="License" /></a> </p>

---

Your AI agent has access to your shell, file system, database, git repos, and the internet. Right now, nothing controls what it can do with any of them.

AgentsID Guard fixes that. 11 tools across 5 categories — shell, files, database, git, HTTP — every operation validated against per-agent permission rules before execution.

How It Works

Agent: shell_run("ls -la /src")
  → Classified: shell.read.ls
  → AgentsID: ALLOWED ✓
  → Executes normally

Agent: shell_run("rm -rf /data")
  → Classified: shell.danger.rm
  → AgentsID: BLOCKED ✗
  → Never executes

Agent: db_query("DROP TABLE users")
  → Classified: db.danger.ddl
  → AgentsID: BLOCKED ✗
  → Never executes

Agent: git_run("push origin main")
  → Classified: git.write.push
  → AgentsID: BLOCKED ✗
  → Never executes

Quick Start

1. Install

npx @agentsid/guard

2. Get your keys

Sign up at agentsid.dev/dashboard — free tier: 25 agents, 10K events/month.

3. Add to Claude Code

claude mcp add guard \
  -e AGENTSID_PROJECT_KEY=aid_proj_your_key \
  -e AGENTSID_AGENT_TOKEN=aid_tok_your_token \
  -- npx @agentsid/guard

4. Set permissions

npx agentsid register-agent --name "my-agent" \
  --permissions "shell.read.*" "file.read" "file.list" "git.read.*" "http.get"

Tools

AgentsID Guard exposes 11 MCP tools:

Tool	What it does	Permission pattern
shell_run	Execute a shell command	shell.read.*, shell.write.*, shell.danger.*, shell.admin.*
file_read	Read a file	file.read
file_write	Write/create a file	file.write
file_delete	Delete a file	file.delete
file_list	List directory contents	file.list
file_info	Get file metadata	file.info
db_query	Run a SQL query	db.read, db.write.*, db.danger.*
git_run	Run a git command	git.read.*, git.write.*, git.danger.*
http_request	Make an HTTP request	http.get, http.post, http.put, http.delete
check_permission	Check if an action would be allowed	—
list_categories	List all permission categories	—

Permission Categories

Shell

Pattern	Commands	Risk
shell.read.*	ls, cat, grep, find, ps, df, curl, ping	Safe
shell.write.*	mkdir, touch, cp, mv	Moderate
shell.danger.*	rm, chmod, chown, kill	High
shell.admin.*	sudo, docker, apt, npm, systemctl	Critical

Files

Pattern	Operations	Risk
file.read	Read file contents	Safe
file.list	List directories	Safe
file.info	File metadata	Safe
file.write	Create/write files	Moderate
file.delete	Delete files	High

Database

Pattern	Statements	Risk
db.read	SELECT, SHOW, DESCRIBE, EXPLAIN	Safe
db.write.insert	INSERT	Moderate
db.write.update	UPDATE	Moderate
db.write.create	CREATE	Moderate
db.danger.delete	DELETE	High
db.danger.ddl	DROP, TRUNCATE, ALTER	Critical

Git

Pattern	Commands	Risk
git.read.*	status, log, diff, branch, show, blame	Safe
git.write.*	add, commit, push, pull, merge, checkout, stash	Moderate
git.danger.*	reset, force-push	Critical

HTTP

Pattern	Methods	Risk
http.get	GET	Safe
http.post	POST	Moderate
http.put	PUT	Moderate
http.delete	DELETE	High

Permission Examples

Read-only research agent:

shell.read.*    → allow
file.read       → allow
file.list       → allow
db.read         → allow
git.read.*      → allow
http.get        → allow

Developer agent (read + write, no destructive):

shell.read.*    → allow
shell.write.*   → allow
file.read       → allow
file.write      → allow
file.list       → allow
db.read         → allow
db.write.*      → allow
git.read.*      → allow
git.write.*     → allow
http.get        → allow
http.post       → allow

Full access with approval gates:

shell.read.*    → allow
shell.write.*   → allow
shell.danger.*  → allow (requires approval)
shell.admin.*   → allow (requires approval)
file.*          → allow
db.read         → allow
db.write.*      → allow
db.danger.*     → allow (requires approval)
git.*           → allow
http.*          → allow

Environment Variables

Variable	Required	Description
AGENTSID_PROJECT_KEY	Yes	Your AgentsID project key
AGENTSID_AGENT_TOKEN	Yes	Agent token for permission checks
AGENTSID_BASE_URL	No	API URL (default: https://agentsid.dev)
GUARD_CWD	No	Working directory (default: cwd)
GUARD_TIMEOUT	No	Command timeout in ms (default: 30000)
GUARD_ALLOWED_DIRS	No	Comma-separated allowed directories for file ops (default: cwd)
GUARD_DB_URL	No	Database connection string for db_query (postgresql://, mysql://, or .db path)

Security

• Deny-first — unknown commands and tools are blocked by default
• Path containment — file operations restricted to allowed directories
• Fail-closed — network errors to AgentsID result in denial, not bypass
• Audit trail — every allow and deny logged to AgentsID's tamper-evident hash chain
• No shell injection — commands executed via execSync with no shell interpolation of user input in tool arguments

Dashboard

Every operation appears in your AgentsID dashboard:

• Which agent ran which command
• Whether it was allowed or denied and why
• Full audit trail across all 5 categories

Links

• AgentsID — Identity & auth for AI agents
• Documentation
• Dashboard

License

MIT