{"id":44982566,"url":"https://github.com/clay-good/proxilion-mcp","last_synced_at":"2026-02-18T18:34:48.962Z","repository":{"id":336537240,"uuid":"1100175472","full_name":"clay-good/proxilion-mcp","owner":"clay-good","description":"Proxilion MCP Security Gateway is a self-hosted, Docker-ready security gateway that provides real-time threat detection (\u003c50ms P95 latency) against insider threats, compromised accounts, and rogue AI agents by analyzing tool calls from assistants like Copilot and Claude Code, achieving a 75-85% detection rate against sophisticated attacks.","archived":false,"fork":false,"pushed_at":"2026-02-04T22:19:15.000Z","size":640,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-05T10:49:20.891Z","etag":null,"topics":["ai-assistant","ai-security","claude-code","cybersecurity","docker","github-copilot","insider-threat","mcp-proto","rust","security-gateway","threat-detection"],"latest_commit_sha":null,"homepage":"https://proxilion.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clay-good.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"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":"2025-11-19T23:58:41.000Z","updated_at":"2026-02-04T22:19:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clay-good/proxilion-mcp","commit_stats":null,"previous_names":["clay-good/proxilion-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/clay-good/proxilion-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay-good%2Fproxilion-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay-good%2Fproxilion-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay-good%2Fproxilion-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay-good%2Fproxilion-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clay-good","download_url":"https://codeload.github.com/clay-good/proxilion-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clay-good%2Fproxilion-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29589701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T16:55:40.614Z","status":"ssl_error","status_checked_at":"2026-02-18T16:55:37.558Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-assistant","ai-security","claude-code","cybersecurity","docker","github-copilot","insider-threat","mcp-proto","rust","security-gateway","threat-detection"],"created_at":"2026-02-18T18:34:46.326Z","updated_at":"2026-02-18T18:34:48.951Z","avatar_url":"https://github.com/clay-good.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Proxilion MCP Security Gateway\n\nReal-time threat detection for AI coding assistants. Analyzes MCP tool calls to detect insider threats, compromised accounts, and rogue AI agents before they can weaponize Claude Code, GitHub Copilot, Cursor, or Windsurf.\n\n---\n\n## What This Is\n\nProxilion is a Rust-based security gateway that sits between AI assistants and MCP servers. It analyzes every tool call (bash commands, file operations, network requests) for malicious patterns before execution.\n\n**What it does well:**\n- Pattern-based threat detection (credential harvesting, network reconnaissance, data exfiltration)\n- Session correlation (tracks multi-phase attack chains)\n- Low latency analysis (\u003c50ms P95 in benchmarks)\n- Custom policy DSL for rules, allowlists, blocklists\n- 358 tests passing\n\n**What it does NOT do:**\n- Prevent attacks that don't involve MCP tool calls\n- Detect novel attack patterns not in its ruleset\n- Provide authentication (you must deploy behind an auth layer)\n- Guarantee detection of sophisticated attackers\n\n---\n\n## Quick Start\n\n### Docker Deployment\n\n```bash\ngit clone https://github.com/clay-good/proxilion\ncd proxilion\n\n# Start in monitor mode (logs only, never blocks)\ndocker compose up -d\n\n# Check health\ncurl http://localhost:8787/health\n\n# View metrics\ncurl http://localhost:8787/metrics\n```\n\n### Build from Source\n\n```bash\ncargo build --release\n\n# Run with in-memory session store (testing only)\nSESSION_STORE=inmemory MODE=monitor ./target/release/proxilion-gateway\n\n# Run with Redis (production)\nSESSION_STORE=redis REDIS_URL=redis://localhost:6379 MODE=block ./target/release/proxilion-gateway\n```\n\n### Enable Monitoring Stack\n\n```bash\ndocker compose --profile monitoring up -d\n```\n\n- Grafana: http://localhost:3001 (admin/admin)\n- Prometheus: http://localhost:9090\n\n---\n\n## Architecture\n\n```\nAI Assistant (Claude Code, Copilot, etc.)\n        |\n        v\nProxilion Gateway (analyzes tool call, \u003c50ms)\n        |\n        v\nDecision: Allow | Alert | Block | Terminate\n        |\n        v\nMCP Server executes (or rejects) the tool call\n```\n\n### Components\n\n| Crate | Purpose |\n|-------|---------|\n| `gateway` | HTTP API server (Axum), request routing, operational modes |\n| `threat-engine` | 22 pattern-based analyzers + 2 session-aware analyzers |\n| `session-state` | Redis/In-Memory/PostgreSQL session storage |\n| `mcp-protocol` | MCP JSON-RPC 2.0 parsing |\n\n### Threat Analyzers (24 Active in Pipeline)\n\n**Pattern-Based (22):**\n- Enumeration (nmap, masscan, port scanning)\n- Credential Access (.env, SSH keys, AWS credentials, /etc/shadow)\n- Exfiltration (curl to external IPs, pastebin uploads, netcat)\n- AI Velocity (automated execution patterns)\n- Prompt Engineering (jailbreak attempts)\n- Social Engineering (authority claims, roleplay manipulation)\n- Callback Validation (C2 detection, SSRF)\n- MCP Orchestration (malicious MCP chaining)\n- File Access (sensitive file patterns)\n- Task Fragmentation (command chaining, obfuscation)\n- Data Volume (bulk transfers, database dumps)\n- Privilege Escalation (sudo abuse, SUID)\n- Lateral Movement (SSH pivoting, internal network)\n- Hacking Tools (metasploit, hashcat, mimikatz)\n- Hallucination (AI fabrication detection)\n- Persistence (cron jobs, systemd, backdoors)\n- Defense Evasion (log clearing, firewall bypass)\n- Command and Control (reverse shells, Cobalt Strike)\n- Collection (data staging, screenshots)\n- Impact (destructive operations like rm -rf)\n- Tool Call (SQL injection, command chaining)\n- Legitimacy (context-aware false positive reduction)\n\n**Session-Aware (2):**\n- Request Rate (burst detection, machine-like velocity)\n- Session Progression (kill chain tracking: Recon -\u003e Credentials -\u003e Exfiltration)\n\n**Additional Analyzers (6, require explicit configuration):**\n- AI Autonomy (autonomous agent detection)\n- Conversation Analysis (social engineering via conversation context)\n- Conversation Context (multi-turn tracking)\n- Multi-Target Orchestration (parallel target operations)\n- Multi-User Correlation (coordinated attacks across users)\n- Semantic Analysis (Claude API-based intent analysis, optional feature flag)\n\n---\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Required\nMODE=monitor                # monitor | alert | block | terminate\nSESSION_STORE=redis         # inmemory | redis\nREDIS_URL=redis://localhost:6379\n\n# Optional\nLISTEN_ADDR=0.0.0.0:8787\nALERT_THRESHOLD=50\nBLOCK_THRESHOLD=70\nTERMINATE_THRESHOLD=90\n\n# Policy file (optional, for custom rules)\nPOLICY_FILE=./proxilion-policy.toml\n\n# Semantic Analysis (optional, requires Claude API)\nENABLE_SEMANTIC_ANALYSIS=false\nANTHROPIC_API_KEY=sk-ant-xxx\n```\n\n### Custom Policy DSL\n\nDefine custom rules, allowlists, and blocklists in a TOML file:\n\n```bash\n# Copy example and customize\ncp proxilion-policy.example.toml proxilion-policy.toml\n\n# Run with policy\nPOLICY_FILE=./proxilion-policy.toml ./target/release/proxilion-gateway\n```\n\nExample policy rules:\n\n```toml\n# proxilion-policy.toml\n\n[settings]\nalert_threshold = 50\nblock_threshold = 70\n\n# Allow git operations\n[[rules]]\nname = \"allow-git\"\npattern = \"^git (status|log|diff|commit)\"\naction = \"allow\"\npriority = 100\n\n# Block reverse shells\n[[rules]]\nname = \"block-reverse-shell\"\npattern = \"bash -i \u003e\u0026 /dev/tcp\"\naction = \"block\"\nscore = 95\n\n# Security team can use nmap\n[[rules]]\nname = \"security-nmap\"\npattern = \"nmap\"\naction = \"allow\"\n[rules.conditions]\nuser_pattern = \"security-.*@company.com\"\n\n# Allowlist for specific users\n[[allowlists.users]]\nid = \"security-team@company.com\"\nbypass_patterns = [\"nmap\", \"metasploit\"]\n\n# Blocklist dangerous commands\n[[blocklists.commands]]\npattern = \"rm -rf /\"\nreason = \"Destructive command\"\nscore = 100\n```\n\nSee [proxilion-policy.example.toml](proxilion-policy.example.toml) for a complete example.\n\n### Operational Modes\n\n| Mode | Score \u003c 50 | Score 50-69 | Score 70-89 | Score \u003e= 90 |\n|------|------------|-------------|-------------|-------------|\n| `monitor` | Allow + Log | Allow + Log | Allow + Log | Allow + Log |\n| `alert` | Allow | Allow + Alert | Allow + Alert | Allow + Alert |\n| `block` | Allow | Alert | **Block** | **Block** |\n| `terminate` | Allow | Alert | **Block** | **Block + Terminate Session** |\n\n---\n\n## API Reference\n\n### POST /analyze\n\nAnalyze a tool call for threats.\n\n**Request:**\n```json\n{\n  \"tool_call\": {\n    \"Bash\": {\n      \"command\": \"nmap -sV target.com\",\n      \"args\": [],\n      \"env\": {}\n    }\n  },\n  \"user_id\": \"user@company.com\",\n  \"session_id\": \"session_123\"\n}\n```\n\n**Response:**\n```json\n{\n  \"decision\": \"Block\",\n  \"threat_score\": 88.0,\n  \"patterns\": [\n    \"nmap reconnaissance tool detected\",\n    \"Port scanning flags detected\"\n  ],\n  \"session_terminated\": false,\n  \"session_id\": \"session_123\"\n}\n```\n\n**Status Codes:**\n- `200 OK` - Analysis complete (Allow or Alert)\n- `403 Forbidden` - Blocked or Terminated\n- `500 Internal Server Error` - Gateway error\n\n### GET /health\n\nHealth check endpoint.\n\n### GET /metrics\n\nPrometheus metrics export.\n\n---\n\n## Integration Examples\n\n**Note:** Client libraries are included in this repository but not yet published to npm/PyPI. Install from local source:\n\n```bash\n# TypeScript - install from local package\ncd packages/mcp-proxilion-middleware \u0026\u0026 npm install \u0026\u0026 npm run build\nnpm link  # or copy to your project\n\n# Python - install from local package\ncd packages/proxilion-mcp-python \u0026\u0026 pip install -e .\n```\n\n### TypeScript\n\n```typescript\nimport { ProxilionMCPClient } from '@proxilion/mcp-middleware';\n\nconst client = new ProxilionMCPClient({\n  proxilionEndpoint: 'http://localhost:8787',\n  userId: 'user@company.com',\n  mode: 'block',\n});\n\nconst result = await client.callToolWithAnalysis(toolCall, executeFunc);\n```\n\n### Python\n\n```python\nfrom proxilion_mcp import ProxilionMCPClient, ProxilionConfig\n\nclient = ProxilionMCPClient(ProxilionConfig(\n    proxilion_endpoint=\"http://localhost:8787\",\n    user_id=\"user@company.com\",\n    mode=\"block\",\n))\n\nresult = await client.call_tool_with_analysis(tool_call, execute_func)\n```\n\nSee [examples/](examples/) for complete integration code.\n\nSee [examples/cursor/](examples/cursor/) and [examples/windsurf/](examples/windsurf/) for IDE-specific integration guides.\n\n**Note:** Cursor and Windsurf do not natively support MCP proxy configuration. The integration guides provide workarounds (network-level proxies, MCP wrappers) that have limitations. See the individual guides for details.\n\n---\n\n## Limitations (Read This)\n\n### This is NOT a Silver Bullet\n\nProxilion is one layer in defense-in-depth. It will not catch everything.\n\n### Architectural Constraints\n\n1. **MCP-layer only**: We only see tool calls. If an attacker manipulates the AI without triggering tool execution, we cannot detect it.\n\n2. **Pattern-based detection**: We detect known attack patterns. Novel techniques, custom obfuscation, or attacks not in our ruleset may evade detection.\n\n3. **No authentication**: Proxilion does not verify user identity. You MUST deploy behind an authentication layer (API gateway, reverse proxy with OAuth/OIDC).\n\n4. **Requires persistent session IDs**: Clients must provide consistent `session_id` values. Without this, session-aware analyzers (kill chain detection, request rate) cannot function.\n\n5. **False positives exist**: Legitimate security work (penetration testing, DevOps) may trigger alerts. Expect to tune thresholds for your environment. Target \u003c5% false positive rate.\n\n### What We Cannot Detect\n\n1. **Strategic planning before tool calls**: Social engineering that succeeds before any tool is executed (e.g., attacker convinces AI to help, but hasn't executed anything yet).\n\n2. **Custom orchestration above MCP**: Attacker frameworks coordinating multiple AI instances externally.\n\n3. **Attacks fragmented over months**: If individual requests appear benign in isolation, session correlation won't help.\n\n4. **Non-MCP AI systems**: We only protect MCP-compatible tools.\n\n5. **Direct network attacks**: We analyze tool calls, not network packets. A direct SSH brute-force bypasses us entirely.\n\n6. **Obfuscated commands**: Heavy base64 encoding, variable expansion tricks, or polyglot payloads may evade pattern matching.\n\n7. **Insider with legitimate access**: If an authorized user with real credentials decides to exfiltrate data using normal tools in normal ways, detection is difficult.\n\n### Operational Constraints\n\n1. **Semantic analysis costs money**: If enabled, Claude API calls cost approximately $0.0015 per analyzed request. At 100,000 requests/month, that's $150/month. Only runs for ambiguous scores (40-80 range).\n\n2. **Redis required for production**: In-memory session store is for testing only. Session data is lost on restart.\n\n3. **Cold start latency**: First request after startup may take 100-200ms as analyzers initialize.\n\n4. **No admin UI**: All configuration is via environment variables and TOML policy files. No web dashboard.\n\n5. **Limited to single-instance**: No built-in clustering. Scale horizontally by running multiple instances behind a load balancer (each needs access to shared Redis).\n\n6. **No failover testing**: Redis and PostgreSQL failover scenarios have not been tested. Plan for data loss during infrastructure failures.\n\n7. **No security audit**: This codebase has not undergone independent security audit or penetration testing. Use at your own risk in high-security environments.\n\n8. **Regex patterns not fuzzed**: Pattern matching regexes have not been fuzz-tested. Malformed input could potentially cause unexpected behavior.\n\n9. **TLS not enforced**: Gateway accepts HTTP connections. You must configure TLS at the reverse proxy or load balancer level.\n\n10. **Redis authentication not enforced**: Gateway connects to Redis without requiring authentication. You must configure Redis `requirepass` separately.\n\n### Detection Rate Claims\n\nThe \"75-85% detection rate against GTG-1002-class attacks\" claim:\n- Based on internal testing against a specific attack scenario\n- Not independently validated\n- Real-world detection rates depend heavily on attacker sophistication and your tuning\n- Novel attacks will have lower detection rates until patterns are added\n\n### What's Missing\n\n- Built-in rate limiting at gateway level (use external rate limiter like NGINX or Kong)\n- Published npm/PyPI packages (client libraries must be installed from local source)\n- Helm charts for Kubernetes deployment\n- Native IDE plugins (Cursor, Windsurf, VS Code) - workarounds only\n\n### Known Evasion Limitations\n\nThe following bypass techniques are documented in the evasion test suite but not fully mitigated:\n\n- Variable concatenation (`a=nm;b=ap;$a$b`) - command built dynamically\n- Nested command substitution (`$($(echo echo) nmap)`)\n- Printf hex escapes (`$(printf '\\\\x6e\\\\x6d\\\\x61\\\\x70')`)\n- Wildcard credential access (`cat /home/*/.ssh/id_*`) - read-only heuristic bypass\n\n---\n\n## Security Considerations\n\n### Deploy Behind Authentication\n\nProxilion does NOT authenticate users. Deploy architecture:\n\n```\nClient (with auth token)\n    |\n    v\nAPI Gateway / Reverse Proxy (OAuth, API key validation)\n    |\n    v\nProxilion Gateway (threat analysis)\n    |\n    v\nMCP Server (tool execution)\n```\n\n### Best Practices\n\n- Network isolation (private VPC, security groups)\n- TLS/SSL for all connections\n- Redis authentication enabled (requirepass)\n- Secrets management (Vault, AWS Secrets Manager)\n- Resource limits (Docker memory/CPU constraints)\n- Regular log review and alerting\n\n### Vulnerability Reporting\n\nOpen a GitHub issue or contact maintainers directly.\n\n---\n\n## Testing\n\n```bash\n# Run all tests (358 tests)\ncargo test\n\n# Run unit tests only\ncargo test -p threat-engine --test unit_tests\n\n# Run evasion bypass tests\ncargo test -p threat-engine --test evasion_tests\n\n# Run demo attack simulation\n./demo.sh\n\n# Run performance benchmarks (requires criterion.rs)\ncargo bench -p threat-engine\n\n# Run specific benchmark\ncargo bench -p threat-engine -- analyze_safe\n\n# Run load tests (requires k6: brew install k6)\nk6 run loadtest/baseline.js\n\n# Run stress test\nk6 run loadtest/stress.js\n```\n\n## Tools\n\n### Cost Calculator\n\nEstimate monthly costs for semantic analysis:\n\n```bash\n# Build and run\ncd tools \u0026\u0026 cargo build --release\n./target/release/cost-calculator --requests 100000\n\n# With custom parameters\n./target/release/cost-calculator -r 500000 -a 0.25 -c 0.50\n\n# Show comparison table\n./target/release/cost-calculator --compare\n```\n\nExample output:\n```\nPROXILION SEMANTIC ANALYSIS COST ESTIMATE\n═══════════════════════════════════════════════════════════════\nMonthly requests:             100,000\nAmbiguous rate:                  30.0%\nResult cache hit rate:           40.0%\n\nTOTAL MONTHLY COST:            $64.06\nCost per request:           $0.000641\n```\n\n---\n\n## Production Checklist\n\nBefore deploying to production:\n\n- [ ] Run in monitor mode for 1+ week to establish baseline\n- [ ] Review false positive rate (target: \u003c5%)\n- [ ] Configure Redis with authentication\n- [ ] Set up Prometheus + Grafana monitoring\n- [ ] Configure alerts for high threat scores (70+)\n- [ ] Deploy behind authentication layer\n- [ ] Enable TLS/SSL\n- [ ] Test fail-open vs fail-closed behavior for your use case\n- [ ] Document incident response procedures for your team\n- [ ] Train security team on interpreting alerts\n\n---\n\n## Documentation\n\n- [docs/QUICK_START.md](docs/QUICK_START.md) - 5-minute deployment\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - System design details\n- [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) - Authentication layer setup (NGINX, Kong, AWS, Azure, mTLS)\n- [docs/ALERTING_GUIDE.md](docs/ALERTING_GUIDE.md) - Prometheus alerts configuration\n- [docs/INCIDENT_RESPONSE.md](docs/INCIDENT_RESPONSE.md) - Security incident response playbook\n- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - Common issues and solutions\n- [docs/BENCHMARKS.md](docs/BENCHMARKS.md) - Performance benchmark suite\n- [docs/BACKUP_RECOVERY.md](docs/BACKUP_RECOVERY.md) - Backup and disaster recovery procedures\n- [docs/MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md) - Migrating from other security tools\n- [docs/ARCHITECTURAL_LIMITATIONS.md](docs/ARCHITECTURAL_LIMITATIONS.md) - Detailed constraints\n- [docs/DEPLOYMENT_GUIDES.md](docs/DEPLOYMENT_GUIDES.md) - Enterprise deployment scenarios\n\n---\n\n## License\n\nMIT License\n\n---\n\n## Built With\n\n- Rust 1.70+ (memory safety, performance)\n- Tokio (async runtime)\n- Axum (HTTP framework)\n- Redis (session correlation)\n- Prometheus + Grafana (monitoring)\n- Docker (deployment)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclay-good%2Fproxilion-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclay-good%2Fproxilion-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclay-good%2Fproxilion-mcp/lists"}