# Azure Security MCP Agent

An AI-powered agent that uses **Model Context Protocol (MCP)** tools and a **Groq LLM** to analyze the security of your **Azure** infrastructure.

The design is inspired by the YouTube example **`yt-mcp-agent`** [`github.com/ShawhinT/yt-mcp-agent`](https://github.com/ShawhinT/yt-mcp-agent) but adapted for **cloud security** and **Azure**.

---

## Overview

This project shows how to build a security-focused AI agent that can:

- Discover resources across an Azure subscription
- Analyze Network Security Groups (NSGs) for dangerous rules
- Audit storage accounts for insecure configuration
- List public IPs and identify exposed assets
- Check basic VM security posture
- Explain risks and relate them to **CIS Azure** best practices (you can reference the included CIS PDF)

There are **three main entry points**:

- **`main.py`** – OpenAI Agents SDK + MCP tools (Groq model) – *recommended path*
- **`agent.py`** – LangChain/LangGraph ReAct-style agent using the same MCP tools
- **`demo.py`** – Offline Groq-only demo using mock Azure data (no Azure access required)

---

## Architecture

```text
┌──────────────────────────────┐
│        Groq LLM API          │   (llama-3.3-70b-versatile via OpenAI-compatible API)
└───────────────┬──────────────┘
                │
                ▼
┌─────────────────────────────────────────────┐
│  Agent Clients                              │
│  - main.py  (OpenAI Agents SDK + MCP tools) │
│  - agent.py (LangChain / LangGraph)         │
└───────────────┬─────────────────────────────┘
                │  (MCP JSON-RPC over stdio)
                ▼
┌─────────────────────────────────────────────┐
│  MCP Server (FastMCP)                       │
│  - server.py                                │
│  - exposes azure_* tools                    │
└───────────────┬─────────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────────┐
│  Azure SDK for Python                       │
│  - azure-identity / mgmt-resource/network   │
│  - mgmt-storage / mgmt-compute              │
└─────────────────────────────────────────────┘
```

---

## Key Components

- **`server.py`**  
  FastMCP-based MCP server (`FastMCP("azure-security-analyzer")`) exposing tools like:
  - `azure_list_resource_groups`
  - `azure_list_nsgs`
  - `azure_list_storage_accounts`
  - `azure_list_resources`
  - `azure_check_nsg_rules`
  - `azure_check_storage_security`
  - `azure_list_public_ips`
  - `azure_check_vm_security`  
  It also exposes a `system_prompt` via `@mcp.prompt()` that reads from `prompts/system_instructions.md`.

- **`main.py`**  
  Uses the **OpenAI Agents SDK** (`agents.Agent`, `MCPServerStdio`) to:
  - Start the MCP server (`server.py`) as a subprocess over stdio
  - Attach all MCP tools to the agent automatically
  - Use **Groq** as the model via the OpenAI-compatible API
  - Provide a simple terminal loop where you type natural-language security questions

- **`agent.py`**  
  An alternative **LangChain/LangGraph** implementation that:
  - Connects to the same MCP server
  - Wraps MCP tools into LangChain tools
  - Uses a ReAct-style graph to decide which Azure tools to call

- **`demo.py`**  
  Offline demo that feeds **mock Azure findings** (e.g. open NSG rules, insecure storage settings) into Groq and asks it to produce a security report. Useful when you don’t have real Azure access.

- **`prompts/system_instructions.md`**  
  System instructions for the agent (how to interpret tool results, severity levels, report format, etc.). You can customize this to align more strictly with the **CIS Microsoft Azure Compute Services Benchmark** (the PDF included in this repo).

---

## Prerequisites

- **Python** 3.10+
- **Azure subscription** with at least some test resources
- **Azure CLI** (`az`) for local authentication
- **Groq account + API key** (`https://console.groq.com`)
- (Optional) Basic familiarity with CIS Azure benchmarks

---

## Setup

### 1. Create and activate a virtual environment

**Windows (PowerShell)**:

```powershell
cd C:\Users\MSI\mcp_project
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

**Linux / macOS**:

```bash
cd /path/to/mcp_project
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Re-activate the venv in each new terminal before running the project.

### 2. Authenticate to Azure

```bash
az login

# (optional) select a specific subscription
az account set --subscription "YOUR-SUBSCRIPTION-ID"

# show your current subscription id
az account show --query id -o tsv
```

### 3. Configure environment variables

Create a `.env` file in the project root:

```text
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxx
AZURE_SUBSCRIPTION_ID=your-subscription-id
```

These are read by both `main.py` and `agent.py`.

---

## Running the Agent (OpenAI Agents SDK + MCP tools)

This path is closest to the **`yt-mcp-agent`** example and is the **recommended** way to use the project.

```powershell
cd C:\Users\MSI\mcp_project
.\venv\Scripts\Activate.ps1
python main.py
```

You’ll see a prompt like:

```text
=== Azure Security Agent (MCP tools + Groq) ===
Type your security query, or 'exit' to quit.

You:
```

Example questions you can ask:

- “Discover my Azure resource groups and list any NSGs with open SSH or RDP.”
- “List storage accounts in my subscription and tell me which ones violate CIS recommendations.”
- “Give me a security review of NSG rules in resource group `rg-security-demo`.”
- “Find all public IPs and summarize which services they expose.”

Behind the scenes the agent will:

1. Use MCP tools (e.g. `azure_list_resource_groups`, `azure_list_nsgs`, `azure_check_nsg_rules`)
2. Combine those results with the **system instructions** and your question
3. Ask Groq’s model to produce a structured security analysis and recommendations

---

## Alternative: LangChain / LangGraph CLI (`agent.py`)

If you want to see how the same MCP tools plug into **LangChain/LangGraph**, run:

```powershell
cd C:\Users\MSI\mcp_project
.\venv\Scripts\Activate.ps1
python agent.py
```

This script:

- Connects to the MCP server via stdio
- Wraps Azure MCP tools as LangChain tools
- Uses a ReAct-style graph to decide which tools to call and in what order

Use this when you want to experiment with chain/graph-based orchestration rather than the OpenAI Agents SDK.

---

## Offline Demo (`demo.py`)

If you don’t have Azure access or just want to see the **security reasoning** piece:

```powershell
cd C:\Users\MSI\mcp_project
.\venv\Scripts\Activate.ps1
python demo.py
```

`demo.py` feeds **mock NSG, storage, public IP, and VM findings** into Groq and asks the model to:

- Prioritize findings by severity
- Explain risks in plain language
- Suggest remediation steps (e.g. align with CIS controls)

No Azure calls or MCP server are needed for this demo, just your `GROQ_API_KEY`.

---

## MCP Tools (Server-Side Capabilities)

The MCP server (`server.py`) exposes the following tools to whichever agent you use.

**Discovery tools** (use these when you don’t know exact resource names):

1. **`azure_list_resource_groups(subscription_id)`** – List all resource groups in the subscription.
2. **`azure_list_nsgs(subscription_id, resource_group=None)`** – List NSGs across the subscription or within a specific resource group.
3. **`azure_list_storage_accounts(subscription_id, resource_group=None)`** – List storage accounts.
4. **`azure_list_resources(subscription_id, resource_group=None)`** – Generic resource inventory (name, type, location, resource group).

**Analysis tools**:

5. **`azure_check_nsg_rules(subscription_id, resource_group, nsg_name)`**  
   - Flags wildcard sources (`*`, `Internet`)
   - Detects dangerous ports (22, 3389, 1433, 3306, 5432, 27017, 6379)
   - Warns on “all ports open” (`destination_port_range="*"`)

6. **`azure_check_storage_security(subscription_id, resource_group, storage_account_name)`**  
   - Checks public blob access, HTTPS-only, TLS version, encryption status.

7. **`azure_list_public_ips(subscription_id, resource_group=None)`**  
   - Lists all public IPs, where they live, and notes that they expose resources to the internet.

8. **`azure_check_vm_security(subscription_id, resource_group, vm_name)`**  
   - Looks for missing managed identities and disk encryption issues.

The **agent** doesn’t hard-code Azure logic; it just calls these tools and reasons over their JSON outputs.

---

## What the Agent Detects (Examples)

- **Network Security**
  - Wildcard source addresses (`*`, `Internet`, `0.0.0.0/0`)
  - Open SSH/RDP/SQL ports to the internet
  - Rules that allow all ports

- **Storage Security**
  - Public blob access enabled
  - HTTPS-only not enforced
  - Weak TLS minimum version
  - Missing or misconfigured encryption

- **VM Security**
  - VMs without managed identity
  - Unencrypted OS disks (or encryption not explicitly configured)

- **Exposure & Posture**
  - Public IP inventory
  - Resource misconfigurations compared to baseline best practices

You can refine or formalize these checks against the provided **CIS Azure** PDF.

---

## Security & Best Practices

- **Do not commit `.env`** – it contains secrets.
- Run initially against **non-production** subscriptions.
- Ensure you have at least **Reader** permissions for the subscription.
- Treat the agent’s output as **advice**, not an automatic “source of truth” – always validate before making changes.

---

## Extending the Project

Ideas for next steps:

- Add more Azure services (Key Vault, SQL, App Service, AKS, etc.).
- Encode more CIS controls directly into `server.py` tools.
- Add a small web UI on top of `main.py` flows.
- Persist findings and generate trend/compliance reports.
- Add multi-cloud support (AWS, GCP) with additional MCP servers.

---

## Inspiration & References

- **Inspiration**: [`yt-mcp-agent`](https://github.com/ShawhinT/yt-mcp-agent) – YouTube analysis agent using MCP and the OpenAI Agents SDK.
- **MCP Documentation**: [`https://modelcontextprotocol.io`](https://modelcontextprotocol.io)
- **Azure SDK for Python**: [`https://learn.microsoft.com/azure/developer/python/`](https://learn.microsoft.com/azure/developer/python/)
- **Groq API Docs**: [`https://console.groq.com/docs`](https://console.groq.com/docs)
- **CIS Azure Benchmark**: [`https://www.cisecurity.org/benchmark/azure`](https://www.cisecurity.org/benchmark/azure)

---

## License

MIT – feel free to use and adapt this project for your own experiments and learning.

# Azure Security MCP Agent

An AI-powered agent for analyzing Azure infrastructure security using Model Context Protocol (MCP) and Groq's free LLM API.

## 🎯 Project Overview

This project demonstrates a simple but powerful AI agent that can:
- Discover Azure resources across your subscription
- Analyze Network Security Groups (NSGs) for misconfigurations
- Check storage account security settings
- Identify public IP exposure
- Audit VM security configurations
- Provide actionable security recommendations based on CIS benchmarks

## 🏗️ Architecture

```
┌─────────────────┐
│   Groq LLM      │  (AI Brain - Free API)
│  (llama-3.3)    │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Agent Client   │  (Orchestrates analysis)
│   (agent.py)    │
└────────┬────────┘
         │
         ↓ (MCP Protocol)
┌─────────────────┐
│   MCP Server    │  (Tools for Azure)
│   (server.py)   │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  Azure SDK      │  (Azure API calls)
│                 │
└─────────────────┘
```

## 🚀 Quick Start

### 1. Prerequisites

- Python 3.8+
- Azure subscription with resources to analyze
- Groq API key (free from https://console.groq.com)
- Azure credentials (Azure CLI recommended)

### 2. Installation (avec environnement virtuel recommandé)

**Oui, utilisez un virtual env** pour éviter les conflits de paquets.

**Windows (PowerShell ou CMD) :**

```powershell
# Aller dans le dossier du projet
cd c:\Users\MSI\mcp_project

# Créer l'environnement virtuel
python -m venv venv

# Activer le venv (PowerShell)
.\venv\Scripts\Activate.ps1

# Ou en CMD
.\venv\Scripts\activate.bat

# Installer les dépendances
pip install -r requirements.txt
```

**Linux / macOS :**

```bash
cd /chemin/vers/mcp_project
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Ensuite, à chaque nouvelle session, **réactivez le venv** avant de lancer le projet :
- Windows : `.\venv\Scripts\Activate.ps1`
- Linux/macOS : `source venv/bin/activate`

### 3. Azure Setup (Simple Test Infrastructure)

**Simplest way to prove the agent works:** Create one resource group, one NSG with one insecure rule, and one storage account with one bad setting. Then run the agent and choose **option 6 (Full discovery and security scan)** — the agent will discover everything and report the issues.

#### Option A: Using Azure Portal (Easiest for beginners)

1. **Create a Resource Group:**
   - Go to Azure Portal (portal.azure.com)
   - Click "Resource groups" → "Create"
   - Name: `rg-security-demo`
   - Region: `East US`
   - Click "Review + Create" → "Create"

2. **Create a Storage Account:**
   - Search for "Storage accounts" → "Create"
   - Resource group: `rg-security-demo`
   - Name: `secdemostorage<random>` (must be globally unique)
   - Region: `East US`
   - Performance: `Standard`
   - Redundancy: `LRS`
   - **Advanced tab:**
     - Enable "Allow Blob public access" (for testing - we'll flag this!)
     - Disable "Require secure transfer" (for testing - we'll catch this!)
   - Click "Review + Create" → "Create"

3. **Create a Network Security Group:**
   - Search for "Network security groups" → "Create"
   - Resource group: `rg-security-demo`
   - Name: `nsg-demo`
   - Region: `East US`
   - Click "Review + Create" → "Create"
   - After creation, click "Inbound security rules" → "Add"
   - Add a rule:
     - Source: `Any` (*)
     - Destination port: `22` (SSH)
     - Action: `Allow`
     - Name: `allow-ssh-any`
   - This creates a security issue for the agent to find!

4. **Create a Virtual Machine (Optional):**
   - Search for "Virtual machines" → "Create"
   - Resource group: `rg-security-demo`
   - VM name: `vm-demo`
   - Region: `East US`
   - Image: `Ubuntu Server 20.04 LTS`
   - Size: `B1s` (cheapest)
   - Authentication: SSH public key
   - Select inbound ports: SSH (22)
   - Click "Next" through tabs, then "Review + Create"

#### Option B: Using Azure CLI (Faster)

```bash
# Login to Azure
az login

# Create resource group
az group create --name rg-security-demo --location eastus

# Create storage account (intentionally insecure for demo)
az storage account create \
  --name secdemostorage$RANDOM \
  --resource-group rg-security-demo \
  --location eastus \
  --sku Standard_LRS \
  --allow-blob-public-access true \
  --https-only false

# Create NSG with insecure rule
az network nsg create \
  --resource-group rg-security-demo \
  --name nsg-demo

az network nsg rule create \
  --resource-group rg-security-demo \
  --nsg-name nsg-demo \
  --name allow-ssh-any \
  --priority 100 \
  --source-address-prefixes '*' \
  --destination-port-ranges 22 \
  --access Allow \
  --protocol Tcp

# Create public IP
az network public-ip create \
  --resource-group rg-security-demo \
  --name pip-demo
```

### 4. Configure Authentication

#### Azure CLI (Recommended)

```bash
# Login to Azure
az login

# Set your subscription
az account set --subscription "your-subscription-id"

# Verify
az account show
```

#### Environment Variables

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

# Edit .env and add your keys
nano .env
```

Add:
```
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxx
AZURE_SUBSCRIPTION_ID=your-subscription-id
```

Get your subscription ID:
```bash
az account show --query id -o tsv
```

### 5. Lancer le projet (Run the Agent)

**Résumé des étapes :**

1. **Créer et activer le virtual env** (une seule fois) :
   ```powershell
   cd c:\Users\MSI\mcp_project
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   ```

2. **Fichier `.env`** à la racine du projet avec :
   ```
   GROQ_API_KEY=gsk_xxxx
   AZURE_SUBSCRIPTION_ID=votre-subscription-id
   ```
   (Clé Groq : https://console.groq.com — Subscription ID : `az account show --query id -o tsv`)

3. **Se connecter à Azure** (dans le même terminal où vous lancez l’agent) :
   ```powershell
   az login
   ```

4. **Lancer l’agent** (avec le venv activé) :
   ```powershell
   python agent.py
   ```

5. Dans le menu, taper **6** pour un scan complet (découverte + analyse) sans saisir de noms de ressources.

**To show the agent working end-to-end:** Choose **6** (Full discovery and security scan). The agent will list resource groups, discover NSGs and storage accounts, run security checks, and return a report — no need to type resource names.

## 📋 Usage Examples

### Quick proof (no resource names needed)

1. Create a simple Azure setup: one resource group (e.g. `rg-security-demo`), one NSG with an “allow SSH from Any” rule, and one storage account with “Allow public blob access” enabled.
2. Run `python agent.py`, then choose **6** (Full discovery and security scan).
3. The agent will discover your resource groups, NSGs, and storage accounts, run security checks, and output a report with findings and recommendations.

### Example 1: Analyze NSG Rules

```
Enter command (1-5 or 'exit'): 2
Enter resource group name: rg-security-demo
Enter NSG name: nsg-demo
```

The agent will:
1. Call the `azure_check_nsg_rules` tool
2. Analyze all inbound/outbound rules
3. Flag dangerous configurations (open ports, wildcard sources)
4. Provide recommendations

### Example 2: Audit Storage Account

```
Enter command (1-5 or 'exit'): 3
Enter resource group name: rg-security-demo
Enter storage account name: secdemostorage12345
```

The agent will check:
- Public access settings
- HTTPS enforcement
- Encryption status
- TLS version

### Example 3: Custom Query

```
Enter command (1-5 or 'exit'): 5
Enter your security query: Find all resources with public access and tell me the risks
```

## 🛠️ Available Tools

The MCP server provides these tools:

**Discovery (use these first when you don’t know resource names):**
1. **azure_list_resource_groups** - List all resource groups in the subscription
2. **azure_list_nsgs** - List all NSGs (optionally in a resource group)
3. **azure_list_storage_accounts** - List all storage accounts (optionally in a resource group)
4. **azure_list_resources** - List all resources in subscription or resource group

**Analysis:**
5. **azure_check_nsg_rules** - Analyze NSG for security issues (open ports, wildcard rules)
6. **azure_check_storage_security** - Audit storage account configuration
7. **azure_list_public_ips** - Find all public IP addresses
8. **azure_check_vm_security** - Check VM security settings

## 🔍 What the Agent Detects

### Network Security
- ✓ Wildcard source addresses (*)
- ✓ Exposed dangerous ports (22, 3389, 1433, etc.)
- ✓ Overly permissive rules
- ✓ All ports open (*)

### Storage Security
- ✓ Public blob access enabled
- ✓ HTTPS-only not enforced
- ✓ Weak TLS versions
- ✓ Encryption status

### VM Security
- ✓ Missing managed identities
- ✓ Unencrypted disks
- ✓ Missing security extensions

### General
- ✓ Public IP exposure
- ✓ Resource misconfigurations
- ✓ CIS benchmark violations

## 📊 Sample Output

```
🤖 Agent analyzing: Analyze the NSG 'nsg-demo' in resource group 'rg-security-demo'

🔧 Executing: azure_check_nsg_rules
   Arguments: {
     "subscription_id": "xxxx",
     "resource_group": "rg-security-demo",
     "nsg_name": "nsg-demo"
   }
   ✓ Result: {
     "nsg_name": "nsg-demo",
     "issues_found": 2,
     "security_issues": [
       {
         "severity": "HIGH",
         "rule_name": "allow-ssh-any",
         "issue": "Inbound rule allows traffic from any source (*)",
         "destination_port": "22",
         "recommendation": "Restrict source IP addresses to specific ranges"
       },
       {
         "severity": "HIGH",
         "rule_name": "allow-ssh-any",
         "issue": "Potentially dangerous port 22 is exposed",
         "recommendation": "Consider restricting access to port 22 or using VPN/bastion"
       }
     ]
   }

============================================================
FINAL ANALYSIS
============================================================

⚠️ SECURITY ANALYSIS: NSG 'nsg-demo'

I found 2 HIGH severity security issues:

1. **Wildcard Source Address** (HIGH)
   - Rule: allow-ssh-any
   - Problem: Allows inbound traffic from ANY source (*)
   - Risk: Exposes SSH to the entire internet
   - Recommendation: Restrict to your office/home IP or use Azure Bastion

2. **Exposed SSH Port** (HIGH)
   - Port 22 is publicly accessible
   - Risk: Brute force attacks, unauthorized access attempts
   - Recommendation: Use Azure Bastion, VPN, or at minimum restrict source IPs

📋 Action Items:
- Immediately restrict the source IP range for SSH access
- Consider implementing Azure Bastion for secure VM access
- Review all NSG rules for least privilege principle
```

## 🔐 Security Best Practices

1. **Never commit `.env` file** - It contains secrets
2. **Use Azure CLI for local development** - Easiest auth method
3. **Use service principals for production** - More secure
4. **Review agent recommendations** - Human oversight is important
5. **Test on non-production first** - Always test safely

## 🚧 Extending the Agent

### Adding New Tools

Edit `server.py` and add new tool functions:

```python
@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        # ... existing tools ...
        Tool(
            name="azure_check_sql_security",
            description="Check Azure SQL database security",
            inputSchema={...}
        )
    ]

async def check_sql_security(args: dict) -> list[TextContent]:
    # Implement SQL security checks
    pass
```

### Adding More Azure Services

Install additional Azure SDK packages:
```bash
pip install azure-mgmt-sql azure-mgmt-keyvault azure-mgmt-web
```

Then add clients in `server.py`:
```python
from azure.mgmt.sql import SqlManagementClient
```

## 📝 Troubleshooting

### Nothing displays when I run `python agent.py`
- You should see at least: `Azure Security Agent — starting...` then `Starting MCP server...` then `Connecting to MCP server...`. If you see nothing at all, run from the project folder: `cd c:\Users\MSI\mcp_project` and ensure your venv is activated.
- If it stops at **Connecting to MCP server...** and hangs, the MCP handshake may be stuck (e.g. server and client waiting on each other). Try running again; if it persists, check that `server.py` runs alone: `python server.py` (it will wait for stdin — that’s normal; press Ctrl+C to exit).
- If it asks for **Azure Subscription ID**, type your subscription ID and press Enter (or add `AZURE_SUBSCRIPTION_ID` to `.env`).

### "Failed to initialize Azure clients"
- Run `az login` to authenticate
- Verify subscription ID is correct
- Check Azure permissions (Reader role minimum)

### "Error: GROQ_API_KEY not found"
- Create `.env` file from `.env.example`
- Add your Groq API key from console.groq.com

### "Resource not found"
- Verify resource names are correct
- Check you're using the right subscription
- Ensure resource group exists

### Rate Limiting
- Groq free tier: 30 requests/minute
- Add delays if needed
- Use smaller queries

## 🎯 Next Steps

1. **Add more security checks:**
   - Key Vault configuration
   - SQL database security
   - App Service settings
   - Kubernetes cluster security

2. **Implement CIS benchmarks:**
   - Azure CIS Benchmark v2.0
   - Automated compliance scoring
   - Remediation scripts

3. **Add visualization:**
   - Security score dashboard
   - Risk heat maps
   - Compliance reports

4. **Multi-cloud support:**
   - AWS security tools
   - GCP security tools
   - Cross-cloud comparison

## 📚 Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [Azure SDK for Python](https://docs.microsoft.com/en-us/azure/developer/python/)
- [Groq API Documentation](https://console.groq.com/docs)
- [CIS Azure Benchmark](https://www.cisecurity.org/benchmark/azure)

## 📄 License

MIT License - Feel free to use and modify for your project!

## 🤝 Contributing

This is a demo project for learning. Feel free to extend it for your needs!

---

**Note**: This is a simple demonstration. For production use, add:
- Error handling
- Logging
- Rate limiting
- Caching
- Comprehensive test coverage
- Remediation automation