Cyber Sentinel MCP Server

# 🛡️ Cyber Sentinel MCP Server A comprehensive threat intelligence aggregation MCP (Model Context Protocol) server that provides unified access to multiple threat intelligence sources for security analysis. ## 🎯 Overview Cyber Sentinel eliminates the tedious manual process of querying multiple threat intelligence sources by providing a single, unified interface. Security analysts can now analyze indicators (IPs, domains, hashes, URLs) across multiple sources with a single command, getting aggregated results with confidence scoring. ## ✨ Features ### 🔍 Threat Intelligence - **Multi-Source Intelligence**: Aggregates data from VirusTotal v3, AbuseIPDB, URLhaus, Shodan, ThreatFox, and MalwareBazaar - **Smart Indicator Detection**: Automatically detects IP addresses, domains, file hashes, and URLs - **Intelligent Aggregation**: Combines results from multiple sources with confidence scoring - **Async Performance**: High-performance concurrent processing - **Smart Caching**: Reduces API calls and improves response times (1-hour TTL) - **Rate Limiting**: Respects API limits across all sources (60 req/min default) - **Error Recovery**: Graceful handling of API failures and timeouts ### 🛡️ Code Security Analysis - **Multi-Language Support**: Analyzes Python, JavaScript, Java, C#, PHP, Go, Rust, C++, and SQL code - **Vulnerability Detection**: Identifies hardcoded secrets, SQL injection, XSS, path traversal, and more - **Network Indicator Analysis**: Extracts and analyzes IPs, domains, and URLs found in code - **Secure Alternatives**: Provides secure coding recommendations and alternatives - **Risk Scoring**: Calculates comprehensive security risk scores ### 📦 Dependency Security - **Multi-Platform Support**: Scans NPM, Python, Maven, Cargo, Go, and Composer dependencies - **Vulnerability Detection**: Identifies known malicious packages and outdated dependencies - **Security Recommendations**: Provides actionable security improvement suggestions - **Risk Assessment**: Comprehensive dependency risk scoring ### 🐳 Infrastructure Security - **Docker Security**: Analyzes Dockerfile configurations for security best practices - **Kubernetes Security**: Scans K8s manifests for security misconfigurations - **CI/CD Integration**: Provides security analysis for DevOps pipelines ### 📊 Reporting & Visualization - **Rich Reports**: Generates comprehensive security analysis reports - **Visual Dashboards**: Creates security metrics and trend visualizations - **Export Options**: Supports multiple output formats (JSON, HTML, PDF) - **MCP Protocol**: Full compatibility with MCP-enabled AI assistants ## 🚀 Quick Start ### Prerequisites - Python 3.8 or higher - MCP-compatible client (Claude Desktop, Cursor, etc.) ### Installation 1. **Clone the repository**: ```bash git clone https://github.com/jx888-max/cyber-sentinel-mcp.git cd cyber-sentinel-mcp ``` 2. **Install dependencies**: ```bash pip install -e . ``` 3. **配置API密钥**: ```bash # 运行设置向导 python -m cyber_sentinel.setup_wizard # 或者直接设置环境变量 export VIRUSTOTAL_API_KEY=your_virustotal_api_key_here export ABUSEIPDB_API_KEY=your_abuseipdb_api_key_here ``` 4. **Verify installation**: ```bash python -c "from cyber_sentinel.server import app; print('✅ Installation successful!')" ``` ### API Key Setup #### VirusTotal (Highly Recommended) - **Free Tier**: 1,000 requests/day - **Capabilities**: IP, domain, hash, and URL analysis 1. Visit [VirusTotal](https://www.virustotal.com/gui/join-us) 2. Create a free account 3. Get your API key from the API section 4. Add to `.env`: `VIRUSTOTAL_API_KEY=your_key_here` #### AbuseIPDB (Highly Recommended) - **Free Tier**: 1,000 requests/day - **Capabilities**: IP address reputation and abuse reporting 1. Visit [AbuseIPDB](https://www.abuseipdb.com/register) 2. Create a free account 3. Get your API key from the account settings 4. Add to `.env`: `ABUSEIPDB_API_KEY=your_key_here` #### Shodan (Optional) - **Free Tier**: 100 results/month - **Capabilities**: Internet-connected device intelligence 1. Visit [Shodan](https://account.shodan.io/) 2. Create an account and get your API key 3. Add to `.env`: `SHODAN_API_KEY=your_key_here` #### URLhaus (No API Key Required) - **Free**: Works without API key for basic usage - **Capabilities**: Malware URL and payload tracking ## 🔧 MCP Client Configuration ### Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "cyber-sentinel": { "command": "python", "args": ["-m", "cyber_sentinel.server"], "cwd": "/path/to/cyber-sentinel", "env": { "VIRUSTOTAL_API_KEY": "your_virustotal_key", "ABUSEIPDB_API_KEY": "your_abuseipdb_key", "SHODAN_API_KEY": "your_shodan_key" } } } } ``` ### Cursor/VS Code Add to your MCP configuration: ```json { "mcp.servers": { "cyber-sentinel": { "command": ["python", "-m", "cyber_sentinel.server"], "cwd": "/path/to/cyber-sentinel", "env": { "VIRUSTOTAL_API_KEY": "your_virustotal_key", "ABUSEIPDB_API_KEY": "your_abuseipdb_key" } } } } ``` ## 📖 Usage Examples Once configured in your MCP client, you can use natural language to analyze security indicators: ### 🔍 Threat Intelligence Analysis ``` Analyze the IP address 8.8.8.8 for any malicious activity Check if 1.1.1.1 is safe to use Is google.com safe? Check the security status of example.com Analyze this MD5 hash: d41d8cd98f00b204e9800998ecf8427e Is this URL safe: https://example.com/suspicious-path Show me the status of all threat intelligence sources ``` ### 🛡️ Code Security Analysis ``` Analyze this Python code for security vulnerabilities: [paste your code here] Check this JavaScript function for XSS vulnerabilities: [paste your code here] Scan this SQL query for injection risks: [paste your code here] ``` ### 📦 Dependency Security Scanning ``` Scan these project dependencies for vulnerabilities: package.json: [paste content] requirements.txt: [paste content] Check my Python project for outdated packages: [provide requirements.txt content] ``` ### 🐳 Infrastructure Security ``` Analyze this Dockerfile for security issues: [paste Dockerfile content] Check this Kubernetes deployment for security misconfigurations: [paste K8s YAML content] ``` ### 📊 Security Reporting ``` Generate a comprehensive security report for my project Create a security dashboard with current threat landscape Export security findings to HTML report ``` ## 🛠️ Available MCP Tools ### 🔍 Threat Intelligence Tools #### `analyze_indicator` Analyzes security indicators across multiple threat intelligence sources. **Supported Indicators:** - **IP Addresses**: IPv4 addresses (e.g., `8.8.8.8`) - **Domain Names**: Any domain (e.g., `google.com`) - **File Hashes**: MD5, SHA1, SHA256 hashes - **URLs**: Complete URLs (e.g., `https://example.com`) **Returns:** - Overall reputation (clean/malicious/unknown) - Confidence score (0-100%) - Results from individual threat intelligence sources - Geographic and ISP information (for IPs) - Detailed analysis data #### `check_api_status` Checks the configuration and status of all threat intelligence sources. **Returns:** - API key validation status - Available capabilities per source - Rate limiting configuration - Overall system health ### 🛡️ Security Analysis Tools #### `analyze_code_security` Performs comprehensive security analysis of source code. **Parameters:** - `code_content`: Source code to analyze - `language`: Programming language (auto-detected if not specified) - `locale`: Output language (zh/en) **Returns:** - Security vulnerabilities and their severity - Hardcoded secrets and credentials - Network indicators found in code - Secure coding recommendations - Risk score and remediation guidance #### `scan_project_dependencies` Scans project dependencies for security vulnerabilities. **Parameters:** - `project_files`: Dictionary of dependency files (package.json, requirements.txt, etc.) **Returns:** - Known malicious packages - Outdated dependencies with vulnerabilities - Security recommendations - Risk assessment and scoring #### `analyze_docker_security` Analyzes Docker configurations for security best practices. **Parameters:** - `dockerfile_content`: Dockerfile content to analyze **Returns:** - Security misconfigurations - Best practice violations - Hardening recommendations - Risk assessment #### `scan_kubernetes_config` Scans Kubernetes manifests for security issues. **Parameters:** - `k8s_manifests`: Dictionary of Kubernetes YAML files **Returns:** - Security policy violations - Privilege escalation risks - Network security issues - Compliance recommendations #### `generate_security_report` Generates comprehensive security reports with visualizations. **Parameters:** - `analysis_results`: Combined results from security analyses - `report_format`: Output format (json/html/markdown) **Returns:** - Formatted security report - Executive summary - Detailed findings - Remediation roadmap ## 📊 Example Response ```json { "indicator": "8.8.8.8", "type": "ip", "overall_reputation": "clean", "confidence": 100.0, "sources_checked": 4, "sources_responded": 3, "malicious_sources": 0, "clean_sources": 3, "countries": ["US"], "isps": ["Google LLC"], "detailed_results": [ { "source": "VirusTotal", "reputation": "clean", "malicious_count": 0, "total_engines": 89 } ], "errors": [], "timestamp": "2024-01-15T10:30:00Z" } ``` ## ⚡ Performance & Reliability ### 🚀 High Performance - **Async Architecture**: High-performance concurrent processing across all analysis tools - **Smart Caching**: 1-hour TTL reduces API calls and improves response times - **Parallel Processing**: Simultaneous analysis across multiple threat intelligence sources - **Optimized Algorithms**: Efficient pattern matching and vulnerability detection ### 🛡️ Reliability & Resilience - **Rate Limiting**: Configurable limits (default: 60 requests/minute) with intelligent throttling - **Timeout Handling**: 30-second request timeouts prevent hanging operations - **Error Recovery**: Graceful handling of API failures and network issues - **Fallback Mechanisms**: Continues analysis even when some sources are unavailable - **Retry Logic**: Automatic retry with exponential backoff for transient failures ## 🔒 Security & Privacy ### 🛡️ Data Protection - **Zero Data Storage**: No indicators, code, or analysis results are permanently stored - **Memory-Only Processing**: All analysis happens in memory with automatic cleanup - **API Key Security**: Keys managed securely through environment variables and encrypted storage - **Source Isolation**: Each threat intelligence source operates independently with isolated credentials ### 🔐 Privacy Safeguards - **Local Processing**: Code analysis happens locally without external transmission - **Error Isolation**: Sensitive information is never exposed in error messages or logs - **Audit Trail**: Optional security event logging for compliance requirements - **Data Minimization**: Only necessary data is processed and immediately discarded ## 🧪 Testing Run the test suite to verify functionality: ```bash # Run unit tests python -m pytest tests/ -v # Test with your API keys python -c " from cyber_sentinel.server import check_api_status import asyncio print(asyncio.run(check_api_status())) " ``` ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes and add tests 4. Commit your changes (`git commit -m 'Add amazing feature'`) 5. Push to the branch (`git push origin feature/amazing-feature`) 6. Open a Pull Request ## 🆘 Support - **Issues**: [GitHub Issues](https://github.com/jx888-max/cyber-sentinel-mcp/issues) - **Documentation**: See [llms-install.md](llms-install.md) for detailed setup - **MCP Protocol**: [Model Context Protocol Documentation](https://modelcontextprotocol.io/) ## 🙏 Acknowledgments - [Anthropic](https://www.anthropic.com/) for the MCP protocol and Claude AI - [VirusTotal](https://www.virustotal.com/) for comprehensive malware analysis - [AbuseIPDB](https://www.abuseipdb.com/) for IP reputation intelligence - [URLhaus](https://urlhaus.abuse.ch/) for malware URL tracking - [Shodan](https://www.shodan.io/) for internet device intelligence - [ThreatFox](https://threatfox.abuse.ch/) for IOC sharing platform - [MalwareBazaar](https://bazaar.abuse.ch/) for malware sample intelligence - [OWASP](https://owasp.org/) for security best practices and vulnerability patterns - Open source security community for continuous threat intelligence sharing --- **🛡️ Threat Intelligence, Simplified.**