contextguard 0.1.7 → 0.2.0

package/SECURITY.md

@@ -1,254 +0,0 @@
-# Security Policy
-
-## Our Commitment
-
-ContextGuard is a security tool designed to protect MCP servers from various attack vectors. We take the security of ContextGuard itself very seriously. If you discover a security vulnerability, we appreciate your help in disclosing it to us responsibly.
-
-## Supported Versions
-
-We release patches for security vulnerabilities for the following versions:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.1.x   | :white_check_mark: |
-| < 0.1   | :x:                |
-
-## What We Protect Against
-
-ContextGuard currently detects and prevents:
-
-### High Severity Threats
-
-- **Prompt Injection Attacks**: 8+ patterns including instruction hijacking, role manipulation, and context escape attempts
-- **Sensitive Data Leakage**: API keys, passwords, private keys, SSH keys, database credentials, social security numbers
-- **Path Traversal Attacks**: Unauthorized file system access attempts using relative paths or escape sequences
-
-### Medium Severity Threats
-
-- **Rate Limit Violations**: Prevents abuse through excessive requests
-- **Suspicious Input Patterns**: Anomalous request structures that may indicate reconnaissance
-
-### Logging & Monitoring
-
-- **Comprehensive Event Logging**: All security events logged with timestamps and severity levels
-- **Forensic Analysis**: Detailed logs for post-incident investigation
-
-## Known Limitations
-
-ContextGuard is a defense-in-depth tool and should not be your only security measure:
-
-### Current Limitations
-
-- **Evasion Techniques**: Sophisticated attackers may use encoding, obfuscation, or novel patterns to bypass detection
-- **False Positives**: Some legitimate requests may be flagged as suspicious
-- **Performance**: While overhead is <1%, extremely high-throughput scenarios should be tested
-- **Transport Support**: Currently only stdio transport is fully supported (SSE/HTTP in development)
-
-### Not Protected Against
-
-- **Zero-day MCP vulnerabilities**: Unknown vulnerabilities in the MCP protocol itself
-- **Server-side vulnerabilities**: Bugs in your MCP server implementation
-- **Network-level attacks**: DDoS, man-in-the-middle (requires network-level protection)
-- **Compromised dependencies**: Supply chain attacks in your MCP server's dependencies
-
-## Reporting a Vulnerability
-
-**Please DO NOT report security vulnerabilities through public GitHub issues.**
-
-### How to Report
-
-1. **Email**: Send details to [amir@mironi.co.il](mailto:amir@mironi.co.il)
-   - Subject: "SECURITY: [Brief Description]"
-2. **Include**:
-
-   - Type of vulnerability
-   - Full paths of source file(s) related to the vulnerability
-   - Location of affected source code (tag/branch/commit or direct URL)
-   - Step-by-step instructions to reproduce
-   - Proof-of-concept or exploit code (if available)
-   - Impact assessment
-   - Any potential fixes you've considered
-
-3. **Response Time**:
-   - Initial response: Within 48 hours
-   - Status update: Within 7 days
-   - Fix timeline: Depends on severity
-
-### What to Expect
-
-After you submit a report:
-
-1. **Acknowledgment**: We'll confirm receipt within 48 hours
-2. **Assessment**: We'll investigate and determine severity
-3. **Communication**: We'll keep you updated on progress
-4. **Fix Development**: We'll work on a patch
-5. **Disclosure**: We'll coordinate public disclosure with you
-6. **Credit**: We'll credit you (unless you prefer anonymity)
-
-### Severity Levels
-
-We use the following severity scale:
-
-| Severity     | Description                                        | Response Time   |
-| ------------ | -------------------------------------------------- | --------------- |
-| **Critical** | Remote code execution, complete bypass of security | Immediate (24h) |
-| **High**     | Unauthorized data access, privilege escalation     | 3-7 days        |
-| **Medium**   | Denial of service, partial bypass                  | 7-14 days       |
-| **Low**      | Minor information disclosure, edge cases           | 14-30 days      |
-
-## Security Best Practices
-
-When using ContextGuard:
-
-### Deployment Recommendations
-
-1. **Defense in Depth**
-
-   ```bash
-   # Use ContextGuard as ONE layer of security
-   # Also implement:
-   # - Network firewalls
-   # - Rate limiting at API gateway
-   # - Authentication/authorization
-   # - Input validation in your MCP server
-   ```
-
-2. **Configuration Security**
-
-   ```json
-   {
-     "maxToolCallsPerMinute": 30,
-     "enablePromptInjectionDetection": true,
-     "enableSensitiveDataDetection": true,
-     "allowedFilePaths": ["/safe/directory/only"],
-     "logLevel": "info"
-   }
-   ```
-
-3. **Least Privilege**
-
-   - Run ContextGuard with minimal required permissions
-   - Restrict file system access to only necessary directories
-   - Use environment variables for secrets, never hardcode
-
-4. **Regular Updates**
-
-   ```bash
-   # Check for updates regularly
-   npm update -g contextguard
-
-   # Subscribe to security advisories
-   npm audit
-   ```
-
-5. **Monitor Logs**
-
-   ```bash
-   # Review security logs regularly
-   tail -f mcp_security.log | grep "SECURITY_VIOLATION"
-
-   # Set up alerts for HIGH severity events
-   ```
-
-### Testing Security
-
-Before production deployment:
-
-```bash
-# 1. Test with known attack patterns
-contextguard --server "node test-server.js" --config test-security.json
-
-# 2. Review logs for false positives
-cat mcp_security.log | jq 'select(.severity == "HIGH")'
-
-# 3. Performance testing
-# Ensure <1% overhead in your specific environment
-
-# 4. Backup and recovery
-# Test your incident response plan
-```
-
-## Security Audit History
-
-| Date | Auditor | Scope         | Status  |
-| ---- | ------- | ------------- | ------- |
-| TBD  | TBD     | Full codebase | Planned |
-
-We plan to conduct regular security audits as the project matures.
-
-## Security-Related Configuration
-
-### Example Production Configuration
-
-```json
-{
-  "maxToolCallsPerMinute": 30,
-  "enablePromptInjectionDetection": true,
-  "enableSensitiveDataDetection": true,
-  "enablePathTraversalPrevention": true,
-  "allowedFilePaths": ["/var/app/data", "/home/user/safe-directory"],
-  "blockedPatterns": [
-    "ignore previous instructions",
-    "system prompt",
-    "confidential"
-  ],
-  "logLevel": "info",
-  "logFile": "/tmp/mcp_security.log",
-  "alertWebhook": "https://your-monitoring-service.com/webhook"
-}
-```
-
-### Environment Variables
-
-Never store secrets in configuration files:
-
-```bash
-# Good
-export MCP_API_KEY="your-key-here"
-contextguard --server "node server.js"
-
-# Bad
-# Don't hardcode secrets in config files or code
-```
-
-## Vulnerability Disclosure Policy
-
-### Our Commitment
-
-- We will respond to your report within 48 hours
-- We will keep you informed of our progress
-- We will not take legal action against security researchers who:
-  - Act in good faith
-  - Avoid privacy violations and service disruption
-  - Give us reasonable time to fix issues before disclosure
-
-### Public Disclosure
-
-- **Coordinated Disclosure**: We prefer to fix vulnerabilities before public disclosure
-- **Timeline**: We aim to release fixes within 90 days of initial report
-- **Credit**: We will publicly thank reporters (unless they prefer anonymity)
-- **CVE Assignment**: Critical vulnerabilities will receive CVE identifiers
-
-## Contact
-
-- **Security Issues**: [amir@mironi.co.il](mailto:amir@mironi.co.il)
-- **General Questions**: [GitHub Issues](https://github.com/amironi/contextguard/issues)
-- **PGP Key**: Coming soon
-
-## Attribution
-
-We appreciate the security research community. Past contributors:
-
-- _Your name could be here!_
-
-## Resources
-
-- [OWASP Top 10 for LLMs](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
-- [MCP Security Best Practices](https://modelcontextprotocol.io/docs/security)
-- [Prompt Injection Defense](https://simonwillison.net/2023/Apr/14/worst-that-can-happen/)
-
----
-
-**Last Updated**: October 2025
-
-Thank you for helping keep ContextGuard and its users safe!

package/eslint.config.mts

@@ -1,23 +0,0 @@
-import js from "@eslint/js";
-import globals from "globals";
-import tseslint from "typescript-eslint";
-import { defineConfig } from "eslint/config";
-
-export default defineConfig([
-  {
-    ignores: ["dist/**", "node_modules/**"],
-  },
-  {
-    files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
-    plugins: { js },
-    extends: ["js/recommended"],
-    languageOptions: { globals: globals.browser },
-  },
-  {
-    rules: {
-      // "no-unused-vars": "warn",
-      // "no-explicit-any": "info",
-    },
-  },
-  tseslint.configs.recommended,
-]);

package/examples/config/config.json

@@ -1,19 +0,0 @@
-{
-  "maxToolCallsPerMinute": 30,
-  "blockedPatterns": [
-    "ignore previous instructions",
-    "system prompt",
-    "confidential"
-  ],
-  "allowedFilePaths": [
-    "/var/app/data",
-    "/home/user/safe-directory"
-  ],
-  "alertThreshold": 5,
-  "enablePromptInjectionDetection": true,
-  "enableSensitiveDataDetection": true,
-  "enablePathTraversalPrevention": true,
-  "enableRateLimiting": true,
-  "logLevel": "debug",
-  "logPath": "/tmp/mcp_security.log"
-}

package/examples/mcp-server/demo.js

@@ -1,228 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Simple MCP Test Server
- * This is a basic MCP server for testing ContextGuard
- */
-
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import fs from "fs/promises";
-
-// Create server instance
-const server = new Server(
-  {
-    name: "test-mcp-server",
-    version: "1.0.0",
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
-
-// Tool 1: Echo - Simple text echo (safe)
-// Tool 2: Read File - Reads files (vulnerable to path traversal)
-// Tool 3: Get Secret - Returns API key (vulnerable to data leakage)
-// Tool 4: Execute Command - Runs commands (vulnerable to prompt injection)
-
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "echo",
-        description: "Echoes back the input text",
-        inputSchema: {
-          type: "object",
-          properties: {
-            message: {
-              type: "string",
-              description: "The message to echo back",
-            },
-          },
-          required: ["message"],
-        },
-      },
-      {
-        name: "read_file",
-        description: "Reads a file from the filesystem",
-        inputSchema: {
-          type: "object",
-          properties: {
-            filepath: {
-              type: "string",
-              description: "Path to the file to read",
-            },
-          },
-          required: ["filepath"],
-        },
-      },
-      {
-        name: "get_config",
-        description: "Gets application configuration (contains API keys)",
-        inputSchema: {
-          type: "object",
-          properties: {
-            key: {
-              type: "string",
-              description: "Configuration key to retrieve",
-            },
-          },
-          required: ["key"],
-        },
-      },
-      {
-        name: "search_database",
-        description: "Searches the user database",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: {
-              type: "string",
-              description: "Search query",
-            },
-          },
-          required: ["query"],
-        },
-      },
-    ],
-  };
-});
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    switch (name) {
-      case "echo": {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Echo: ${args.message}`,
-            },
-          ],
-        };
-      }
-
-      case "read_file": {
-        // VULNERABLE: No path validation!
-        // An attacker could use: ../../../../etc/passwd
-        const filepath = args.filepath;
-
-        try {
-          const content = await fs.readFile(filepath, "utf-8");
-          return {
-            content: [
-              {
-                type: "text",
-                text: `File content:\n${content}`,
-              },
-            ],
-          };
-        } catch (error) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: `Error reading file: ${error.message}`,
-              },
-            ],
-            isError: true,
-          };
-        }
-      }
-
-      case "get_config": {
-        // VULNERABLE: Returns sensitive data!
-        const configs = {
-          api_key: "sk-1234567890abcdefghijklmnop",
-          database_password: "super_secret_password_123",
-          aws_secret: "AKIAIOSFODNN7EXAMPLE",
-          stripe_key: "sk_live_51234567890",
-        };
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Config value: ${configs[args.key] || "Not found"}`,
-            },
-          ],
-        };
-      }
-
-      case "search_database": {
-        // VULNERABLE: Could be manipulated via prompt injection
-        const query = args.query;
-
-        // Simulated database with sensitive info
-        const users = [
-          {
-            id: 1,
-            name: "John Doe",
-            ssn: "123-45-6789",
-            email: "john@example.com",
-          },
-          {
-            id: 2,
-            name: "Jane Smith",
-            ssn: "987-65-4321",
-            email: "jane@example.com",
-          },
-        ];
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Search results for "${query}":\n${JSON.stringify(
-                users,
-                null,
-                2
-              )}`,
-            },
-          ],
-        };
-      }
-
-      default:
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Unknown tool: ${name}`,
-            },
-          ],
-          isError: true,
-        };
-    }
-  } catch (error) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Error: ${error.message}`,
-        },
-      ],
-      isError: true,
-    };
-  }
-});
-
-// Start the server
-async function main() {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("Test MCP Server running on stdio");
-}
-
-main().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});