Metadata-Version: 2.4
Name: iflow-mcp_jmstar85_azure-sentinel-mcp
Version: 1.0.0
Summary: Advanced Microsoft Sentinel Threat Analysis and Automated Response System
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.9.0
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: azure-mgmt-authorization>=4.0.0
Requires-Dist: azure-mgmt-loganalytics>=12.0.0
Requires-Dist: azure-mgmt-securityinsight>=1.0.0
Requires-Dist: azure-monitor-query>=1.2.0
Requires-Dist: azure-core>=1.29.0
Requires-Dist: msal>=1.25.0
Requires-Dist: msal-extensions>=1.0.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: cachetools>=5.3.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0

# Advanced Sentinel MCP Server

Advanced Microsoft Sentinel Threat Analysis and Automated Response System

## 🎯 Key Features

### 1. Threat Intelligence Analyst 🔍
In-depth analysis and intelligence for threat events

- **MITRE ATT&CK Mapping**: Automatically map alerts/incidents to MITRE framework
- **Threat Actor Profiling**: Generate attacker profiles based on TTPs
- **IoC Extraction and Analysis**: Automatically extract and enrich threat indicators (IPs, domains, hashes, etc.)
- **Threat Context Provision**: Kill Chain stages, threat severity, response priorities

**Main Tools:**
- `threat_event_analysis`: In-depth threat event analysis
- `mitre_attack_mapping`: MITRE ATT&CK framework mapping
- `ioc_extraction`: IoC extraction and enrichment
- `threat_actor_profiling`: Threat actor profile generation

### 2. Attack Path Predictor 🎯
Machine learning-based attack path prediction and Kill Chain analysis

- **Next TTP Prediction**: Predict next attack stages based on observed techniques
- **Kill Chain Analysis**: Analyze current attack progression and completion
- **Attack Timeline Reconstruction**: Visualize attack paths through event correlation
- **Attack Velocity Analysis**: Estimate attack progression speed and time to Impact

**Main Tools:**
- `next_ttp_prediction`: ML-based next TTP prediction
- `kill_chain_analysis`: Kill Chain progress analysis
- `attack_timeline_reconstruction`: Attack timeline reconstruction

### 3. Response Coordinator 📋
Business impact assessment and response resource optimization

- **Business Impact Assessment**: Quantify business impact of incidents
- **Response Plan Generation**: Automated response playbook matching and plan generation
- **Resource Prioritization**: Determine response priorities for multiple incidents
- **SLA Management**: Set response time targets by severity

**Main Tools:**
- `business_impact_assessment`: Business impact assessment
- `response_plan_generation`: Automated response plan generation
- `resource_prioritization`: Resource prioritization

### 4. Automation Executor ⚙️
Automated response action execution and approval workflows

- **Automated Response Actions**: Host isolation, IP blocking, account disabling, etc.
- **Approval Workflow**: Risk-based approval process management
- **Playbook Execution**: Automated execution of predefined response playbooks
- **Action Tracking and Rollback**: Track execution history and rollback when needed

**Main Tools:**
- `execute_response_action`: Execute response actions
- `approve_response_action`: Approve actions
- `list_available_playbooks`: List available playbooks
- `execute_playbook`: Execute playbooks
- `rollback_action`: Rollback actions

## 🏗️ Architecture

```
sentinel-advanced-mcp/
├── server.py                      # MCP server main
├── tools/                         # MCP tools
│   ├── base.py                    # Tool base class
│   ├── threat_analyst_tools.py   # TI analysis tools
│   ├── attack_predictor_tools.py # Attack prediction tools
│   ├── response_coordinator_tools.py  # Response coordination
│   └── automation_executor_tools.py   # Automation execution
├── ml_models/                     # ML models
│   ├── ttp_predictor.py          # TTP prediction engine
│   └── attack_graph.py           # Attack graph analysis
├── intelligence/                  # Threat intelligence
│   ├── mitre_attck.py            # MITRE ATT&CK framework
│   └── ioc_enrichment.py         # IoC enrichment
├── playbooks/                     # Response playbooks
│   └── executor.py               # Playbook execution engine
└── utilities/                     # Utilities
    ├── task_manager.py           # Async task management
    └── cache.py                  # Caching
```

## 🚀 Installation and Execution

### 1. Requirements

- Python 3.10 or higher
- Azure Sentinel Workspace
- Azure Authentication (Azure CLI or Service Principal)

### 2. Installation

```bash
# Create virtual environment
python -m venv .venv

# Activate virtual environment (Windows)
.venv\Scripts\activate

# Activate virtual environment (Linux/Mac)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Environment Setup

```bash
# Copy environment variables file
cp .env.example .env

# Edit .env file (enter Azure information)
vi .env
```

**Required Environment Variables:**
```
AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_RESOURCE_GROUP=your-resource-group
AZURE_WORKSPACE_NAME=your-workspace-name
AZURE_WORKSPACE_ID=your-workspace-guid
```

### 4. Azure Authentication

**Option A: Azure CLI (Recommended for Development/Testing)**
```bash
az login
az account set --subscription your-subscription-id
```

**Option B: Service Principal (Recommended for Production)**
```bash
# Set in .env
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
```

### 5. Server Execution

```bash
python server.py
```

## 📚 Usage Examples

### Example 1: Threat Event Analysis

```python
# In-depth incident analysis
{
  "tool": "threat_event_analysis",
  "parameters": {
    "incident_number": 12345,
    "timespan": "24h"
  }
}

