{"_id":"@b1ttsteel/agent-shield","name":"@b1ttsteel/agent-shield","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@b1ttsteel/agent-shield","version":"0.1.0","description":"Firewall and audit logger for MCP agent-to-tool connections — intercept, log, and enforce policies on every tool call your AI agents make","type":"module","bin":{"agent-shield":"dist/index.js"},"main":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","dev":"tsx src/index.ts","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"eslint src/ test/","typecheck":"tsc --noEmit","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","prepublishOnly":"npm run clean && npm run build && npm test"},"keywords":["mcp","ai-agents","security","firewall","audit-log","claude-code","cursor","windsurf","proxy","observability","model-context-protocol"],"author":{"name":"AgentShield Contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/inprod/agent-shield.git"},"homepage":"https://github.com/inprod/agent-shield#readme","bugs":{"url":"https://github.com/inprod/agent-shield/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","chalk":"^5.3.0","chokidar":"^3.6.0","commander":"^12.1.0","eventsource":"^4.1.0","express":"^5.2.1","uuid":"^10.0.0","yaml":"^2.5.0","zod":"^3.23.0"},"optionalDependencies":{"better-sqlite3":"^12.8.0"},"devDependencies":{"@types/better-sqlite3":"^7.6.13","@types/eventsource":"^1.1.15","@types/express":"^5.0.6","@types/node":"^20.14.0","@types/uuid":"^10.0.0","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.57.0","tsx":"^4.16.0","typescript":"^5.5.0","vitest":"^1.6.0"},"_id":"@b1ttsteel/agent-shield@0.1.0","gitHead":"66ac00a265a582e98785eecd697205c65a84f4b6","types":"./dist/index.d.ts","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-NX+iYzlMezWF16Vj0TfOk24U1YyxQ317bXHhKzEAV86a+pidH1EZ8OPVDpmn+4dvQWAhrjn1QNgjoHxph9VdXQ==","shasum":"c35a532e90a674c4aec2567a494a89ae31885648","tarball":"https://registry.npmjs.org/@b1ttsteel/agent-shield/-/agent-shield-0.1.0.tgz","fileCount":138,"unpackedSize":280878,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBMX8g9OxeBLm9Jer+NhCQGYfxn5hUnhKp+srI+e0QHpAiAGsSbvwHW6/jYJAZlQ4a5HBgFZObqMEYf3QtgcUh12yA=="}]},"_npmUser":{"name":"b1ttsteel","email":"brigen.tafilica@hotmail.fr"},"directories":{},"maintainers":[{"name":"b1ttsteel","email":"brigen.tafilica@hotmail.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-shield_0.1.0_1774568228947_0.38913869937765266"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-26T23:37:08.878Z","0.1.0":"2026-03-26T23:37:09.080Z","modified":"2026-03-26T23:37:09.248Z"},"maintainers":[{"name":"b1ttsteel","email":"brigen.tafilica@hotmail.fr"}],"description":"Firewall and audit logger for MCP agent-to-tool connections — intercept, log, and enforce policies on every tool call your AI agents make","homepage":"https://github.com/inprod/agent-shield#readme","keywords":["mcp","ai-agents","security","firewall","audit-log","claude-code","cursor","windsurf","proxy","observability","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/inprod/agent-shield.git"},"author":{"name":"AgentShield Contributors"},"bugs":{"url":"https://github.com/inprod/agent-shield/issues"},"license":"MIT","readme":"# AgentShield\n\n**A firewall and audit log for AI agents.**\n\nAgentShield sits between your AI agents and the tools they use. It intercepts every tool call, enforces allow/deny policies, rate-limits dangerous operations, and logs everything — so you know exactly what your agents are doing.\n\nWorks with **Claude Code**, **Cursor**, **Windsurf**, and any custom MCP-based agent.\n\n> You wouldn't deploy an API without rate limiting. Why are your agents different?\n\n---\n\n## What It Does\n\n```\n┌─────────────┐     ┌──────────────────────────────────────────┐     ┌─────────────┐\n│  AI Agent    │     │             AgentShield Proxy             │     │  MCP Server  │\n│ (Claude Code │────▶│                                          │────▶│  (GitHub,    │\n│  Cursor,     │◀────│  Intercept → Policy Check → Log → Route  │◀────│   Jira,      │\n│  Custom)     │     │                                          │     │   Slack...)   │\n└─────────────┘     └──────────────────────────────────────────┘     └─────────────┘\n                              │           │           │\n                              ▼           ▼           ▼\n                         ┌────────┐ ┌─────────┐ ┌──────────┐\n                         │ Policy │ │  Audit   │ │Dashboard │\n                         │ Engine │ │   Log    │ │   API    │\n                         └────────┘ └─────────┘ └──────────┘\n```\n\nThree interception layers:\n- **MCP tool calls** — intercept any MCP server (GitHub, Jira, Slack, filesystem, etc.)\n- **CLI commands** — intercept shell commands agents run (`rm -rf`, `git push --force`, etc.)\n- **HTTP requests** — intercept outbound HTTP (block exfil domains, scan for secret leaks)\n\n---\n\n## Quick Start (5 minutes)\n\n### 1. Install\n\n```bash\nnpm install -g agent-shield\n```\n\n### 2. Create a policy file\n\nCreate `agent-shield.yaml` in your project root:\n\n```yaml\nversion: \"1\"\n\nsettings:\n  log_level: \"info\"\n  log_file: \"./agent-shield-audit.log\"\n  redact_secrets: true\n\nservers:\n  - name: \"github\"\n    command: \"npx\"\n    args: [\"-y\", \"@modelcontextprotocol/server-github\"]\n    env:\n      GITHUB_TOKEN: \"${GITHUB_TOKEN}\"\n\nrules:\n  # Block dangerous operations\n  - name: \"block-destructive-git\"\n    action: deny\n    servers: [\"github\"]\n    tools: [\"push_files\", \"delete_branch\", \"delete_repository\"]\n    message: \"Destructive git operations are blocked\"\n\n  # Rate limit writes to 20/min\n  - name: \"rate-limit-writes\"\n    action: allow\n    tools: [\"write_file\"]\n    rate_limit:\n      max_calls: 20\n      window_seconds: 60\n\n  # Allow reads freely\n  - name: \"allow-reads\"\n    action: allow\n    tools: [\"read_file\", \"search_files\", \"list_directory\"]\n\n  # Log anything else for review\n  - name: \"warn-unknown\"\n    action: warn\n    message: \"Unrecognized tool — logged for review\"\n\n  # Block everything not matched above\n  - name: \"default-deny\"\n    action: deny\n    message: \"Not explicitly permitted by policy\"\n```\n\n### 3. Validate your policy\n\n```bash\nagent-shield policy validate\n# ✓ Policy is valid (5 rules loaded)\n```\n\n### 4. Connect your agent\n\n**Claude Code** — update `~/.claude/config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"agent-shield\",\n      \"args\": [\"start\", \"--server\", \"github\", \"--config\", \"./agent-shield.yaml\"]\n    }\n  }\n}\n```\n\n**Cursor** — update `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"agent-shield\",\n      \"args\": [\"start\", \"--server\", \"github\", \"--config\", \"./agent-shield.yaml\"]\n    }\n  }\n}\n```\n\nThat's it. Every tool call now goes through AgentShield's policy engine.\n\n---\n\n## Examples\n\n### Block an agent from deleting repos but allow reading issues\n\n```yaml\nrules:\n  - name: \"block-destructive\"\n    action: deny\n    tools: [\"delete_repository\", \"delete_branch\", \"push_files\"]\n    message: \"Destructive operations are not allowed\"\n\n  - name: \"allow-read-ops\"\n    action: allow\n    tools: [\"get_issue\", \"search_issues\", \"list_repos\", \"read_file\"]\n\n  - name: \"default-deny\"\n    action: deny\n    message: \"Not permitted\"\n```\n\n### Rate limit an agent to 10 file writes per minute\n\n```yaml\nrules:\n  - name: \"rate-limit-writes\"\n    action: allow\n    tools: [\"write_file\", \"create_file\"]\n    rate_limit:\n      max_calls: 10\n      window_seconds: 60\n\n  - name: \"allow-reads\"\n    action: allow\n    tools: [\"read_file\", \"search_files\"]\n\n  - name: \"default-deny\"\n    action: deny\n```\n\n### Proxy multiple MCP servers with different policies\n\n```yaml\nservers:\n  - name: \"github\"\n    command: \"npx\"\n    args: [\"-y\", \"@modelcontextprotocol/server-github\"]\n    env:\n      GITHUB_TOKEN: \"${GITHUB_TOKEN}\"\n\n  - name: \"filesystem\"\n    command: \"npx\"\n    args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"./workspace\"]\n\n  - name: \"linear\"\n    url: \"https://mcp.linear.app/sse\"\n    headers:\n      Authorization: \"Bearer ${LINEAR_TOKEN}\"\n\nrules:\n  # GitHub: read-only\n  - name: \"github-read-only\"\n    action: deny\n    servers: [\"github\"]\n    tools: [\"push_files\", \"create_branch\", \"delete_branch\"]\n    message: \"GitHub is read-only through AgentShield\"\n\n  # Filesystem: allow reads, rate-limit writes\n  - name: \"fs-allow-reads\"\n    action: allow\n    servers: [\"filesystem\"]\n    tools: [\"read_file\", \"list_directory\", \"search_files\"]\n\n  - name: \"fs-limit-writes\"\n    action: allow\n    servers: [\"filesystem\"]\n    tools: [\"write_file\"]\n    rate_limit:\n      max_calls: 30\n      window_seconds: 60\n\n  # Linear: allow everything (trusted)\n  - name: \"linear-allow-all\"\n    action: allow\n    servers: [\"linear\"]\n\n  # Default deny\n  - name: \"default-deny\"\n    action: deny\n    message: \"Not explicitly permitted\"\n```\n\n### Match on tool arguments with regex\n\n```yaml\nrules:\n  # Block writes to production paths\n  - name: \"block-prod-writes\"\n    action: deny\n    tools: [\"write_file\"]\n    args_match:\n      path: \"/prod/|/production/\"\n    message: \"Cannot write to production paths\"\n\n  # Allow writes elsewhere\n  - name: \"allow-writes\"\n    action: allow\n    tools: [\"write_file\"]\n```\n\n---\n\n## Beyond MCP: CLI Command Interception\n\nAgents don't just call MCP tools — they run shell commands too. AgentShield can intercept those as well.\n\n### Dry-run a command against policy\n\n```bash\nagent-shield exec --dry-run \"rm -rf /\"\n# ✗ DENY: \"rm -rf /\" — Destructive file operations blocked (rule: block-destructive)\n\nagent-shield exec --dry-run \"git status\"\n# ✓ ALLOW: \"git status\" (rule: allow-safe-commands)\n\nagent-shield exec --dry-run \"docker run ubuntu\"\n# ⚠ WARN: \"docker run ubuntu\" — Docker command detected (rule: warn-docker)\n```\n\n### Run a command through the policy engine\n\n```bash\nagent-shield exec \"git status\"    # runs if allowed\nagent-shield exec \"rm -rf /\"     # blocked — exits with code 1\n```\n\n### Claude Code hook integration\n\nAgentShield can generate a Claude Code `PreToolUse` hook that automatically intercepts every `Bash` tool call:\n\n```bash\n# See the hook config\nagent-shield hook show\n\n# Test what the hook would do\nagent-shield hook test \"kubectl delete pod --all\"\n```\n\nAdd the output of `agent-shield hook show` to your `.claude/settings.json` and every shell command Claude Code runs will go through policy.\n\n**Default command rules block:**\n- `rm -rf`, destructive filesystem ops\n- `git push --force`, `git reset --hard`\n- System commands (`shutdown`, `dd`, `mkfs`)\n- Data exfiltration via `curl`/`wget`\n\n---\n\n## Beyond MCP: HTTP Request Interception\n\nAgentShield can also act as an HTTP forward proxy — intercepting outbound requests, blocking dangerous domains, and scanning request bodies for leaked secrets.\n\n### Check a URL against policy\n\n```bash\nagent-shield http-check https://pastebin.com/raw/abc\n# ✗ DENY — Request to known data exfiltration domain blocked\n\nagent-shield http-check https://api.github.com/repos\n# ✓ ALLOW (rule: allow-dev-domains)\n\nagent-shield http-check https://random-site.xyz\n# ⚠ WARN — HTTP request to unrecognized domain\n\nagent-shield http-check -m POST -b '{\"key\":\"AKIAIOSFODNN7EXAMPLE\"}' https://api.example.com\n# ✗ DENY — Request body contains potential secrets\n```\n\n### Start the HTTP proxy\n\n```bash\nagent-shield http-proxy --port 8080\n```\n\nThen route agent traffic through it:\n\n```bash\nHTTP_PROXY=http://localhost:8080 HTTPS_PROXY=http://localhost:8080 your-agent\n```\n\n**Default HTTP rules block:**\n- Exfiltration domains (pastebin, ngrok, webhook.site, requestbin, etc.)\n- File uploads (`multipart/form-data`) to external services\n- Secret leaks in request bodies (AWS keys, GitHub PATs, private keys, Stripe/OpenAI keys)\n\n**Allows:**\n- Dev domains (GitHub, npm, PyPI, localhost)\n- AI/cloud APIs (OpenAI, Anthropic, Google, AWS, Azure)\n\n---\n\n## Web Dashboard\n\n```bash\nagent-shield dashboard\n# ✓ Dashboard running at http://localhost:4040\n```\n\nProvides:\n- **Live Feed** — Real-time stream of every tool call with policy decisions\n- **Analytics** — Total calls, allow/deny/warn breakdown, top tools, latency\n- **Anomaly Alerts** — Volume spikes, new tool access, off-hours activity, high deny rates\n- **Policy Reference** — Quick view of your current rules\n\nThe dashboard reads from SQLite, so it works even when the proxy isn't running. (Requires optional `better-sqlite3` — see [Optional Dependencies](#optional-dependencies)).\n\n---\n\n## Audit Log\n\nEvery intercepted call is logged as structured JSON:\n\n```json\n{\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\",\n  \"server_name\": \"github\",\n  \"agent_id\": \"claude-code\",\n  \"method\": \"tools/call\",\n  \"tool_name\": \"create_issue\",\n  \"arguments\": { \"project\": \"PROD\", \"title\": \"Fix bug\" },\n  \"result_preview\": \"Created issue PROD-123\",\n  \"policy_decision\": \"allow\",\n  \"policy_rule\": \"allow-reads\",\n  \"latency_ms\": 142,\n  \"error\": null\n}\n```\n\n- Secrets are **automatically redacted** before logging (AWS keys, GitHub tokens, Slack tokens, API keys, passwords, emails)\n- Log file is structured JSON (one entry per line) — pipe to `jq`, Datadog, or any log aggregator\n- Policy file changes are **hot-reloaded** — no restart needed\n\n### Query logs with CLI\n\n```bash\nagent-shield logs                             # Show recent entries\nagent-shield logs --filter write_file         # Filter by tool name\nagent-shield logs --action deny               # Show only blocked calls\nagent-shield logs --server github --json      # JSON output for piping\n```\n\n---\n\n## All CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-shield start --server <name>` | Start the MCP proxy (called by agent config) |\n| `agent-shield logs` | View audit log entries |\n| `agent-shield policy validate` | Validate your policy file |\n| `agent-shield dashboard` | Launch web dashboard |\n| `agent-shield exec <command>` | Run a shell command through policy |\n| `agent-shield exec --dry-run <command>` | Check if a command would be allowed |\n| `agent-shield hook show` | Show Claude Code hook config |\n| `agent-shield hook test <command>` | Test hook policy for a command |\n| `agent-shield http-proxy --port <port>` | Start HTTP forward proxy |\n| `agent-shield http-check <url>` | Check a URL against HTTP policy |\n\n---\n\n## Policy Rule Reference\n\nRules are evaluated top-to-bottom. **First match wins** (like iptables/nginx).\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Human-readable rule name |\n| `action` | `allow` \\| `deny` \\| `warn` | What to do when matched |\n| `servers` | string[] | Match specific servers (omit = all) |\n| `tools` | string[] | Match specific tools (omit = all) |\n| `args_match` | object | Regex matching on tool arguments |\n| `rate_limit` | `{ max_calls, window_seconds }` | Rate limiting (only with `allow`) |\n| `time_window` | `{ start, end, timezone }` | Time-of-day restrictions (HH:MM) |\n| `message` | string | Shown on deny, logged on warn |\n\n### Actions\n\n- **`allow`** — permit the call and log it\n- **`deny`** — block the call, return an error to the agent, and log it\n- **`warn`** — permit the call but flag it for review in logs/dashboard\n\n---\n\n## Features\n\n- **Policy enforcement** — Allow/deny/warn rules with first-match-wins evaluation\n- **Rate limiting** — Per-tool call limits with configurable time windows\n- **Audit logging** — Structured JSON logs, queryable via CLI\n- **SQLite storage** — Queryable audit data for dashboard and analytics (optional)\n- **Secret redaction** — Auto-redacts API keys, tokens, passwords, emails before logging\n- **Hot-reload** — Edit your policy file and changes apply instantly, no restart needed\n- **Web dashboard** — Real-time feed, analytics, top tools, anomaly alerts\n- **Anomaly detection** — Volume spikes, new tools, off-hours activity, high deny rates\n- **CLI command interception** — Intercept shell commands agents run, not just MCP\n- **HTTP request interception** — Forward proxy with domain blocking and secret leak scanning\n- **Claude Code hooks** — Drop-in PreToolUse hook for Bash tool interception\n- **SSE transport** — Proxy remote MCP servers over HTTP (not just local stdio)\n- **Works with any agent** — Claude Code, Cursor, Windsurf, or custom agents\n\n---\n\n## Optional Dependencies\n\nAgentShield works out of the box with zero native dependencies. Some features require optional packages:\n\n| Feature | Package | Install |\n|---------|---------|---------|\n| Dashboard + SQLite storage | `better-sqlite3` | `npm install better-sqlite3` |\n\nIf `better-sqlite3` is not installed, AgentShield still works — it just uses JSON file logging instead of SQLite, and the dashboard won't be available.\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/inprod/agent-shield.git\ncd agent-shield\nnpm install\nnpm test        # 146 tests\nnpm run build   # compile TypeScript\n```\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-4f03cc3b06769c97fdf4f0a3d22dbff8"}