# 🛡️ 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.**