# Results:
# - MITRE ATT&CK mapping
# - Extracted IoC list
# - Threat summary and recommendations
```

### Example 2: Next Attack Stage Prediction

```python
# Prediction based on observed TTPs
{
  "tool": "next_ttp_prediction",
  "parameters": {
    "observed_tactics": ["TA0001", "TA0002", "TA0003"],
    "observed_techniques": ["T1566", "T1059", "T1053"],
    "time_elapsed_minutes": 120,
    "top_k": 5
  }
}

# Results:
# - Next expected tactics (with probabilities)
# - Next expected techniques (with probabilities)
# - Attack likelihood analysis
# - Defense recommendations
```

### Example 3: Response Plan Generation

```python
# Automated response plan generation
{
  "tool": "response_plan_generation",
  "parameters": {
    "incident_number": 12345,
    "auto_match": true
  }
}

# Results:
# - Matched playbooks
# - Execution plan (action list)
# - Approval requirements
# - Expected impact
```

### Example 4: Playbook Execution

```python
# Execute ransomware response playbook
{
  "tool": "execute_playbook",
  "parameters": {
    "playbook_id": "pb_ransomware_001",
    "incident_data": {
      "host": "DESKTOP-001",
      "account": "user@company.com",
      "severity": "Critical"
    },
    "auto_approve": false,
    "execute_immediately": false
  }
}

# Results:
# - Generated action list
# - Actions pending approval
# - Auto-approved actions
# - Next steps guide
```

## 🛡️ Security Considerations

### ⚠️ Important: Test Environment Only

This MCP server is designed for use in **test/development environments** only.

**Additional Considerations for Production Use:**

1. **Action Execution Permissions**: Automation Executor requires strong permissions - strict RBAC configuration essential
2. **Approval Workflow**: Critical actions must implement multi-stage approval processes
3. **Audit Logs**: Record all action execution history in separate logging system
4. **Data Exposure**: Sentinel data may contain sensitive information - consider data masking
5. **Network Isolation**: MCP server should operate in secure network segment

### Permission Requirements

**Azure Sentinel:**
- `Microsoft.OperationalInsights/workspaces/read`
- `Microsoft.OperationalInsights/workspaces/query/*/read`
- `Microsoft.SecurityInsights/*/read`

**Automation Execution (Optional):**
- `Microsoft.SecurityInsights/incidents/write`
- `Microsoft.Logic/workflows/run/action`

## 🔧 Extension and Customization

### Adding New Playbooks

```python
# Add to playbooks/executor.py

custom_playbook = ResponsePlaybook(
    playbook_id="pb_custom_001",
    name="Custom Response Playbook",
    description="Response for specific scenario",
    trigger_conditions={
        "severity": ["Critical"],
        "techniques": ["T1234"]
    },
    actions=[
        ResponseAction(
            action_id="act_custom_001",
            action_type=ActionType.BLOCK_IP,
            target="malicious_ips",
            requires_approval=False
        )
    ],
    execution_mode="semi_auto"
)
```

### Adding New Tools

```python
# tools/custom_tools.py

from tools.base import MCPToolBase

class MyCustomTool(MCPToolBase):
    name = "my_custom_tool"
    description = "Custom analysis tool"

    async def run(self, ctx: Context, **kwargs) -> Dict:
        # Implementation
        return self.wrap_result({"data": "result"})

def register_tools(mcp: FastMCP):
    MyCustomTool.register(mcp)
```

## 📊 Performance Optimization

- **Caching**: Frequently accessed data uses TTL cache (default 10 minutes)
- **Parallel Processing**: Independent queries executed in parallel
- **Query Optimization**: KQL queries select only necessary columns

## 🐛 Troubleshooting

### Authentication Errors
```bash
# Re-authenticate Azure CLI
az logout
az login
az account set --subscription your-subscription-id
```

### Query Timeouts
```python
# Increase timeout in task_manager.py
timeout=120.0  # default 60 seconds
```

### Module Import Errors
```bash
# Check Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
```

## 📝 License and Copyright

**Copyright (c) 2025 jmstar85. All rights reserved.**

This software and associated documentation files (the "Software") are the exclusive property of jmstar85. All rights, title, and interest in and to the Software are owned by jmstar85.

### Terms of Use

This project is provided for **educational and research purposes only**.

### Copyright Protection

- **Unauthorized copying, distribution, modification, or use** of this Software, in whole or in part, is strictly prohibited without explicit written permission from the copyright owner.
- Any violation of these terms may result in **legal action** and you may be subject to **civil and criminal penalties** under applicable copyright laws.
- All intellectual property rights, including but not limited to copyrights, patents, and trade secrets, remain with jmstar85.

### Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE COPYRIGHT OWNER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

For licensing inquiries or permission requests, please contact the repository owner.

## 🤝 Contributing

Feature improvements and bug fixes are welcome.

## ⚡ Roadmap

- [ ] Real-time threat monitoring dashboard
- [ ] Advanced ML model integration (LSTM, Transformer)
- [ ] External threat intelligence feed integration (VirusTotal, AbuseIPDB, etc.)
- [ ] Actual Azure Logic Apps integration
- [ ] Slack/Teams notification integration
- [ ] SIEM data visualization (Grafana)

---

**Built**: 2025
**Version**: 1.0.0
