{"id":50649100,"url":"https://github.com/flyingsquirrel0419/warden-cli","last_synced_at":"2026-06-07T16:02:08.520Z","repository":{"id":353707802,"uuid":"1219668613","full_name":"flyingsquirrel0419/warden-cli","owner":"flyingsquirrel0419","description":"Local-first security gateway CLI for MCP servers","archived":false,"fork":false,"pushed_at":"2026-04-25T17:08:09.000Z","size":283,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T18:24:42.401Z","etag":null,"topics":["audit-log","cli","developer-tools","local-first","mcp","mcp-client","mcp-server","model-context-protocol","nodejs","policy-engine","prompt-injection","proxy","security","ssrf-protection","typescript","warden","warden-cli"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingsquirrel0419.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","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-04-24T05:27:13.000Z","updated_at":"2026-04-25T17:07:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flyingsquirrel0419/warden-cli","commit_stats":null,"previous_names":["flyingsquirrel0419/mcp-warden","flyingsquirrel0419/warden-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/flyingsquirrel0419/warden-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingsquirrel0419%2Fwarden-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingsquirrel0419%2Fwarden-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingsquirrel0419%2Fwarden-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingsquirrel0419%2Fwarden-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingsquirrel0419","download_url":"https://codeload.github.com/flyingsquirrel0419/warden-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingsquirrel0419%2Fwarden-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34027670,"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-07T02:00:07.652Z","response_time":124,"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":["audit-log","cli","developer-tools","local-first","mcp","mcp-client","mcp-server","model-context-protocol","nodejs","policy-engine","prompt-injection","proxy","security","ssrf-protection","typescript","warden","warden-cli"],"created_at":"2026-06-07T16:02:07.456Z","updated_at":"2026-06-07T16:02:08.513Z","avatar_url":"https://github.com/flyingsquirrel0419.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://img.shields.io/badge/🛡️-MCP%20Warden-4A90D9?style=for-the-badge\u0026labelColor=1a1a2e\" alt=\"Warden CLI\" /\u003e\n\n# Warden CLI\n\n**The security gateway your MCP setup didn't know it needed.**\n\n[![CI](https://github.com/flyingsquirrel0419/warden-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/flyingsquirrel0419/warden-cli/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/warden-cli?color=cb3837\u0026label=npm)](https://www.npmjs.com/package/warden-cli)\n[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n\nMCP tools can read your files, run shell commands, and hit any URL on the internet.\n**Warden sits in the middle and makes sure they only do what you said they could.**\n\n[Quick Start](#-quick-start) · [How It Works](#-how-it-works) · [Policy Files](#-policy-files) · [CLI Reference](#-cli-reference) · [Docs](#-documentation)\n\n\u003c/div\u003e\n\n---\n\n## The Problem\n\nWhen you wire up an MCP server to Claude or Cursor, you're handing it power over your local environment. Most servers are trustworthy — but:\n\n- **You can't see what tools are being called** or what arguments they receive.\n- **Over-broad tools** can accidentally (or deliberately) access things they shouldn't.\n- **Prompt injection attacks** can trick an AI into misusing a tool.\n- **No audit trail** means you can't reconstruct what happened after the fact.\n\nWarden CLI solves all of this without changing how your AI client works.\n\n---\n\n## ✨ What It Does\n\n| Problem | What Warden does |\n|---|---|\n| 🔍 **No visibility** | Logs every tool call and result to a local SQLite database |\n| 🚫 **Over-permissioned tools** | Allow-lists and block-lists per server, per tool |\n| 💉 **Prompt injection** | Heuristic detector warns or blocks suspicious outputs |\n| 🔗 **SSRF via tool args** | Blocks URL-like arguments targeting local network ranges |\n| 🔑 **Secrets in logs** | Masks sensitive fields before writing to disk |\n| 📊 **No audit trail** | Local dashboard with log explorer, stats, and analytics |\n| 🏃 **Unknown new tools** | Detects and alerts when a server exposes a new tool |\n| ⚡ **Rate abuse** | Per-server, per-tool rate limiting |\n| 🔏 **Untrusted policy repos** | SSH signature verification for synced policy files |\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Install globally\nnpm install -g warden-cli\n\n# Step 1: Scan a server before you trust it\nwarden scan --target \"npx @some/mcp-server\"\n\n# Step 2: Auto-discover existing MCP configs\nwarden discover\n\n# Step 3: Open the dashboard to see what's happening\nwarden dashboard\n# → http://localhost:4242\n```\n\nOr jump straight to proxying a specific server:\n\n```bash\nwarden proxy \\\n  --target \"npx @some/mcp-server\" \\\n  --name my-server \\\n  --policy ~/.warden/policy.yaml\n```\n\nWhen the discovered config looks right, run `warden discover --wrap` to route those servers through Warden.\n\n\u003e **No account. No cloud. No telemetry.** Everything stays on your machine.\n\n---\n\n## 🏗️ How It Works\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                     Your Machine                         │\n│                                                         │\n│  ┌──────────┐    ┌──────────────┐    ┌───────────────┐  │\n│  │  Claude  │───▶│  Warden CLI  │───▶│  MCP Server   │  │\n│  │  Cursor  │    │              │    │  (filesystem,  │  │\n│  │  etc.    │◀───│  ✓ Policy    │◀───│  shell, fetch, │  │\n│  └──────────┘    │  ✓ Security  │    │  etc.)         │  │\n│                  │  ✓ Audit log │    └───────────────┘  │\n│                  └──────────────┘                       │\n│                        │                                │\n│                  ┌──────────────┐                       │\n│                  │  Dashboard   │  localhost:4242        │\n│                  │  SQLite DB   │  ~/.warden/       │\n│                  └──────────────┘                       │\n└─────────────────────────────────────────────────────────┘\n```\n\nEvery tool call flows through Warden's pipeline:\n\n1. **Policy check** — is this tool/server allowed in the configured mode?\n2. **SSRF guard** — do any arguments contain suspicious URLs?\n3. **Forward** — send the call to the real MCP server.\n4. **Output inspection** — scan the result for injection patterns or data leaks.\n5. **Audit write** — record the full decision to SQLite (with secrets masked).\n6. **Return** — pass the result back to the AI client.\n\nIf a step blocks the call, the client gets a clean MCP error response — not a crash.\n\n---\n\n## 📋 Policy Files\n\nPolicy lives in a YAML file at `~/.warden/policy.yaml`. Here's a complete example:\n\n```yaml\nversion: 1\n\ndefaults:\n  mode: audit-only        # passthrough | audit-only | enforcing\n  alert_on_new_tool: true\n\nservers:\n  # Strict mode for an untrusted community server\n  community-tools:\n    mode: enforcing\n    allowed_tools:\n      - search\n      - summarize\n    blocked_tools:\n      - delete_file\n      - run_shell\n    rate_limit:\n      per_minute: 20\n      per_hour: 200\n    rules:\n      - name: no-token-input\n        description: Block calls that pass raw tokens as arguments.\n        match:\n          input:\n            token:\n              pattern: \".+\"\n        action: block\n        message: Token input is not allowed on this server.\n\n  # Audit-only for a trusted internal tool\n  my-notes:\n    mode: audit-only\n```\n\n### Policy Modes\n\n| Mode | What happens |\n|---|---|\n| `passthrough` | Warden is transparent — calls go through, nothing is blocked |\n| `audit-only` | Calls go through, policy violations are **logged** but not blocked |\n| `enforcing` | Policy violations are **blocked** with an MCP error response |\n\nStart with `audit-only` to learn what your servers do, then move to `enforcing` when you're confident.\n\n---\n\n## 💻 CLI Reference\n\n```bash\nwarden \u003ccommand\u003e [options]\n```\n\n| Command | What it does |\n|---|---|\n| `proxy --target \u003ccmd\u003e` | Start the security gateway for an MCP server |\n| `scan --target \u003ccmd\u003e` | Inspect a server's tools and estimate risk before connecting |\n| `discover` | Find MCP servers in Claude Desktop, Cursor, and `.mcp.json` |\n| `discover --wrap` | Rewrite discovered configs to route through Warden |\n| `init` | Interactively wrap existing MCP client configurations |\n| `status` | Show recent audit log entries |\n| `log` | Query audit logs with filters |\n| `dashboard` | Start the local web dashboard (`--port` to override 4242) |\n| `policy sync` | Sync policy files from a Git repo |\n| `policy list` | List synced policy files |\n| `policy apply` | Apply a synced policy file |\n| `policy trust-key` | Add a trusted SSH signer for policy repo verification |\n| `policy list-keys` | Show trusted SSH signers |\n\n### Useful Log Queries\n\n```bash\n# Show calls to a specific tool\nwarden log --server my-server --tool search --limit 20\n\n# Show only blocked calls\nwarden log --blocked\n\n# Tail logs in real time\nwarden log --tail\n```\n\n### Policy Sync from Git\n\nKeep policy in a shared repo and sync it to any machine:\n\n```bash\n# Preview what's in a policy repo\nwarden policy sync --repo https://github.com/example/mcp-policies.git --list\n\n# Apply a specific policy file\nwarden policy apply \\\n  --repo https://github.com/example/mcp-policies.git \\\n  --policy strict.yaml\n\n# Skip signature verification (not recommended for production)\nwarden policy sync --repo \u003curl\u003e --no-verify\n```\n\nPolicy repos are verified against SSH-signed commits. Add trusted signers with `policy trust-key`.\n\n---\n\n## 📊 Dashboard\n\n```bash\nwarden dashboard        # → http://localhost:4242\nwarden dashboard --port 8080\n```\n\nThe dashboard gives you a local UI for exploring audit logs, viewing policy, and checking per-server and per-tool statistics. It reads directly from your local SQLite database — no network requests.\n\nAvailable APIs:\n\n```\nGET  /api/status\nGET  /api/logs/recent\nGET  /api/stats/server/:name\nGET  /api/stats/tools\nGET  /api/stats/analytics\nGET  /api/policy\nPUT  /api/policy\nGET  /api/config\nPUT  /api/config\n```\n\n\u003e ⚠️ The dashboard binds to localhost only. Do not expose it publicly without adding authentication and network controls.\n\n---\n\n## 📦 Installation\n\n### npm (recommended)\n\n```bash\nnpm install -g warden-cli\n```\n\nOr run without installing:\n\n```bash\nnpx warden-cli --help\n```\n\n### Homebrew\n\n```bash\nbrew install --formula https://github.com/flyingsquirrel0419/warden-cli/releases/latest/download/warden-cli.rb\n```\n\n### curl installer\n\n```bash\n# Latest release\ncurl -fsSL https://github.com/flyingsquirrel0419/warden-cli/releases/latest/download/install.sh | sh\n\n# Specific version\nWARDEN_CLI_VERSION=1.0.0 sh -c \"$(curl -fsSL https://github.com/flyingsquirrel0419/warden-cli/releases/latest/download/install.sh)\"\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/flyingsquirrel0419/warden-cli.git\ncd warden-cli\nnpm ci \u0026\u0026 npm run build\nnpm link          # makes `warden` available globally\n```\n\n**Requirements:** Node.js `\u003e=20.0.0`, npm.\n\n---\n\n## 🔒 Security Notes\n\nWarden CLI is a policy and observability layer — not a sandbox. It cannot fully restrict what a running MCP server process can do at the OS level.\n\n- Policy enforcement is only as strong as your configured mode (`enforcing` blocks, `audit-only` records).\n- Audit logs are stored locally under `~/.warden`. Treat `warden.db` as sensitive.\n- Input masking covers well-known secret patterns — avoid passing secrets to untrusted tools regardless.\n- SSRF and data-leak detectors are **heuristic** — they catch common patterns, not everything.\n- For stronger isolation, combine Warden with OS sandboxing, containers, or restricted API tokens.\n\nSee [SECURITY_MODEL.md](docs/SECURITY_MODEL.md) for a full breakdown of what Warden does and doesn't protect against.\n\n---\n\n## 🗂️ Project Structure\n\n```\nsrc/\n├── audit/       SQLite audit log, masking, database setup\n├── cli/         Commander-based CLI commands\n├── daemon/      Notification delivery\n├── dashboard/   Local Express API and static dashboard\n├── policy/      Schema, loader, engine, sync, rate limiter, signature verification\n├── proxy/       MCP proxy, transports, request handlers, notification relay\n├── security/    SSRF guard, injection detector, data leak detector\n└── utils/       Config paths, logger, shared error types\n```\n\n---\n\n## 🧑‍💻 Development\n\n```bash\nnpm ci              # install dependencies\nnpm run build       # compile TypeScript\nnpm run dev         # watch mode\nnpm run format      # auto-format with Prettier\n```\n\n### Testing\n\n```bash\nnpm test                  # full test suite (Vitest)\nnpm run test:coverage     # with coverage report\nnpm run lint              # TypeScript type check\n```\n\nRun the same checks as CI before opening a PR:\n\n```bash\nnpm run format:check \u0026\u0026 npm run lint \u0026\u0026 npm test \u0026\u0026 npm run build \u0026\u0026 npm audit\n```\n\n---\n\n## 🤝 Contributing\n\nContributions are very welcome. MCP security tooling is still early — there's a lot of ground to cover.\n\n**Good first areas:**\n- New security detector heuristics (more injection patterns, new secret formats)\n- Dashboard UI improvements\n- Additional policy rule actions and conditions\n- Integration tests for new MCP server types\n\n**Before you open a PR:**\n1. Create a topic branch.\n2. Make the smallest useful change.\n3. Add or update tests (especially for policy, proxy, and security changes).\n4. Pass all CI checks locally (see above).\n5. Describe the security implications if your change touches `src/policy`, `src/proxy`, `src/security`, or `src/audit`.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide and PR checklist.\nReport vulnerabilities privately via [SECURITY.md](SECURITY.md).\n\n---\n\n## 📚 Documentation\n\n| Doc | What's in it |\n|---|---|\n| [CLI guide](docs/CLI.md) | Every command, flag, and option |\n| [Policy guide](docs/POLICY.md) | Policy schema, modes, rules, and sync |\n| [Architecture](ARCHITECTURE.md) | Component breakdown and request flow |\n| [Security model](docs/SECURITY_MODEL.md) | What Warden protects and what it doesn't |\n| [Operations guide](docs/OPERATIONS.md) | Config paths, log rotation, production tips |\n| [Release guide](docs/RELEASE.md) | How releases and versioning work |\n| [Changelog](CHANGELOG.md) | What changed and when |\n\n---\n\n## License\n\n[Apache-2.0](LICENSE) — free to use, modify, and distribute.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt for the MCP community. ⭐ Star it if it helps you.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingsquirrel0419%2Fwarden-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingsquirrel0419%2Fwarden-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingsquirrel0419%2Fwarden-cli/lists"}